doc/src/sgml/bki.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <chapter id="bki">
   4  <title><acronym>BKI</acronym> Backend Interface</title>
   5
   6  <para>
   7   Backend Interface (<acronym>BKI</acronym>) files are scripts in a
   8   special language that is understood by the
   9   <productname>PostgreSQL</productname> backend when running in the
  10   <quote>bootstrap</quote> mode.  The bootstrap mode allows system catalogs
  11   to be created and filled from scratch, whereas ordinary SQL commands
  12   require the catalogs to exist already.
  13   <acronym>BKI</acronym> files can therefore be used to create the
  14   database system in the first place.  (And they are probably not
  15   useful for anything else.)
  16  </para>
  17
  18  <para>
  19   <application>initdb</application> uses a <acronym>BKI</acronym> file
  20   to do part of its job when creating a new database cluster.  The
  21   input file used by <application>initdb</application> is created as
  22   part of building and installing <productname>PostgreSQL</productname>
  23   by a program named <filename>genbki.sh</filename>, which reads some
  24   specially formatted C header files in the <filename>src/include/catalog/</>
  25   directory of the source tree.  The created
  26   <acronym>BKI</acronym> file is called <filename>postgres.bki</filename> and is
  27   normally installed in the
  28   <filename>share</filename> subdirectory of the installation tree.
  29  </para>
  30
  31  <para>
  32   Related information can be found in the documentation for
  33   <application>initdb</application>.
  34  </para>
  35
  36  <sect1 id="bki-format">
  37   <title><acronym>BKI</acronym> File Format</title>
  38
  39   <para>
  40    This section describes how the <productname>PostgreSQL</productname>
  41    backend interprets <acronym>BKI</acronym> files.  This description
  42    will be easier to understand if the <filename>postgres.bki</filename>
  43    file is at hand as an example.
  44   </para>
  45
  46   <para>
  47    <acronym>BKI</acronym> input consists of a sequence of commands.  Commands are made up
  48    of a number of tokens, depending on the syntax of the command.
  49    Tokens are usually separated by whitespace, but need not be if
  50    there is no ambiguity.  There is no special command separator; the
  51    next token that syntactically cannot belong to the preceding
  52    command starts a new one.  (Usually you would put a new command on
  53    a new line, for clarity.)  Tokens can be certain key words, special
  54    characters (parentheses, commas, etc.), numbers, or double-quoted
  55    strings.  Everything is case sensitive.
  56   </para>
  57
  58   <para>
  59    Lines starting with <literal>#</literal> are ignored.
  60   </para>
  61
  62  </sect1>
  63
  64  <sect1 id="bki-commands">
  65   <title><acronym>BKI</acronym> Commands</title>
  66
  67   <variablelist>
  68    <varlistentry>
  69     <term>
  70      <literal>create</>
  71      <optional><literal>bootstrap</></optional>
  72      <optional><literal>shared_relation</></optional>
  73      <optional><literal>without_oids</></optional>
  74      <replaceable class="parameter">tablename</replaceable>
  75      <replaceable class="parameter">tableoid</replaceable>
  76      (<replaceable class="parameter">name1</replaceable> =
  77      <replaceable class="parameter">type1</replaceable> <optional>,
  78      <replaceable class="parameter">name2</replaceable> = <replaceable
  79      class="parameter">type2</replaceable>, ...</optional>)
  80     </term>
  81
  82     <listitem>
  83      <para>
  84       Create a table named <replaceable
  85       class="parameter">tablename</replaceable>, and having the OID
  86       <replaceable class="parameter">tableoid</replaceable>,
  87       with the columns given in parentheses.
  88      </para>
  89
  90      <para>
  91       The following column types are supported directly by
  92       <filename>bootstrap.c</>: <type>bool</type>,
  93       <type>bytea</type>, <type>char</type> (1 byte),
  94       <type>name</type>, <type>int2</type>,
  95       <type>int4</type>, <type>regproc</type>, <type>regclass</type>,
  96       <type>regtype</type>, <type>text</type>,
  97       <type>oid</type>, <type>tid</type>, <type>xid</type>,
  98       <type>cid</type>, <type>int2vector</type>, <type>oidvector</type>,
  99       <type>_int4</type> (array), <type>_text</type> (array),
 100       <type>_oid</type> (array), <type>_char</type> (array),
 101       <type>_aclitem</type> (array).  Although it is possible to create
 102       tables containing columns of other types, this cannot be done until
 103       after <structname>pg_type</> has been created and filled with
 104       appropriate entries.  (That effectively means that only these
 105       column types can be used in bootstrapped tables, but non-bootstrap
 106       catalogs can contain any built-in type.)
 107      </para>
 108
 109      <para>
 110       When <literal>bootstrap</> is specified,
 111       the table will only be created on disk; nothing is entered into
 112       <structname>pg_class</structname>,
 113       <structname>pg_attribute</structname>, etc, for it.  Thus the
 114       table will not be accessible by ordinary SQL operations until
 115       such entries are made the hard way (with <literal>insert</>
 116       commands).  This option is used for creating
 117       <structname>pg_class</structname> etc themselves.
 118      </para>
 119
 120      <para>
 121       The table is created as shared if <literal>shared_relation</> is
 122       specified.
 123       It will have OIDs unless <literal>without_oids</> is specified.
 124      </para>
 125     </listitem>
 126    </varlistentry>
 127
 128    <varlistentry>
 129     <term>
 130      <literal>open</> <replaceable class="parameter">tablename</replaceable>
 131     </term>
 132
 133     <listitem>
 134      <para>
 135       Open the table named
 136       <replaceable class="parameter">tablename</replaceable>
 137       for insertion of data.  Any currently open table is closed.
 138      </para>
 139     </listitem>
 140    </varlistentry>
 141
 142    <varlistentry>
 143     <term>
 144      <literal>close</> <optional><replaceable class="parameter">tablename</replaceable></optional>
 145     </term>
 146
 147     <listitem>
 148      <para>
 149       Close the open table.  The name of the table can be given as a
 150       cross-check, but this is not required.
 151      </para>
 152     </listitem>
 153    </varlistentry>
 154
 155    <varlistentry>
 156     <term>
 157      <literal>insert</> <optional><literal>OID =</> <replaceable class="parameter">oid_value</replaceable></optional> <literal>(</> <replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ... <literal>)</>
 158     </term>
 159
 160     <listitem>
 161      <para>
 162       Insert a new row into the open table using <replaceable
 163       class="parameter">value1</replaceable>, <replaceable
 164       class="parameter">value2</replaceable>, etc., for its column
 165       values and <replaceable
 166       class="parameter">oid_value</replaceable> for its OID.  If
 167       <replaceable class="parameter">oid_value</replaceable> is zero
 168       (0) or the clause is omitted, and the table has OIDs, then the
 169       next available OID is assigned.
 170      </para>
 171
 172      <para>
 173       NULL values can be specified using the special key word
 174       <literal>_null_</literal>.  Values containing spaces must be
 175       double quoted.
 176      </para>
 177     </listitem>
 178    </varlistentry>
 179
 180    <varlistentry>
 181     <term>
 182      <literal>declare</> <optional><literal>unique</></optional>
 183      <literal>index</> <replaceable class="parameter">indexname</replaceable>
 184      <replaceable class="parameter">indexoid</replaceable>
 185      <literal>on</> <replaceable class="parameter">tablename</replaceable>
 186      <literal>using</> <replaceable class="parameter">amname</replaceable>
 187      <literal>(</> <replaceable class="parameter">opclass1</replaceable>
 188      <replaceable class="parameter">name1</replaceable>
 189      <optional>, ...</optional> <literal>)</>
 190     </term>
 191
 192     <listitem>
 193      <para>
 194       Create an index named <replaceable
 195       class="parameter">indexname</replaceable>, having OID
 196       <replaceable class="parameter">indexoid</replaceable>,
 197       on the table named
 198       <replaceable class="parameter">tablename</replaceable>, using the
 199       <replaceable class="parameter">amname</replaceable> access
 200       method.  The fields to index are called <replaceable
 201       class="parameter">name1</replaceable>, <replaceable
 202       class="parameter">name2</replaceable> etc., and the operator
 203       classes to use are <replaceable
 204       class="parameter">opclass1</replaceable>, <replaceable
 205       class="parameter">opclass2</replaceable> etc., respectively.
 206       The index file is created and appropriate catalog entries are
 207       made for it, but the index contents are not initialized by this command.
 208      </para>
 209     </listitem>
 210    </varlistentry>
 211
 212    <varlistentry>
 213     <term>
 214      <literal>declare toast</>
 215      <replaceable class="parameter">toasttableoid</replaceable>
 216      <replaceable class="parameter">toastindexoid</replaceable>
 217      <literal>on</> <replaceable class="parameter">tablename</replaceable>
 218     </term>
 219
 220     <listitem>
 221      <para>
 222       Create a TOAST table for the table named
 223       <replaceable class="parameter">tablename</replaceable>.
 224       The TOAST table is assigned OID
 225       <replaceable class="parameter">toasttableoid</replaceable>
 226       and its index is assigned OID
 227       <replaceable class="parameter">toastindexoid</replaceable>.
 228       As with <literal>declare index</>, filling of the index
 229       is postponed.
 230      </para>
 231     </listitem>
 232    </varlistentry>
 233
 234    <varlistentry>
 235     <term><literal>build indices</></term>
 236
 237     <listitem>
 238      <para>
 239       Fill in the indices that have previously been declared.
 240      </para>
 241     </listitem>
 242    </varlistentry>
 243   </variablelist>
 244
 245  </sect1>
 246
 247  <sect1 id="bki-structure">
 248   <title>Structure of the Bootstrap <acronym>BKI</acronym> File</title>
 249
 250   <para>
 251    The <literal>open</> command cannot be used until the tables it uses
 252    exist and have entries for the table that is to be opened.
 253    (These minimum tables are <structname>pg_class</>,
 254    <structname>pg_attribute</>, <structname>pg_proc</>, and
 255    <structname>pg_type</>.)   To allow those tables themselves to be filled,
 256    <literal>create</> with the <literal>bootstrap</> option implicitly opens
 257    the created table for data insertion.
 258   </para>
 259
 260   <para>
 261    Also, the <literal>declare index</> and <literal>declare toast</>
 262    commands cannot be used until the system catalogs they need have been
 263    created and filled in.
 264   </para>
 265
 266   <para>
 267    Thus, the structure of the <filename>postgres.bki</filename> file has to
 268    be:
 269    <orderedlist>
 270     <listitem>
 271      <para>
 272       <literal>create bootstrap</> one of the critical tables
 273      </para>
 274     </listitem>
 275     <listitem>
 276      <para>
 277       <literal>insert</> data describing at least the critical tables
 278      </para>
 279     </listitem>
 280     <listitem>
 281      <para>
 282       <literal>close</>
 283      </para>
 284     </listitem>
 285     <listitem>
 286      <para>
 287       Repeat for the other critical tables.
 288      </para>
 289     </listitem>
 290     <listitem>
 291      <para>
 292       <literal>create</> (without <literal>bootstrap</>) a noncritical table
 293      </para>
 294     </listitem>
 295     <listitem>
 296      <para>
 297       <literal>open</>
 298      </para>
 299     </listitem>
 300     <listitem>
 301      <para>
 302       <literal>insert</> desired data
 303      </para>
 304     </listitem>
 305     <listitem>
 306      <para>
 307       <literal>close</>
 308      </para>
 309     </listitem>
 310     <listitem>
 311      <para>
 312       Repeat for the other noncritical tables.
 313      </para>
 314     </listitem>
 315     <listitem>
 316      <para>
 317       Define indexes and toast tables.
 318      </para>
 319     </listitem>
 320     <listitem>
 321      <para>
 322       <literal>build indices</>
 323      </para>
 324     </listitem>
 325    </orderedlist>
 326   </para>
 327
 328   <para>
 329    There are doubtless other, undocumented ordering dependencies.
 330   </para>
 331  </sect1>
 332
 333  <sect1 id="bki-example">
 334   <title>Example</title>
 335
 336   <para>
 337    The following sequence of commands will create the
 338    table <literal>test_table</literal> with OID 420, having two columns
 339    <literal>cola</literal> and <literal>colb</literal> of type
 340    <type>int4</type> and <type>text</type>, respectively, and insert
 341    two rows into the table:
 342 <programlisting>
 343 create test_table 420 (cola = int4, colb = text)
 344 open test_table
 345 insert OID=421 ( 1 "value1" )
 346 insert OID=422 ( 2 _null_ )
 347 close test_table
 348 </programlisting>
 349   </para>
 350  </sect1>
 351 </chapter>