<!-- doc/src/sgml/bki.sgml -->

<chapter id="bki">
 <title>System Catalog Declarations and Initial Contents</title>

 <para>
  <productname>PostgreSQL</productname> uses many different system catalogs
  to keep track of the existence and properties of database objects, such as
  tables and functions.  Physically there is no difference between a system
  catalog and a plain user table, but the backend C code knows the structure
  and properties of each catalog, and can manipulate it directly at a low
  level.  Thus, for example, it is inadvisable to attempt to alter the
  structure of a catalog on-the-fly; that would break assumptions built into
  the C code about how rows of the catalog are laid out.  But the structure
  of the catalogs can change between major versions.
 </para>

 <para>
  The structures of the catalogs are declared in specially formatted C
  header files in the <filename>src/include/catalog/</filename> directory of
  the source tree.  For each catalog there is a header file
  named after the catalog (e.g., <filename>pg_class.h</filename>
  for <structname>pg_class</structname>), which defines the set of columns
  the catalog has, as well as some other basic properties such as its OID.
 </para>

 <para>
  Many of the catalogs have initial data that must be loaded into them
  during the <quote>bootstrap</quote> phase
  of <application>initdb</application>, to bring the system up to a point
  where it is capable of executing SQL commands.  (For
  example, <filename>pg_class.h</filename> must contain an entry for itself,
  as well as one for each other system catalog and index.)  This
  initial data is kept in editable form in data files that are also stored
  in the <filename>src/include/catalog/</filename> directory.  For example,
  <filename>pg_proc.dat</filename> describes all the initial rows that must
  be inserted into the <structname>pg_proc</structname> catalog.
 </para>

 <para>
  To create the catalog files and load this initial data into them, a
  backend running in bootstrap mode reads a <acronym>BKI</acronym>
  (Backend Interface) file containing commands and initial data.
  The <filename>postgres.bki</filename> file used in this mode is prepared
  from the aforementioned header and data files, while building
  a <productname>PostgreSQL</productname> distribution, by a Perl script
  named <filename>genbki.pl</filename>.
  Although it's specific to a particular <productname>PostgreSQL</productname>
  release, <filename>postgres.bki</filename> is platform-independent and is
  installed in the <filename>share</filename> subdirectory of the
  installation tree.
 </para>

 <para>
  <filename>genbki.pl</filename> also produces a derived header file for
  each catalog, for example <filename>pg_class_d.h</filename> for
  the <structname>pg_class</structname> catalog.  This file contains
  automatically-generated macro definitions, and may contain other macros,
  enum declarations, and so on that can be useful for client C code that
  reads a particular catalog.
 </para>

 <para>
  Most PostgreSQL developers don't need to be directly concerned with
  the <acronym>BKI</acronym> file, but almost any nontrivial feature
  addition in the backend will require modifying the catalog header files
  and/or initial data files.  The rest of this chapter gives some
  information about that, and for completeness describes
  the <acronym>BKI</acronym> file format.
 </para>

 <sect1 id="system-catalog-declarations">
  <title>System Catalog Declaration Rules</title>

  <para>
   The key part of a catalog header file is a C structure definition
   describing the layout of each row of the catalog.  This begins with
   a <literal>CATALOG</literal> macro, which so far as the C compiler is
   concerned is just shorthand for <literal>typedef struct
   FormData_<replaceable>catalogname</replaceable></literal>.
   Each field in the struct gives rise to a catalog column.
   Fields can be annotated using the BKI property macros described