← Back to branch summary

~ubuntu-branches/ubuntu/natty/postgresql-8.4/natty-updates

« back to all changes in this revision

Viewing changes to doc/src/sgml/bki.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-03-20 12:00:13 UTC
  • Revision ID: james.westby@ubuntu.com-20090320120013-hogj7egc5mjncc5g
Tags: upstream-8.4~0cvs20090328
Import upstream version 8.4~0cvs20090328

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/bki.sgml
 
1
<!-- $PostgreSQL$ -->
 
2
 
 
3
<chapter id="bki">
 
4
 <title><acronym>BKI</acronym> Backend Interface</title>
 
5
 
 
6
 <para>
 
7
  Backend Interface (<acronym>BKI</acronym>) files are scripts in a
 
8
  special language that is understood by the
 
9
  <productname>PostgreSQL</productname> backend when running in the
 
10
  <quote>bootstrap</quote> mode.  The bootstrap mode allows system catalogs
 
11
  to be created and filled from scratch, whereas ordinary SQL commands
 
12
  require the catalogs to exist already.
 
13
  <acronym>BKI</acronym> files can therefore be used to create the
 
14
  database system in the first place.  (And they are probably not
 
15
  useful for anything else.)
 
16
 </para>
 
17
 
 
18
 <para>
 
19
  <application>initdb</application> uses a <acronym>BKI</acronym> file
 
20
  to do part of its job when creating a new database cluster.  The
 
21
  input file used by <application>initdb</application> is created as
 
22
  part of building and installing <productname>PostgreSQL</productname>
 
23
  by a program named <filename>genbki.sh</filename>, which reads some
 
24
  specially formatted C header files in the <filename>src/include/catalog/</>
 
25
  directory of the source tree.  The created
 
26
  <acronym>BKI</acronym> file is called <filename>postgres.bki</filename> and is
 
27
  normally installed in the
 
28
  <filename>share</filename> subdirectory of the installation tree.
 
29
 </para>
 
30
 
 
31
 <para>
 
32
  Related information can be found in the documentation for
 
33
  <application>initdb</application>.
 
34
 </para>
 
35
 
 
36
 <sect1 id="bki-format">
 
37
  <title><acronym>BKI</acronym> File Format</title>
 
38
 
 
39
  <para>
 
40
   This section describes how the <productname>PostgreSQL</productname>
 
41
   backend interprets <acronym>BKI</acronym> files.  This description
 
42
   will be easier to understand if the <filename>postgres.bki</filename>
 
43
   file is at hand as an example.
 
44
  </para>
 
45
 
 
46
  <para>
 
47
   <acronym>BKI</acronym> input consists of a sequence of commands.  Commands are made up
 
48
   of a number of tokens, depending on the syntax of the command.
 
49
   Tokens are usually separated by whitespace, but need not be if
 
50
   there is no ambiguity.  There is no special command separator; the
 
51
   next token that syntactically cannot belong to the preceding
 
52
   command starts a new one.  (Usually you would put a new command on
 
53
   a new line, for clarity.)  Tokens can be certain key words, special
 
54
   characters (parentheses, commas, etc.), numbers, or double-quoted
 
55
   strings.  Everything is case sensitive.
 
56
  </para>
 
57
 
 
58
  <para>
 
59
   Lines starting with <literal>#</literal> are ignored.
 
60
  </para>
 
61
 
 
62
 </sect1>
 
63
 
 
64
 <sect1 id="bki-commands">
 
65
  <title><acronym>BKI</acronym> Commands</title>
 
66
 
 
67
  <variablelist>
 
68
   <varlistentry>
 
69
    <term>
 
70
     <literal>create</> 
 
71
     <optional><literal>bootstrap</></optional>
 
72
     <optional><literal>shared_relation</></optional>
 
73
     <optional><literal>without_oids</></optional>
 
74
     <replaceable class="parameter">tablename</replaceable>
 
75
     <replaceable class="parameter">tableoid</replaceable>
 
76
     (<replaceable class="parameter">name1</replaceable> =
 
77
     <replaceable class="parameter">type1</replaceable> <optional>,
 
78
     <replaceable class="parameter">name2</replaceable> = <replaceable
 
79
     class="parameter">type2</replaceable>, ...</optional>)
 
80
    </term>
 
81
 
 
82
    <listitem>
 
83
     <para>
 
84
      Create a table named <replaceable
 
85
      class="parameter">tablename</replaceable>, and having the OID
 
86
      <replaceable class="parameter">tableoid</replaceable>,
 
87
      with the columns given in parentheses.
 
88
     </para>
 
89
 
 
90
     <para>
 
91
      The following column types are supported directly by
 
92
      <filename>bootstrap.c</>: <type>bool</type>,
 
93
      <type>bytea</type>, <type>char</type> (1 byte),
 
94
      <type>name</type>, <type>int2</type>,
 
95
      <type>int4</type>, <type>regproc</type>, <type>regclass</type>,
 
96
      <type>regtype</type>, <type>text</type>,
 
97
      <type>oid</type>, <type>tid</type>, <type>xid</type>,
 
