Skip to content
Snippets Groups Projects
Commit 37c55f98 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files

Some of the stuff documented here hasn't existed since Postgres95.

parent fad81377
Branches
Tags
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 222 additions and 414 deletions
doc/src/sgml/bki.sgml
+ 222
− 414
View file @ 37c55f98
<!-- <!-- $Header: /cvsroot/pgsql/doc/src/sgml/bki.sgml,v 1.6 2000/12/23 16:24:29 petere Exp $ -->
$Header: /cvsroot/pgsql/doc/src/sgml/bki.sgml,v 1.5 2000/12/22 18:57:49 petere Exp $
Transcribed from the original bki.man.5 documentation
- Thomas Lockhart 1998-08-03
-->
<chapter id="bki"> <chapter id="bki">
<title>Backend Interface</title> <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>Postgres</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> <para>
Backend Interface (<acronym>BKI</acronym>) files are scripts that are input <application>initdb</application> uses <acronym>BKI</acronym> files
to the <productname>Postgres</productname> to do part of its job when creating a new database cluster. The
backend running in the special "bootstrap" mode that allows it to perform input files used by <application>initbd</application> are created as
database functions without a database system already existing. <acronym>BKI</acronym> files part of building and installing <productname>Postgres</productname>
can therefore be used to create the database system in the first place. by a program named <filename>genbki.sh</filename> from some
<application>initdb</application> specially formatted C header files in the source tree. The created
uses <acronym>BKI</acronym> files to do just that: to create a database system. However, BKI files are called <filename>global.bki</filename> (for global
<application>initdb</application>'s catalogs) and <filename>template1.bki</filename> (for the catalogs
<acronym>BKI</acronym> files are generated internally. It generates them using the files initially stored in the template1 database and then duplicated in
<filename>global1.bki.source</filename> and <filename>local1.template1.bki.source</filename>, which it finds in the every created database) and are normally installed in the
<productname>Postgres</productname> "library" directory. They get installed there as part of installing <filename>share</filename> subdirectory of the installation tree.
<productname>Postgres</productname>. These .source files get build as part of the <productname>Postgres</productname> build
process, by a build program called
<application>genbki</application>.
<application>genbki</application>
takes as input <productname>Postgres</productname> source files that double as
<application>genbki</application>
input that builds tables and C header files that describe those
tables.
</para> </para>
<para> <para>
Related information may be found in documentation for Related information may be found in the documentation for
<application>initdb</application>, <application>initdb</application>.
<application>createdb</application>,
and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>.
</para> </para>
<sect1 id="bki-format"> <sect1 id="bki-format">
<title><acronym>BKI</acronym> File Format</title> <title><acronym>BKI</acronym> File Format</title>
<para> <para>
The <productname>Postgres</productname> backend interprets This section describes how the <productname>Postgres</productname>
<acronym>BKI</acronym> files as described below. This backend interprets <acronym>BKI</acronym> files. This description
description will be easier to understand if the will be easier to understand if the <filename>global.bki</filename>
<filename>global1.bki.source</filename> file is file is at hand as an example. You should also study the source
at hand as an example. (As explained above, this .source file isn't quite code of <application>initdb</application> to get an idea of how the
a <acronym>BKI</acronym> file, but you'll be able to guess what backend is invoked.
the resulting <acronym>BKI</acronym> file would be
anyway).
</para> </para>
<para> <para>
Commands are composed of a command name followed by space separated BKI input consists of a sequence of commands. Commands are made up
arguments. Arguments to a command that begin with a "$" are of a number of tokens, depending on the syntax of the command.
treated specially. If "$$" are the first two characters, then Tokens are usually separated by whitespace, but need not be if
the first "$" is ignored and the argument is then processed there is no ambiguity. There is not special command separator; the
normally. If the "$" is followed by space, then it is treated next token that syntactically cannot belong to the preceeding
as a NULL command starts a new one. (Usually you would put a new command on
value. Otherwise, the characters following the "$" are a new line, for clarity.) Tokens can be certain key words, special
interpreted as the name of a macro causing the argument to be replaced characters (parentheses, commas, etc.), numbers, or double-quoted
with the macro's value. It is an error for this macro to be strings. Everything is case sensitive.
undefined.
</para> </para>
<para> <para>
Macros are defined using Lines starting with a <literal>#</literal> are ignored.
<programlisting>
define macro macro_name = macro_value
</programlisting>
and are undefined using
<programlisting>
undefine macro macro_name
</programlisting>
and redefined using the same syntax as define.
</para> </para>
<para>
Lists of general commands and macro commands
follow.
</para>
</sect1> </sect1>
<sect1 id="bki-commands"> <sect1 id="bki-commands">
<title>General Commands</title> <title>BKI Commands</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
OPEN <replaceable class="parameter">classname</replaceable> open <replaceable class="parameter">tablename</replaceable>
</term>
<listitem>
<para>
Open the class called
<replaceable class="parameter">classname</replaceable>
for further manipulation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
CLOSE [<replaceable class="parameter">classname</replaceable>]
</term>
<listitem>
<para>
Close the open class called
<replaceable class="parameter">classname</replaceable>.
It is an error if
<replaceable class="parameter">classname</replaceable>
is not already opened. If no
<replaceable class="parameter">classname</replaceable>
is given, then the currently open class is closed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
PRINT
</term>
<listitem>
<para>
Print the currently open class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
INSERT [OID=<replaceable class="parameter">oid_value</replaceable>] (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...)
</term> </term>
<listitem>
<para>
Insert a new instance to the open class using
<replaceable class="parameter">value1</replaceable>,
<replaceable class="parameter">value2</replaceable>,
etc., for its attribute values and
<replaceable class="parameter">oid_value</replaceable>
for its OID. If
<replaceable class="parameter">oid_value</replaceable>
is not zero (0), then this value will be used as the instance's
object identifier. Otherwise, it is an error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
INSERT (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...)
</term>
<listitem> <listitem>
<para> <para>
As above, but the system generates a unique object identifier. Open the table called
</para> <replaceable class="parameter">tablename</replaceable>
</listitem> for further manipulation.
</varlistentry>
<varlistentry>
<term>
CREATE <replaceable class="parameter">classname</replaceable> (<replaceable class="parameter">name1</replaceable> = <replaceable class="parameter">type1</replaceable> [,<replaceable class="parameter">name2</replaceable> = <replaceable class="parameter">type2</replaceable>[,...]])
</term>
<listitem>
<para>
Create a class named
<replaceable class="parameter">classname</replaceable>
with the attributes given in parentheses.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
OPEN (<replaceable class="parameter">name1</replaceable> = <replaceable class="parameter">type1</replaceable> [,<replaceable class="parameter">name2</replaceable> = <replaceable class="parameter">type2</replaceable>[,...]]) AS <replaceable class="parameter">classname</replaceable> close <optional><replaceable class="parameter">tablename</replaceable></optional>
</term> </term>
<listitem>
<para>
Open a class named
<replaceable class="parameter">classname</replaceable>
for writing but do not record its existence in the system catalogs.
(This is primarily to aid in bootstrapping.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
DESTROY <replaceable class="parameter">classname</replaceable>
</term>
<listitem> <listitem>
<para> <para>
Destroy the class named Close the open table called <replaceable
<replaceable class="parameter">classname</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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
DEFINE INDEX <replaceable class="parameter">indexname</replaceable> ON <replaceable class="parameter">class_name</replaceable> USING <replaceable class="parameter">amname</replaceable> create <replaceable class="parameter">tablename</replaceable>
(<replaceable class="parameter">opclass</replaceable> <replaceable class="parameter">attr</replaceable> | (<replaceable class="parameter">function</replaceable>(<replaceable class="parameter">attr</replaceable>)) (<replaceable class="parameter">name1</replaceable> =
<replaceable class="parameter">type1</replaceable> <optional>,
<replaceable class="parameter">name2</replaceable> = <replaceable
class="parameter">type2</replaceable>, ...</optional>)
</term> </term>
<listitem>
<para>
Create an index named
<replaceable class="parameter">indexname</replaceable>
on the class named
<replaceable class="parameter">classname</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 collections to use are
<replaceable class="parameter">collection_1</replaceable>,
<replaceable class="parameter">collection_2</replaceable>
etc., respectively.
</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04
</para>
</note>
</sect1>
<sect1 id="bki-macros">
<title>Macro Commands</title>
<para>
<variablelist>
<varlistentry>
<term>
DEFINE FUNCTION <replaceable class="parameter">macro_name</replaceable> AS <replaceable class="parameter">rettype</replaceable> <replaceable class="parameter">function_name</replaceable>(<replaceable class="parameter">args</replaceable>)
</term>
<listitem> <listitem>
<para> <para>
Define a function prototype for a function named Create a table named <replaceable
<replaceable class="parameter">macro_name</replaceable> class="parameter">tablename</replaceable> with the columns given
which has its value of type in parentheses.
<replaceable class="parameter">rettype</replaceable>
computed from the execution
<replaceable class="parameter">function_name</replaceable>
with the arguments
<replaceable class="parameter">args</replaceable>
declared in a C-like manner.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
DEFINE MACRO <replaceable class="parameter">macro_name</replaceable> FROM FILE <replaceable class="parameter">filename</replaceable>
</term>
<listitem>
<para> <para>
Define a macro named The <replaceable>type</replaceable> is not necessarily the data
<replaceable class="parameter">macro_name</replaceable> type that the column will have in the SQL environment; that is
which has its value determined by the <structname>pg_attribute</structname> system
read from the file called catalog. The type here is essentially only used to allocate
<replaceable class="parameter">filename</replaceable>. 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> </para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="bki-debug">
<title>Debugging Commands</title>
<para>
<note> <note>
<para> <para>
This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05 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> </para>
</note> </note>
<variablelist>
<varlistentry>
<term>
r
</term>
<listitem>
<para>
Randomly print the open class.
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
m -1 insert <optional>OID = <replaceable class="parameter">oid_value</replaceable></optional> (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...)
</term> </term>
<listitem>
<para>
Toggle display of time information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
m 0
</term>
<listitem> <listitem>
<para> <para>
Set retrievals to now. 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 ommitted, then the next available OID is
used.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
m 1 Jan 1 01:00:00 1988
</term>
<listitem>
<para> <para>
Set retrievals to snapshots of the specfied time. NULL values can be specified using the special key word
<literal>_null_</literal>. Values containing spaces should be
double quoted.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988 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> </term>
<listitem>
<para>
Set retrievals to ranges of the specified times.
Either time may be replaced with space
if an unbounded time range is desired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
&amp;A <replaceable class="parameter">classname</replaceable> <replaceable class="parameter">natts</replaceable> <replaceable class="parameter">name1</replaceable> <replaceable class="parameter">type1</replaceable> <replaceable class="parameter">name2</replaceable> <replaceable class="parameter">type2</replaceable> <replaceable class="parameter">...</replaceable>
</term>
<listitem> <listitem>
<para> <para>
Add Create an index named <replaceable
<replaceable class="parameter">natts</replaceable> class="parameter">indexname</replaceable> on the table named
attributes named <replaceable class="parameter">tablename</replaceable> using the
<replaceable class="parameter">name1</replaceable>, <replaceable class="parameter">amname</replaceable> access
<replaceable class="parameter">name2</replaceable>, method. The fields to index are called <replaceable
etc. of class="parameter">name1</replaceable>, <replaceable
types class="parameter">name2</replaceable> etc., and the operator
<replaceable class="parameter">type1</replaceable>, classes to use are <replaceable
<replaceable class="parameter">type2</replaceable>, class="parameter">opclass1</replaceable>, <replaceable
etc. to the class class="parameter">opclass2</replaceable> etc., respectively.
<replaceable class="parameter">classname</replaceable>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>build indices</term>
&amp;RR <replaceable class="parameter">oldclassname</replaceable> <replaceable class="parameter">newclassname</replaceable>
</term>
<listitem>
<para>
Rename the
<replaceable class="parameter">oldclassname</replaceable>
class to
<replaceable class="parameter">newclassname</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
&amp;RA classname oldattname newattname
<replaceable class="parameter">classname</replaceable>
<replaceable class="parameter">oldattname</replaceable>
<replaceable class="parameter">newattname</replaceable>
</term>
<listitem> <listitem>
<para> <para>
Rename the Build the indices that have previously been declared.
<replaceable class="parameter">oldattname</replaceable>
attribute in the class named
<replaceable class="parameter">classname</replaceable>
to
<replaceable class="parameter">newattname</replaceable>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</sect1> </sect1>
<sect1 id="bki-example"> <sect1 id="bki-example">
<title>Example</title> <title>Example</title>
<para> <para>
The following set of commands will create the <literal>pg_opclass</literal> The following sequence of commands will create the
class containing the <literal>test_table</literal> table with the two columns
<parameter>int_ops</parameter> <literal>cola</literal> and <literal>colb</literal> of type
collection as an object with an OID of <type>int4</type> and <type>text</type>, respectively, and insert
<parameter>421</parameter>, two rows into the table.
print out the class, and then close it.
<programlisting> <programlisting>
create pg_opclass (opcname=name) create test_table (cola = int4, colb = text)
open pg_opclass open test_table
insert oid=421 (int_ops) insert OID=421 ( 1 "value1" )
print insert OID=422 ( 2 _null_ )
close pg_opclass close test_table
</programlisting> </programlisting>
</para> </para>
</sect1> </sect1>
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment