path: root/doc/src/sgml/bki.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.13 2005/01/05 23:42:03 tgl Exp $
 -->

<chapter id="bki">
 <title><acronym>BKI</acronym> Backend Interface</title>

 <para>
  Backend Interface (<acronym>BKI</acronym>) files are scripts in a
  special language that is understood by the
  <productname>PostgreSQL</productname> backend when running in the
  <quote>bootstrap</quote> mode.  The bootstrap mode allows system catalogs
  to be created and filled from scratch, whereas ordinary SQL commands
  require the catalogs to exist already.
  <acronym>BKI</acronym> files can therefore be used to create the
  database system in the first place.  (And they are probably not
  useful for anything else.)
 </para>

 <para>
  <application>initdb</application> uses a <acronym>BKI</acronym> file
  to do part of its job when creating a new database cluster.  The
  input file used by <application>initdb</application> is created as
  part of building and installing <productname>PostgreSQL</productname>
  by a program named <filename>genbki.sh</filename>, which reads some
  specially formatted C header files in the <filename>src/include/catalog/</>
  directory of the source tree.  The created
  <acronym>BKI</acronym> file is called <filename>postgres.bki</filename> and is
  normally installed in the
  <filename>share</filename> subdirectory of the installation tree.
 </para>

 <para>
  Related information may be found in the documentation for
  <application>initdb</application>.
 </para>

 <sect1 id="bki-format">
  <title><acronym>BKI</acronym> File Format</title>

  <para>
   This section describes how the <productname>PostgreSQL</productname>
   backend interprets <acronym>BKI</acronym> files.  This description
   will be easier to understand if the <filename>postgres.bki</filename>
   file is at hand as an example.
  </para>

  <para>
   <acronym>BKI</acronym> input consists of a sequence of commands.  Commands are made up
   of a number of tokens, depending on the syntax of the command.
   Tokens are usually separated by whitespace, but need not be if
   there is no ambiguity.  There is no special command separator; the
   next token that syntactically cannot belong to the preceding
   command starts a new one.  (Usually you would put a new command on
   a new line, for clarity.)  Tokens can be certain key words, special
   characters (parentheses, commas, etc.), numbers, or double-quoted
   strings.  Everything is case sensitive.
  </para>

  <para>
   Lines starting with a <literal>#</literal> are ignored.
  </para>

 </sect1>

 <sect1 id="bki-commands">
  <title><acronym>BKI</acronym> Commands</title>

  <variablelist>
   <varlistentry>
    <term>
     create 
     <optional>bootstrap</optional>
     <optional>shared_relation</optional>
     <optional>without_oids</optional>
     <replaceable class="parameter">tablename</replaceable>
     (<replaceable class="parameter">name1</replaceable> =
     <replaceable class="parameter">type1</replaceable> <optional>,
     <replaceable class="parameter">name2</replaceable> = <replaceable
     class="parameter">type2</replaceable>, ...</optional>)
    </term>

    <listitem>
     <para>
      Create a table named <replaceable
      class="parameter">tablename</replaceable> with the columns given
      in parentheses.
     </para>

     <para>
      The following column types are supported directly by
      <filename>bootstrap.c</>: <type>bool</type>,
      <type>bytea</type>, <type>char</type> (1 byte),
      <type>name</type>, <type>int2</type>,
      <type>int4</type>, <type>regproc</type>, <type>regclass</type>,
      <type>regtype</type>, <type>text</type>,
      <type>oid</type>, <type>tid</type>, <type>xid</type>,
      <type>cid</type>, <type>int2vector</type>, <type>oidvector</type>,
      <type>_int4</type> (array), <type>_text</type> (array),
      <type>_aclitem</type> (array).  Although it is possible to create
      tables containing columns of other types, this cannot be done until
      after <structname>pg_type</> has been created and filled with
      appropriate entries.
     </para>

     <para>
      When <literal>bootstrap</> is specified,
      the table will only be created on disk; nothing is entered into
      <structname>pg_class</structname>,
      <structname>pg_attribute</structname>, etc, for it.  Thus the
      table will not be accessible by ordinary SQL operations until
      such entries are made the hard way (with <literal>insert</>
      commands).  This option is used for creating
      <structname>pg_class</structname> etc themselves.
     </para>

     <para>
      The table is created as shared if <literal>shared_relation</> is
      specified.
      It will have OIDs unless <literal>without_oids</> is specified.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     open <replaceable class="parameter">tablename</replaceable>
    </term>

    <listitem>
     <para>
      Open the table called
      <replaceable class="parameter">tablename</replaceable>
      for further manipulation.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     close <optional><replaceable class="parameter">tablename</replaceable></optional>
    </term>

    <listitem>
     <para>
      Close the open table called <replaceable
      class="parameter">tablename</replaceable>.  It is an error if
      <replaceable class="parameter">tablename</replaceable> is not
      already opened.  If no <replaceable
      class="parameter">tablename</replaceable> is given, then the
      currently open table is closed.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     insert <optional>OID = <replaceable class="parameter">oid_value</replaceable></optional> (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...)
    </term>

    <listitem>
     <para>
      Insert a new row into the open table using <replaceable
      class="parameter">value1</replaceable>, <replaceable
      class="parameter">value2</replaceable>, etc., for its column
      values and <replaceable
      class="parameter">oid_value</replaceable> for its OID.  If
      <replaceable class="parameter">oid_value</replaceable> is zero
      (0) or the clause is omitted, then the next available OID is
      used.
     </para>

     <para>
      NULL values can be specified using the special key word
      <literal>_null_</literal>.  Values containing spaces must be
      double quoted.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     declare <optional>unique</optional> index <replaceable
     class="parameter">indexname</replaceable> on <replaceable
     class="parameter">tablename</replaceable> using <replaceable
     class="parameter">amname</replaceable> (<replaceable
     class="parameter">opclass1</replaceable> <replaceable
     class="parameter">name1</replaceable> <optional>, ...</optional>)
    </term>

    <listitem>
     <para>
      Create an index named <replaceable
      class="parameter">indexname</replaceable> on the table named
      <replaceable class="parameter">tablename</replaceable> using the
      <replaceable class="parameter">amname</replaceable> access
      method.  The fields to index are called <replaceable
      class="parameter">name1</replaceable>, <replaceable
      class="parameter">name2</replaceable> etc., and the operator
      classes to use are <replaceable
      class="parameter">opclass1</replaceable>, <replaceable
      class="parameter">opclass2</replaceable> etc., respectively.
      The index file is created and appropriate catalog entries are
      made for it, but the index contents are not initialized by this command.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>build indices</term>

    <listitem>
     <para>
      Fill in the indices that have previously been declared.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

 </sect1>

 <sect1 id="bki-example">
  <title>Example</title>

  <para>
   The following sequence of commands will create the
   table <literal>test_table</literal> with two columns
   <literal>cola</literal> and <literal>colb</literal> of type
   <type>int4</type> and <type>text</type>, respectively, and insert
   two rows into the table.
<programlisting>
create test_table (cola = int4, colb = text)
open test_table
insert OID=421 ( 1 "value1" )
insert OID=422 ( 2 _null_ )
close test_table
</programlisting>
  </para>
 </sect1>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->