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
Show 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
<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>
Related information may be found in documentation for <application>initdb</application> uses <acronym>BKI</acronym> files
<application>initdb</application>, to do part of its job when creating a new database cluster. The
<application>createdb</application>, input files used by <application>initbd</application> are created as
and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>. part of building and installing <productname>Postgres</productname>
</para> by a program named <filename>genbki.sh</filename> from some
specially formatted C header files in the source tree. The created
BKI files are called <filename>global.bki</filename> (for global
catalogs) and <filename>template1.bki</filename> (for the catalogs
initially stored in the template1 database and then duplicated in
every created database) and are 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"> <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>
Macros are defined using
<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>
Lists of general commands and macro commands
follow.
</para>
</sect1>
<sect1 id="bki-commands">
<title>General Commands</title>
<variablelist>
<varlistentry>
<term>
OPEN <replaceable class="parameter">classname</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>
<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>
<para>
As above, but the system generates a unique object identifier.
</para>
</listitem>
</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>
</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>
</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>
<para>
Destroy the class named
<replaceable class="parameter">classname</replaceable>.
</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>
(<replaceable class="parameter">opclass</replaceable> <replaceable class="parameter">attr</replaceable> | (<replaceable class="parameter">function</replaceable>(<replaceable class="parameter">attr</replaceable>))
</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>
<para> Lines starting with a <literal>#</literal> are ignored.
This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04 </para>
</para>
</note>
</sect1>
<sect1 id="bki-macros"> </sect1>
<title>Macro Commands</title>
<para> <sect1 id="bki-commands">
<variablelist> <title>BKI Commands</title>
<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> <variablelist>
<term> <varlistentry>
DEFINE MACRO <replaceable class="parameter">macro_name</replaceable> FROM FILE <replaceable class="parameter">filename</replaceable> <term>
</term> open <replaceable class="parameter">tablename</replaceable>
<listitem> </term>
<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> <listitem>
</para> <para>
</sect1> Open the table called
<replaceable class="parameter">tablename</replaceable>
for further manipulation.
</para>
</listitem>
</varlistentry>
<sect1 id="bki-debug"> <varlistentry>
<title>Debugging Commands</title> <term>
close <optional><replaceable class="parameter">tablename</replaceable></optional>
</term>
<para> <listitem>
<note> <para>
<para> Close the open table called <replaceable
This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05 class="parameter">tablename</replaceable>. It is an error if
</para> <replaceable class="parameter">tablename</replaceable> is not
</note> 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>
<variablelist> <para>
<varlistentry> The <replaceable>type</replaceable> is not necessarily the data
<term> type that the column will have in the SQL environment; that is
r determined by the <structname>pg_attribute</structname> system
</term> catalog. The type here is essentially only used to allocate
<listitem> storage. The following types are allowed: <type>bool</type>,
<para> <type>bytea</type>, <type>char</type> (1 byte),
Randomly print the open class. <type>name</type>, <type>int2</type>, <type>int2vector</type>,
</para> <type>int4</type>, <type>regproc</type>, <type>text</type>,
</listitem> <type>oid</type>, <type>tid</type>, <type>xid</type>,
</varlistentry> <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>
<varlistentry> <note>
<term> <para>
m -1 The table will only be created on disk, it will not
</term> automatically be registered in the system catalogs and will
<listitem> therefore not be accessible unless appropriate rows are
<para> inserted in <structname>pg_class</structname>,
Toggle display of time information. <structname>pg_attribute</structname>, etc.
</para> </para>
</listitem> </note>
</varlistentry> </listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
m 0 insert <optional>OID = <replaceable class="parameter">oid_value</replaceable></optional> (<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">value2</replaceable> ...)
</term> </term>
<listitem>
<para>
Set retrievals to now.
</para>
</listitem>
</varlistentry>
<varlistentry> <listitem>
<term> <para>
m 1 Jan 1 01:00:00 1988 Insert a new row into the open table using <replaceable
</term> class="parameter">value1</replaceable>, <replaceable
<listitem> class="parameter">value2</replaceable>, etc., for its column
<para> values and <replaceable
Set retrievals to snapshots of the specfied time. class="parameter">oid_value</replaceable> for its OID. If
</para> <replaceable class="parameter">oid_value</replaceable> is zero
</listitem> (0) or the clause is ommitted, then the next available OID is
</varlistentry> used.
</para>
<varlistentry> <para>
<term> NULL values can be specified using the special key word
m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988 <literal>_null_</literal>. Values containing spaces should be
</term> double quoted.
<listitem> </para>
<para> </listitem>
Set retrievals to ranges of the specified times. </varlistentry>
Either time may be replaced with space
if an unbounded time range is desired. <varlistentry>
</para> <term>
</listitem> declare <optional>unique</optional> index <replaceable
</varlistentry> 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> <varlistentry>
<term> <term>build indices</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> <listitem>
<term> <para>
&amp;RR <replaceable class="parameter">oldclassname</replaceable> <replaceable class="parameter">newclassname</replaceable> Build the indices that have previously been declared.
</term> </para>
<listitem> </listitem>
<para> </varlistentry>
Rename the </variablelist>
<replaceable class="parameter">oldclassname</replaceable>
class to
<replaceable class="parameter">newclassname</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry> </sect1>
<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"> <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>
</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