98
      <type>cid</type>, <type>int2vector</type>, <type>oidvector</type>,
 
99
      <type>_int4</type> (array), <type>_text</type> (array),
 
100
      <type>_oid</type> (array), <type>_char</type> (array),
 
101
      <type>_aclitem</type> (array).  Although it is possible to create
 
102
      tables containing columns of other types, this cannot be done until
 
103
      after <structname>pg_type</> has been created and filled with
 
104
      appropriate entries.  (That effectively means that only these
 
105
      column types can be used in bootstrapped tables, but non-bootstrap
 
106
      catalogs can contain any built-in type.)
 
107
     </para>
 
108
 
 
109
     <para>
 
110
      When <literal>bootstrap</> is specified,
 
111
      the table will only be created on disk; nothing is entered into
 
112
      <structname>pg_class</structname>,
 
113
      <structname>pg_attribute</structname>, etc, for it.  Thus the
 
114
      table will not be accessible by ordinary SQL operations until
 
115
      such entries are made the hard way (with <literal>insert</>
 
116
      commands).  This option is used for creating
 
117
      <structname>pg_class</structname> etc themselves.
 
118
     </para>
 
119
 
 
120
     <para>
 
121
      The table is created as shared if <literal>shared_relation</> is
 
122
      specified.
 
123
      It will have OIDs unless <literal>without_oids</> is specified.
 
124
     </para>
 
125
    </listitem>
 
126
   </varlistentry>
 
127
 
 
128
   <varlistentry>
 
129
    <term>
 
130
     <literal>open</> <replaceable class="parameter">tablename</replaceable>
 
131
    </term>
 
132
 
 
133
    <listitem>
 
134
     <para>
 
135
      Open the table named
 
136
      <replaceable class="parameter">tablename</replaceable>
 
137
      for insertion of data.  Any currently open table is closed.
 
138
     </para>
 
139
    </listitem>
 
140
   </varlistentry>
 
141
 
 
142
   <varlistentry>
 
143
    <term>
 
144
     <literal>close</> <optional><replaceable class="parameter">tablename</replaceable></optional>
 
145
    </term>
 
146
 
 
147
    <listitem>
 
148
     <para>
 
149
      Close the open table.  The name of the table can be given as a
 
150
      cross-check, but this is not required.
 
151
     </para>
 
152
    </listitem>
 
153
   </varlistentry>
 
154
 
 
155
   <varlistentry>
 
156
    <term>
 
157
     <literal>insert</> <optional><literal>OID =</> <replaceable class="parameter">oid_value</replaceable></optional> <literal>(</> <replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ... <literal>)</>
 
158
    </term>
 
159
 
 
160
    <listitem>
 
161
     <para>
 
162
      Insert a new row into the open table using <replaceable
 
163
      class="parameter">value1</replaceable>, <replaceable
 
164
      class="parameter">value2</replaceable>, etc., for its column
 
165
      values and <replaceable
 
166
      class="parameter">oid_value</replaceable> for its OID.  If
 
167
      <replaceable class="parameter">oid_value</replaceable> is zero
 
168
      (0) or the clause is omitted, and the table has OIDs, then the
 
169
      next available OID is assigned.
 
170
     </para>
 
171
 
 
172
     <para>
 
173
      NULL values can be specified using the special key word
 
174
      <literal>_null_</literal>.  Values containing spaces must be
 
175
      double quoted.
 
176
     </para>
 
177
    </listitem>
 
178
   </varlistentry>
 
179
 
 
180
   <varlistentry>
 
181
    <term>
 
182
     <literal>declare</> <optional><literal>unique</></optional>
 
183
     <literal>index</> <replaceable class="parameter">indexname</replaceable>
 
184
     <replaceable class="parameter">indexoid</replaceable>
 
185
     <literal>on</> <replaceable class="parameter">tablename</replaceable>
 
186
     <literal>using</> <replaceable class="parameter">amname</replaceable>
 
187
     <literal>(</> <replaceable class="parameter">opclass1</replaceable>
 
188
     <replaceable class="parameter">name1</replaceable>
 
189
     <optional>, ...</optional> <literal>)</>
 
190
    </term>
 
191
 
 
192
    <listitem>
 
193
     <para>
 
194
      Create an index named <replaceable
 
195
      class="parameter">indexname</replaceable>, having OID
 
196
      <replaceable class="parameter">indexoid</replaceable>,
 
197
      on the table named
 
198
      <replaceable class="parameter">tablename</replaceable>, using the
 
199
      <replaceable class="parameter">amname</replaceable> access
 
200
      method.  The fields to index are called <replaceable
 
201
      class="parameter">name1</replaceable>, <replaceable
 
202
      class="parameter">name2</replaceable> etc., and the operator
 
203
      classes to use are <replaceable
 
204
      class="parameter">opclass1</replaceable>, <replaceable
 
205
      class="parameter">opclass2</replaceable> etc., respectively.
 
206
      The index file is created and appropriate catalog entries are
 
207
      made for it, but the index contents are not initialized by this command.
 
208
     </para>
 
