postgresql/doc/src/sgml/bki.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/bki.sgml,v 1.9 2001/11/21 22:57:01 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 are input to the
  <productname>PostgreSQL</productname> backend running in the special
  <quote>bootstrap</quote> mode that allows it to perform database
  functions without a database system already existing.
  <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> from some
  specially formatted C header files in the source tree.  The created
  BKI 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.  You should also study the source
   code of <application>initdb</application> to get an idea of how the
   backend is invoked.
  </para>

  <para>
   BKI 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>BKI Commands</title>

  <variablelist>
   <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>
     create <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 <replaceable>type</replaceable> is not necessarily the data
      type that the column will have in the SQL environment; that is
      determined by the <structname>pg_attribute</structname> system
      catalog.  The type here is essentially only used to allocate
      storage.  The following types are allowed: <type>bool</type>,
      <type>bytea</type>, <type>char</type> (1 byte),
      <type>name</type>, <type>int2</type>, <type>int2vector</type>,
      <type>int4</type>, <type>regproc</type>, <type>text</type>,
      <type>oid</type>, <type>tid</type>, <type>xid</type>,
      <type>cid</type>, <type>oidvector</type>, <type>smgr</type>,
      <type>_int4</type> (array), <type>_aclitem</type> (array).
      Array types can also be indicated by writing
      <literal>[]</literal> after the name of the element type.
     </para>

     <note>
      <para>
       The table will only be created on disk, it will not
       automatically be registered in the system catalogs and will
       therefore not be accessible unless appropriate rows are
       inserted in <structname>pg_class</structname>,
       <structname>pg_attribute</structname>, etc.
      </para>
     </note>
    </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.
     </para>
    </listitem>
   </varlistentry>

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

    <listitem>
     <para>
      Build 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
   <literal>test_table</literal> table with the 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:
-->