BKI Backend Interface
Backend Interface (BKI) files are scripts in a
special language that is understood by the
PostgreSQL backend when running in the
bootstrap
mode. The bootstrap mode allows system catalogs
to be created and filled from scratch, whereas ordinary SQL commands
require the catalogs to exist already.
BKI files can therefore be used to create the
database system in the first place. (And they are probably not
useful for anything else.)
initdb uses a BKI file
to do part of its job when creating a new database cluster. The
input file used by initdb is created as
part of building and installing PostgreSQL
by a program named genbki.pl, which reads some
specially formatted C header files in the src/include/catalog/>
directory of the source tree. The created BKI file
is called postgres.bki and is
normally installed in the
share subdirectory of the installation tree.
Related information can be found in the documentation for
initdb.
BKI File Format
This section describes how the PostgreSQL
backend interprets BKI files. This description
will be easier to understand if the postgres.bki
file is at hand as an example.
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.
Lines starting with # are ignored.
BKI Commands
create>
tablename
tableoid
bootstrap>
shared_relation>
without_oids>
rowtype_oid> oid>
(name1 =
type1 ,
name2 = type2, ...)
Create a table named tablename, and having the OID
tableoid,
with the columns given in parentheses.
The following column types are supported directly by
bootstrap.c>: bool,
bytea, char (1 byte),
name, int2,
int4, regproc, regclass,
regtype, text,
oid, tid, xid,
cid, int2vector, oidvector,
_int4 (array), _text (array),
_oid (array), _char (array),
_aclitem (array). Although it is possible to create
tables containing columns of other types, this cannot be done until
after 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.)
When bootstrap> is specified,
the table will only be created on disk; nothing is entered into
pg_class,
pg_attribute, etc, for it. Thus the
table will not be accessible by ordinary SQL operations until
such entries are made the hard way (with insert>
commands). This option is used for creating
pg_class etc themselves.
The table is created as shared if shared_relation> is
specified.
It will have OIDs unless without_oids> is specified.
The table's rowtype OID (pg_type> OID) can optionally
be specified via the rowtype_oid> clause; if not specified,
an OID is automatically generated for it. (The rowtype_oid>
clause is useless if bootstrap> is specified, but it can be
provided anyway for documentation.)
open> tablename
Open the table named
tablename
for insertion of data. Any currently open table is closed.
close> tablename
Close the open table. The name of the table can be given as a
cross-check, but this is not required.
insert> OID => oid_value (> value1 value2 ... )>
Insert a new row into the open table using value1, value2, etc., for its column
values and oid_value for its OID. If
oid_value is zero
(0) or the clause is omitted, and the table has OIDs, then the
next available OID is assigned.
NULL values can be specified using the special key word
_null_. Values containing spaces must be
double quoted.
declare> unique>
index> indexname
indexoid
on> tablename
using> amname
(> opclass1
name1
, ... )>
Create an index named indexname, having OID
indexoid,
on the table named
tablename, using the
amname access
method. The fields to index are called name1, name2 etc., and the operator
classes to use are opclass1, opclass2 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.
declare toast>
toasttableoid
toastindexoid
on> tablename
Create a TOAST table for the table named
tablename.
The TOAST table is assigned OID
toasttableoid
and its index is assigned OID
toastindexoid.
As with declare index>, filling of the index
is postponed.
build indices>
Fill in the indices that have previously been declared.
Structure of the Bootstrap BKI File
The 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 pg_class>,
pg_attribute>, pg_proc>, and
pg_type>.) To allow those tables themselves to be filled,
create> with the bootstrap> option implicitly opens
the created table for data insertion.
Also, the declare index> and declare toast>
commands cannot be used until the system catalogs they need have been
created and filled in.
Thus, the structure of the postgres.bki file has to
be:
create bootstrap> one of the critical tables
insert> data describing at least the critical tables
close>
Repeat for the other critical tables.
create> (without bootstrap>) a noncritical table
open>
insert> desired data
close>
Repeat for the other noncritical tables.
Define indexes and toast tables.
build indices>
There are doubtless other, undocumented ordering dependencies.
Example
The following sequence of commands will create the
table test_table with OID 420, having two columns
cola and colb of type
int4 and text, respectively, and insert
two rows into the table:
create test_table 420 (cola = int4, colb = text)
open test_table
insert OID=421 ( 1 "value1" )
insert OID=422 ( 2 _null_ )
close test_table