209
    </listitem>
 
210
   </varlistentry>
 
211
 
 
212
   <varlistentry>
 
213
    <term>
 
214
     <literal>declare toast</>
 
215
     <replaceable class="parameter">toasttableoid</replaceable>
 
216
     <replaceable class="parameter">toastindexoid</replaceable>
 
217
     <literal>on</> <replaceable class="parameter">tablename</replaceable>
 
218
    </term>
 
219
 
 
220
    <listitem>
 
221
     <para>
 
222
      Create a TOAST table for the table named
 
223
      <replaceable class="parameter">tablename</replaceable>.
 
224
      The TOAST table is assigned OID
 
225
      <replaceable class="parameter">toasttableoid</replaceable>
 
226
      and its index is assigned OID
 
227
      <replaceable class="parameter">toastindexoid</replaceable>.
 
228
      As with <literal>declare index</>, filling of the index
 
229
      is postponed.
 
230
     </para>
 
231
    </listitem>
 
232
   </varlistentry>
 
233
 
 
234
   <varlistentry>
 
235
    <term><literal>build indices</></term>
 
236
 
 
237
    <listitem>
 
238
     <para>
 
239
      Fill in the indices that have previously been declared.
 
240
     </para>
 
241
    </listitem>
 
242
   </varlistentry>
 
243
  </variablelist>
 
244
 
 
245
 </sect1>
 
246
 
 
247
 <sect1 id="bki-structure">
 
248
  <title>Structure of the Bootstrap <acronym>BKI</acronym> File</title>
 
249
 
 
250
  <para>
 
251
   The <literal>open</> command cannot be used until the tables it uses
 
252
   exist and have entries for the table that is to be opened.
 
253
   (These minimum tables are <structname>pg_class</>,
 
254
   <structname>pg_attribute</>, <structname>pg_proc</>, and
 
255
   <structname>pg_type</>.)   To allow those tables themselves to be filled,
 
256
   <literal>create</> with the <literal>bootstrap</> option implicitly opens
 
257
   the created table for data insertion.
 
258
  </para>
 
259
 
 
260
  <para>
 
261
   Also, the <literal>declare index</> and <literal>declare toast</>
 
262
   commands cannot be used until the system catalogs they need have been
 
263
   created and filled in.
 
264
  </para>
 
265
 
 
266
  <para>
 
267
   Thus, the structure of the <filename>postgres.bki</filename> file has to
 
268
   be:
 
269
   <orderedlist>
 
270
    <listitem>
 
271
     <para>
 
272
      <literal>create bootstrap</> one of the critical tables
 
273
     </para>
 
274
    </listitem>
 
275
    <listitem>
 
276
     <para>
 
277
      <literal>insert</> data describing at least the critical tables
 
278
     </para>
 
279
    </listitem>
 
280
    <listitem>
 
281
     <para>
 
282
      <literal>close</>
 
283
     </para>
 
284
    </listitem>
 
285
    <listitem>
 
286
     <para>
 
287
      Repeat for the other critical tables.
 
288
     </para>
 
289
    </listitem>
 
290
    <listitem>
 
291
     <para>
 
292
      <literal>create</> (without <literal>bootstrap</>) a noncritical table
 
293
     </para>
 
294
    </listitem>
 
295
    <listitem>
 
296
     <para>
 
297
      <literal>open</>
 
298
     </para>
 
299
    </listitem>
 
300
    <listitem>
 
301
     <para>
 
302
      <literal>insert</> desired data
 
303
     </para>
 
304
    </listitem>
 
305
    <listitem>
 
306
     <para>
 
307
      <literal>close</>
 
308
     </para>
 
309
    </listitem>
 
310
    <listitem>
 
311
     <para>
 
312
      Repeat for the other noncritical tables.
 
313
     </para>
 
314
    </listitem>
 
315
    <listitem>
 
316
     <para>
 
317
      Define indexes and toast tables.
 
318
     </para>
 
319
    </listitem>
 
320
    <listitem>
 
321
     <para>
 
322
      <literal>build indices</>
 
323
     </para>
 
324
    </listitem>
 
325
   </orderedlist>
 
326
  </para>
 
327
 
 
328
  <para>
 
329
   There are doubtless other, undocumented ordering dependencies.
 
330
  </para>
 
331
 </sect1>
 
332
 
 
333
 <sect1 id="bki-example">
 
334
  <title>Example</title>
 
335
 
 
336
  <para>
 
337
   The following sequence of commands will create the
 
338
   table <literal>test_table</literal> with OID 420, having two columns
 
339
   <literal>cola</literal> and <literal>colb</literal> of type
 
340
   <type>int4</type> and <type>text</type>, respectively, and insert
 
341
   two rows into the table:
 
342
<programlisting>
 
343
create test_table 420 (cola = int4, colb = text)
 
344
open test_table
 
345
insert OID=421 ( 1 "value1" )
 
346
insert OID=422 ( 2 _null_ )
 
347
close test_table
 
348
</programlisting>
 
349
  </para>
 
350
 </sect1>
 
351
</chapter>