Skip to content

P
Postgres FD Implementation
Commit 37c55f98 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

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

parent fad81377
Hide whitespace changes
Inline Side-by-side
Showing with 222 additions and 414 deletions
doc/src/sgml/bki.sgml
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> <para>
Backend Interface (<acronym>BKI</acronym>) files are scripts that are input Backend Interface (<acronym>BKI</acronym>) files are scripts in a
to the <productname>Postgres</productname> special language that are input to the
backend running in the special "bootstrap" mode that allows it to perform <productname>Postgres</productname> backend running in the special
database functions without a database system already existing. <acronym>BKI</acronym> files <quote>bootstrap</quote> mode that allows it to perform database
can therefore be used to create the database system in the first place. functions without a database system already existing.
<application>initdb</application> <acronym>BKI</acronym> files can therefore be used to create the
uses <acronym>BKI</acronym> files to do just that: to create a database system. However, database system in the first place. (And they are probably not
<application>initdb</application>'s useful for anything else.)
<acronym>BKI</acronym> files are generated internally. It generates them using the files </para>
<filename>global1.bki.source</filename> and <filename>local1.template1.bki.source</filename>, which it finds in the
<productname>Postgres</productname> "library" directory. They get installed there as part of installing <para>
<productname>Postgres</productname>. These .source files get build as part of the <productname>Postgres</productname> build <application>initdb</application> uses <acronym>BKI</acronym> files
process, by a build program called to do part of its job when creating a new database cluster. The
<application>genbki</application>. input files used by <application>initbd</application> are created as
<application>genbki</application> part of building and installing <productname>Postgres</productname>
takes as input <productname>Postgres</productname> source files that double as by a program named <filename>genbki.sh</filename> from some
<application>genbki</application> specially formatted C header files in the source tree. The created
input that builds tables and C header files that describe those BKI files are called <filename>global.bki</filename> (for global
tables. catalogs) and <filename>template1.bki</filename> (for the catalogs
</para> initially stored in the template1 database and then duplicated in
every created database) and are normally installed in the
<para> <filename>share</filename> subdirectory of the installation tree.
Related information may be found in documentation for </para>
<application>initdb</application>,
<application>createdb</application>, <para>
and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>. Related information may be found in the documentation for
</para> <application>initdb</application>.
</para>
<sect1 id="bki-format">
<title><acronym>BKI</acronym> File Format</title> <sect1 id="bki-format">
<title><acronym>BKI</acronym> File Format</title>
<para>
The <productname>Postgres</productname> backend interprets <para>
<acronym>BKI</acronym> files as described below. This This section describes how the <productname>Postgres</productname>
description will be easier to understand if the backend interprets <acronym>BKI</acronym> files. This description
<filename>global1.bki.source</filename> file is will be easier to understand if the <filename>global.bki</filename>
at hand as an example. (As explained above, this .source file isn't quite file is at hand as an example. You should also study the source
a <acronym>BKI</acronym> file, but you'll be able to guess what code of <application>initdb</application> to get an idea of how the
the resulting <acronym>BKI</acronym> file would be backend is invoked.
anyway). </para>
</para>
<para>
<para> BKI input consists of a sequence of commands. Commands are made up
Commands are composed of a command name followed by space separated of a number of tokens, depending on the syntax of the command.
arguments. Arguments to a command that begin with a "$" are Tokens are usually separated by whitespace, but need not be if
treated specially. If "$$" are the first two characters, then there is no ambiguity. There is not special command separator; the
the first "$" is ignored and the argument is then processed next token that syntactically cannot belong to the preceeding
normally. If the "$" is followed by space, then it is treated command starts a new one. (Usually you would put a new command on
as a NULL a new line, for clarity.) Tokens can be certain key words, special
value. Otherwise, the characters following the "$" are characters (parentheses, commas, etc.), numbers, or double-quoted
interpreted as the name of a macro causing the argument to be replaced strings. Everything is case sensitive.
with the macro's value. It is an error for this macro to be </para>
undefined.
</para> <para>
Lines starting with a <literal>#</literal> are ignored.
<para> </para>
Macros are defined using
<programlisting> </sect1>
define macro macro_name = macro_value
</programlisting> <sect1 id="bki-commands">
and are undefined using <title>BKI Commands</title>
<programlisting>
undefine macro macro_name <variablelist>
</programlisting> <varlistentry>
and redefined using the same syntax as define. <term>
</para> open <replaceable class="parameter">tablename</replaceable>
</term>
<para>
Lists of general commands and macro commands <listitem>
follow. <para>
</para> Open the table called
</sect1> <replaceable class="parameter">tablename</replaceable>
for further manipulation.
<sect1 id="bki-commands"> </para>
<title>General Commands</title> </listitem>
</varlistentry>
<variablelist>
<varlistentry> <varlistentry>
<term> <term>
OPEN <replaceable class="parameter">classname</replaceable> close <optional><replaceable class="parameter">tablename</replaceable></optional>
</term> </term>
<listitem>
<para> <listitem>
Open the class called <para>
<replaceable class="parameter">classname</replaceable> Close the open table called <replaceable
for further manipulation. class="parameter">tablename</replaceable>. It is an error if
</para> <replaceable class="parameter">tablename</replaceable> is not
</listitem> already opened. If no <replaceable
</varlistentry> class="parameter">tablename</replaceable> is given, then the
currently open table is closed.
<varlistentry> </para>
<term> </listitem>
CLOSE [<replaceable class="parameter">classname</replaceable>] </varlistentry>
</term>
<listitem> <varlistentry>
<para> <term>
Close the open class called create <replaceable class="parameter">tablename</replaceable>
<replaceable class="parameter">classname</replaceable>. (<replaceable class="parameter">name1</replaceable> =
It is an error if <replaceable class="parameter">type1</replaceable> <optional>,
<replaceable class="parameter">classname</replaceable> <replaceable class="parameter">name2</replaceable> = <replaceable
is not already opened. If no class="parameter">type2</replaceable>, ...</optional>)
<replaceable class="parameter">classname</replaceable> </term>
is given, then the currently open class is closed.
</para> <listitem>
</listitem> <para>
</varlistentry> Create a table named <replaceable
class="parameter">tablename</replaceable> with the columns given
<varlistentry> in parentheses.
<term> </para>
PRINT
</term> <para>
<listitem> The <replaceable>type</replaceable> is not necessarily the data
<para> type that the column will have in the SQL environment; that is
Print the currently open class. determined by the <structname>pg_attribute</structname> system
</para> catalog. The type here is essentially only used to allocate
</listitem> storage. The following types are allowed: <type>bool</type>,
</varlistentry> <type>bytea</type>, <type>char</type> (1 byte),
<type>name</type>, <type>int2</type>, <type>int2vector</type>,
<varlistentry> <type>int4</type>, <type>regproc</type>, <type>text</type>,
<term> <type>oid</type>, <type>tid</type>, <type>xid</type>,
INSERT [OID=<replaceable class="parameter">oid_value</replaceable>] (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...) <type>cid</type>, <type>oidvector</type>, <type>smgr</type>,
</term> <type>_int4</type> (array), <type>_aclitem</type> (array).
<listitem> Array types can also be indicated by writing
<para> <literal>[]</literal> after the name of the element type.
Insert a new instance to the open class using </para>
<replaceable class="parameter">value1</replaceable>,
<replaceable class="parameter">value2</replaceable>, <note>
etc., for its attribute values and <para>
<replaceable class="parameter">oid_value</replaceable> The table will only be created on disk, it will not
for its OID. If automatically be registered in the system catalogs and will
<replaceable class="parameter">oid_value</replaceable> therefore not be accessible unless appropriate rows are
is not zero (0), then this value will be used as the instance's inserted in <structname>pg_class</structname>,
object identifier. Otherwise, it is an error. <structname>pg_attribute</structname>, etc.
</para> </para>
</listitem> </note>
</varlistentry> </listitem>
</varlistentry>
<varlistentry>
<term> <varlistentry>
INSERT (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...) <term>
</term> insert <optional>OID = <replaceable class="parameter">oid_value</replaceable></optional> (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...)
<listitem> </term>
<para>
As above, but the system generates a unique object identifier. <listitem>
</para> <para>
</listitem> Insert a new row into the open table using <replaceable
</varlistentry> class="parameter">value1</replaceable>, <replaceable
class="parameter">value2</replaceable>, etc., for its column
<varlistentry> values and <replaceable
<term> class="parameter">oid_value</replaceable> for its OID. If
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>[,...]]) <replaceable class="parameter">oid_value</replaceable> is zero
</term> (0) or the clause is ommitted, then the next available OID is
<listitem> used.
<para> </para>
Create a class named
<replaceable class="parameter">classname</replaceable> <para>
with the attributes given in parentheses. NULL values can be specified using the special key word
</para> <literal>_null_</literal>. Values containing spaces should be
</listitem> double quoted.
</varlistentry> </para>
</listitem>
<varlistentry> </varlistentry>
<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> <varlistentry>
</term> <term>
<listitem> declare <optional>unique</optional> index <replaceable
<para> class="parameter">indexname</replaceable> on <replaceable
Open a class named class="parameter">tablename</replaceable> using <replaceable
<replaceable class="parameter">classname</replaceable> class="parameter">amname</replaceable> (<replaceable
for writing but do not record its existence in the system catalogs. class="parameter">opclass1</replaceable> <replaceable
(This is primarily to aid in bootstrapping.) class="parameter">name1</replaceable> <optional>, ...</optional>)
</para> </term>
</listitem>
</varlistentry> <listitem>
<para>
<varlistentry> Create an index named <replaceable
<term> class="parameter">indexname</replaceable> on the table named
DESTROY <replaceable class="parameter">classname</replaceable> <replaceable class="parameter">tablename</replaceable> using the
</term> <replaceable class="parameter">amname</replaceable> access
<listitem> method. The fields to index are called <replaceable
<para> class="parameter">name1</replaceable>, <replaceable
Destroy the class named class="parameter">name2</replaceable> etc., and the operator
<replaceable class="parameter">classname</replaceable>. classes to use are <replaceable
</para> class="parameter">opclass1</replaceable>, <replaceable
</listitem> class="parameter">opclass2</replaceable> etc., respectively.
</varlistentry> </para>
</listitem>
<varlistentry> </varlistentry>
<term>
DEFINE INDEX <replaceable class="parameter">indexname</replaceable> ON <replaceable class="parameter">class_name</replaceable> USING <replaceable class="parameter">amname</replaceable> <varlistentry>
(<replaceable class="parameter">opclass</replaceable> <replaceable class="parameter">attr</replaceable> | (<replaceable class="parameter">function</replaceable>(<replaceable class="parameter">attr</replaceable>)) <term>build indices</term>
</term>
<listitem> <listitem>
<para> <para>
Create an index named Build the indices that have previously been declared.
<replaceable class="parameter">indexname</replaceable> </para>
on the class named </listitem>
<replaceable class="parameter">classname</replaceable> </varlistentry>
using the </variablelist>
<replaceable class="parameter">amname</replaceable>
access method. The fields to index are called </sect1>
<replaceable class="parameter">name1</replaceable>,
<replaceable class="parameter">name2</replaceable> <sect1 id="bki-example">
etc., and the operator collections to use are <title>Example</title>
<replaceable class="parameter">collection_1</replaceable>,
<replaceable class="parameter">collection_2</replaceable> <para>
etc., respectively. The following sequence of commands will create the
</para> <literal>test_table</literal> table with the two columns
</listitem> <literal>cola</literal> and <literal>colb</literal> of type
</varlistentry> <type>int4</type> and <type>text</type>, respectively, and insert
two rows into the table.
</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>
<para>
Define a function prototype for a function named
<replaceable class="parameter">macro_name</replaceable>
which has its value of type
<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>
</listitem>
</varlistentry>
<varlistentry>
<term>
DEFINE MACRO <replaceable class="parameter">macro_name</replaceable> FROM FILE <replaceable class="parameter">filename</replaceable>
</term>
<listitem>
<para>
Define a macro named
<replaceable class="parameter">macro_name</replaceable>
which has its value
read from the file called
<replaceable class="parameter">filename</replaceable>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="bki-debug">
<title>Debugging Commands</title>
<para>
<note>
<para>
This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05
</para>
</note>
<variablelist>
<varlistentry>
<term>
r
</term>
<listitem>
<para>
Randomly print the open class.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
m -1
</term>
<listitem>
<para>
Toggle display of time information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
m 0
</term>
<listitem>
<para>
Set retrievals to now.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
m 1 Jan 1 01:00:00 1988
</term>
<listitem>
<para>
Set retrievals to snapshots of the specfied time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988
</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>
<para>
Add
<replaceable class="parameter">natts</replaceable>
attributes named
<replaceable class="parameter">name1</replaceable>,
<replaceable class="parameter">name2</replaceable>,
etc. of
types
<replaceable class="parameter">type1</replaceable>,
<replaceable class="parameter">type2</replaceable>,
etc. to the class
<replaceable class="parameter">classname</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<para>
Rename the
<replaceable class="parameter">oldattname</replaceable>
attribute in the class named
<replaceable class="parameter">classname</replaceable>
to
<replaceable class="parameter">newattname</replaceable>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="bki-example">
<title>Example</title>
<para>
The following set of commands will create the <literal>pg_opclass</literal>
class containing the
<parameter>int_ops</parameter>
collection as an object with an OID of
<parameter>421</parameter>,
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>
</chapter> </chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment