1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
<!--
$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:
-->