mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-30 20:21:15 +02:00
64737e9313
pg_attribute, by having genbki.pl derive the information from the various catalog header files. This greatly simplifies modification of the "bootstrapped" catalogs. This patch finally kills genbki.sh and Gen_fmgrtab.sh; we now rely entirely on Perl scripts for those build steps. To avoid creating a Perl build dependency where there was not one before, the output files generated by these scripts are now treated as distprep targets, ie, they will be built and shipped in tarballs. But you will need a reasonably modern Perl (probably at least 5.6) if you want to build from a CVS pull. The changes to the MSVC build process are untested, and may well break --- we'll soon find out from the buildfarm. John Naylor, based on ideas from Robert Haas and others
358 lines
12 KiB
Plaintext
358 lines
12 KiB
Plaintext
<!-- $PostgreSQL: pgsql/doc/src/sgml/bki.sgml,v 1.23 2010/01/05 01:06:55 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.pl</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 can 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 <literal>#</literal> are ignored.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="bki-commands">
|
|
<title><acronym>BKI</acronym> Commands</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>create</>
|
|
<replaceable class="parameter">tablename</replaceable>
|
|
<replaceable class="parameter">tableoid</replaceable>
|
|
<optional><literal>bootstrap</></optional>
|
|
<optional><literal>shared_relation</></optional>
|
|
<optional><literal>without_oids</></optional>
|
|
<optional><literal>rowtype_oid</> <replaceable>oid</></optional>
|
|
(<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>, and having the OID
|
|
<replaceable class="parameter">tableoid</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>_oid</type> (array), <type>_char</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. (That effectively means that only these
|
|
column types can be used in bootstrapped tables, but non-bootstrap
|
|
catalogs can contain any built-in type.)
|
|
</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.
|
|
The table's rowtype OID (<structname>pg_type</> OID) can optionally
|
|
be specified via the <literal>rowtype_oid</> clause; if not specified,
|
|
an OID is automatically generated for it. (The <literal>rowtype_oid</>
|
|
clause is useless if <literal>bootstrap</> is specified, but it can be
|
|
provided anyway for documentation.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<literal>open</> <replaceable class="parameter">tablename</replaceable>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Open the table named
|
|
<replaceable class="parameter">tablename</replaceable>
|
|
for insertion of data. Any currently open table is closed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<literal>close</> <optional><replaceable class="parameter">tablename</replaceable></optional>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Close the open table. The name of the table can be given as a
|
|
cross-check, but this is not required.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<literal>insert</> <optional><literal>OID =</> <replaceable class="parameter">oid_value</replaceable></optional> <literal>(</> <replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ... <literal>)</>
|
|
</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, and the table has OIDs, then the
|
|
next available OID is assigned.
|
|
</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>
|
|
<literal>declare</> <optional><literal>unique</></optional>
|
|
<literal>index</> <replaceable class="parameter">indexname</replaceable>
|
|
<replaceable class="parameter">indexoid</replaceable>
|
|
<literal>on</> <replaceable class="parameter">tablename</replaceable>
|
|
<literal>using</> <replaceable class="parameter">amname</replaceable>
|
|
<literal>(</> <replaceable class="parameter">opclass1</replaceable>
|
|
<replaceable class="parameter">name1</replaceable>
|
|
<optional>, ...</optional> <literal>)</>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Create an index named <replaceable
|
|
class="parameter">indexname</replaceable>, having OID
|
|
<replaceable class="parameter">indexoid</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>
|
|
<literal>declare toast</>
|
|
<replaceable class="parameter">toasttableoid</replaceable>
|
|
<replaceable class="parameter">toastindexoid</replaceable>
|
|
<literal>on</> <replaceable class="parameter">tablename</replaceable>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Create a TOAST table for the table named
|
|
<replaceable class="parameter">tablename</replaceable>.
|
|
The TOAST table is assigned OID
|
|
<replaceable class="parameter">toasttableoid</replaceable>
|
|
and its index is assigned OID
|
|
<replaceable class="parameter">toastindexoid</replaceable>.
|
|
As with <literal>declare index</>, filling of the index
|
|
is postponed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal>build indices</></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Fill in the indices that have previously been declared.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="bki-structure">
|
|
<title>Structure of the Bootstrap <acronym>BKI</acronym> File</title>
|
|
|
|
<para>
|
|
The <literal>open</> command cannot be used until the tables it uses
|
|
exist and have entries for the table that is to be opened.
|
|
(These minimum tables are <structname>pg_class</>,
|
|
<structname>pg_attribute</>, <structname>pg_proc</>, and
|
|
<structname>pg_type</>.) To allow those tables themselves to be filled,
|
|
<literal>create</> with the <literal>bootstrap</> option implicitly opens
|
|
the created table for data insertion.
|
|
</para>
|
|
|
|
<para>
|
|
Also, the <literal>declare index</> and <literal>declare toast</>
|
|
commands cannot be used until the system catalogs they need have been
|
|
created and filled in.
|
|
</para>
|
|
|
|
<para>
|
|
Thus, the structure of the <filename>postgres.bki</filename> file has to
|
|
be:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>create bootstrap</> one of the critical tables
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>insert</> data describing at least the critical tables
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>close</>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Repeat for the other critical tables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>create</> (without <literal>bootstrap</>) a noncritical table
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>open</>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>insert</> desired data
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>close</>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Repeat for the other noncritical tables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Define indexes and toast tables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>build indices</>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
There are doubtless other, undocumented ordering dependencies.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="bki-example">
|
|
<title>Example</title>
|
|
|
|
<para>
|
|
The following sequence of commands will create the
|
|
table <literal>test_table</literal> with OID 420, having 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 420 (cola = int4, colb = text)
|
|
open test_table
|
|
insert OID=421 ( 1 "value1" )
|
|
insert OID=422 ( 2 _null_ )
|
|
close test_table
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|