begriffs open source - ai-pg/blob - full-docs/txt/bki.txt

   1
   2 Chapter 68. System Catalog Declarations and Initial Contents
   3
   4    Table of Contents
   5
   6    68.1. System Catalog Declaration Rules
   7    68.2. System Catalog Initial Data
   8
   9         68.2.1. Data File Format
  10         68.2.2. OID Assignment
  11         68.2.3. OID Reference Lookup
  12         68.2.4. Automatic Creation of Array Types
  13         68.2.5. Recipes for Editing Data Files
  14
  15    68.3. BKI File Format
  16    68.4. BKI Commands
  17    68.5. Structure of the Bootstrap BKI File
  18    68.6. BKI Example
  19
  20    PostgreSQL uses many different system catalogs to keep track of the
  21    existence and properties of database objects, such as tables and
  22    functions. Physically there is no difference between a system catalog
  23    and a plain user table, but the backend C code knows the structure and
  24    properties of each catalog, and can manipulate it directly at a low
  25    level. Thus, for example, it is inadvisable to attempt to alter the
  26    structure of a catalog on-the-fly; that would break assumptions built
  27    into the C code about how rows of the catalog are laid out. But the
  28    structure of the catalogs can change between major versions.
  29
  30    The structures of the catalogs are declared in specially formatted C
  31    header files in the src/include/catalog/ directory of the source tree.
  32    For each catalog there is a header file named after the catalog (e.g.,
  33    pg_class.h for pg_class), which defines the set of columns the catalog
  34    has, as well as some other basic properties such as its OID.
  35
  36    Many of the catalogs have initial data that must be loaded into them
  37    during the “bootstrap” phase of initdb, to bring the system up to a
  38    point where it is capable of executing SQL commands. (For example,
  39    pg_class.h must contain an entry for itself, as well as one for each
  40    other system catalog and index.) This initial data is kept in editable
  41    form in data files that are also stored in the src/include/catalog/
  42    directory. For example, pg_proc.dat describes all the initial rows that
  43    must be inserted into the pg_proc catalog.
  44
  45    To create the catalog files and load this initial data into them, a
  46    backend running in bootstrap mode reads a BKI (Backend Interface) file
  47    containing commands and initial data. The postgres.bki file used in
  48    this mode is prepared from the aforementioned header and data files,
  49    while building a PostgreSQL distribution, by a Perl script named
  50    genbki.pl. Although it's specific to a particular PostgreSQL release,
  51    postgres.bki is platform-independent and is installed in the share
  52    subdirectory of the installation tree.
  53
  54    genbki.pl also produces a derived header file for each catalog, for
  55    example pg_class_d.h for the pg_class catalog. This file contains
  56    automatically-generated macro definitions, and may contain other
  57    macros, enum declarations, and so on that can be useful for client C
  58    code that reads a particular catalog.
  59
  60    Most PostgreSQL developers don't need to be directly concerned with the
  61    BKI file, but almost any nontrivial feature addition in the backend
  62    will require modifying the catalog header files and/or initial data
  63    files. The rest of this chapter gives some information about that, and
  64    for completeness describes the BKI file format.