Convert information from man pages. Not really suitable for man pages
anyway, so this will replace them as of now.
This commit is contained in:
Thomas G. Lockhart
parent
4b11e394bc
commit
45816ec4d2
348
doc/src/sgml/bki.sgml
Normal file
348
doc/src/sgml/bki.sgml
Normal file
@ -0,0 +1,348 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/bki.sgml,v 1.1 1998/08/15 06:49:33 thomas Exp $
|
||||
|
||||
Transcribed from the original bki.man.5 documentation
|
||||
- Thomas Lockhart 1998-08-03
|
||||
-->
|
||||
|
||||
<chapter id="bki">
|
||||
<title>Backend Interface</title>
|
||||
|
||||
<para>
|
||||
Backend Interface (<acronym>BKI</acronym>) files are scripts that are input
|
||||
to the <productname>Postgres</productname>
|
||||
backend running in the special "bootstrap" 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.
|
||||
<application>initdb</application>
|
||||
uses <acronym>BKI</acronym> files to do just that: to create a database system. However,
|
||||
<application>initdb</application>'s
|
||||
<acronym>BKI</acronym> files are generated internally. It generates them using the files
|
||||
<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>
|
||||
Related information may be found in documentation for
|
||||
<application>initdb</application>,
|
||||
<application>createdb</application>,
|
||||
and the <acronym>SQL</acronym> command <command>CREATE DATABASE</command>.
|
||||
|
||||
<sect1>
|
||||
<title><acronym>BKI</acronym> File Format</title>
|
||||
|
||||
<para>
|
||||
The <productname>Postgres</productname> backend interprets <acronym>BKI</acronym> files as described below. This
|
||||
description will be easier to understand if the <filename>global1.bki.source</filename> file is
|
||||
at hand as an example. (As explained above, this .source file isn't quite
|
||||
a <acronym>BKI</acronym> file, but you'll be able to guess what the resulting <acronym>BKI</acronym> file would be
|
||||
anyway).
|
||||
|
||||
<para>
|
||||
Commands are composed of a command name followed by space separated
|
||||
arguments. Arguments to a command which begin with a <quote>$</quote> are
|
||||
treated specially. If <quote>$$</quote> are the first two characters, then
|
||||
the first <quote>$</quote> is ignored and the argument is then processed
|
||||
normally. If the <quote>$</quote> is followed by space, then it is treated
|
||||
as a NULL
|
||||
value. Otherwise, the characters following the <quote>$</quote> are
|
||||
interpreted as the name of a macro causing the argument to be replaced
|
||||
with the macro's value. It is an error for this macro to be
|
||||
undefined.
|
||||
|
||||
<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>
|
||||
Lists of general commands and macro commands
|
||||
follow.
|
||||
|
||||
<sect1>
|
||||
<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.
|
||||
|
||||
<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.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
PRINT
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Print the currently open class.
|
||||
|
||||
<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 <quote>0</quote>, then this value will be used as the instance's
|
||||
object identifier. Otherwise, it is an error.
|
||||
|
||||
<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.
|
||||
|
||||
<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.
|
||||
|
||||
<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.)
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
DESTROY <replaceable class="parameter">classname</replaceable>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Destroy the class named
|
||||
<replaceable class="parameter">classname</replaceable>.
|
||||
|
||||
<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.
|
||||
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04
|
||||
</note>
|
||||
|
||||
<sect1>
|
||||
<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.
|
||||
|
||||
<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>.
|
||||
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<sect1>
|
||||
<title>Debugging Commands</title>
|
||||
|
||||
<para>
|
||||
<note>
|
||||
<para>
|
||||
This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05
|
||||
</note>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
r
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Randomly print the open class.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
m -1
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Toggle display of time information.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
m 0
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Set retrievals to now.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
m 1 Jan 1 01:00:00 1988
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Set retrievals to snapshots of the specfied time.
|
||||
|
||||
<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.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
&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>.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
&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>.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
&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>.
|
||||
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<sect1>
|
||||
<title>Example</title>
|
||||
|
||||
<para>
|
||||
The following set of commands will create the <quote>pg_opclass</quote>
|
||||
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>
|
||||
create pg_opclass (opcname=name)
|
||||
open pg_opclass
|
||||
insert oid=421 (int_ops)
|
||||
print
|
||||
close pg_opclass
|
||||
</programlisting>
|
||||
|
||||
</chapter>
|
||||
181
doc/src/sgml/page.sgml
Normal file
181
doc/src/sgml/page.sgml
Normal file
@ -0,0 +1,181 @@
|
||||
<chapter id="page">
|
||||
|
||||
<title>Page Files</title>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
A description of the database file default page format.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
<para>
|
||||
This section provides an overview of the page format used by <productname>Postgres</productname>
|
||||
classes. User-defined access methods need not use this page format.
|
||||
|
||||
<para>
|
||||
In the following explanation, a
|
||||
<firstterm>byte</firstterm>
|
||||
is assumed to contain 8 bits. In addition, the term
|
||||
<firstterm>item</firstterm>
|
||||
refers to data which is stored in <productname>Postgres</productname> classes.
|
||||
|
||||
<para>
|
||||
The following table shows how pages in both normal <productname>Postgres</productname> classes
|
||||
and <productname>Postgres</productname> index
|
||||
classes (e.g., a B-tree index) are structured.
|
||||
|
||||
<table tocentry="1">
|
||||
<title>Sample Page Layout</title>
|
||||
<titleabbrev>Page Layout</titleabbrev>
|
||||
<tgroup cols="1">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>
|
||||
</entry>
|
||||
<entry>
|
||||
</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>
|
||||
itemPointerData
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
filler
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
itemData...
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
Unallocated Space
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
ItemContinuationData
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
Special Space
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
``ItemData 2''
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
``ItemData 1''
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
ItemIdData
|
||||
</entry>
|
||||
<row>
|
||||
<entry>
|
||||
PageHeaderData
|
||||
</entry>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<!--
|
||||
.\" Running
|
||||
.\" .q .../bin/dumpbpages
|
||||
.\" or
|
||||
.\" .q .../src/support/dumpbpages
|
||||
.\" as the postgres superuser
|
||||
.\" with the file paths associated with
|
||||
.\" (heap or B-tree index) classes,
|
||||
.\" .q .../data/base/<database-name>/<class-name>,
|
||||
.\" will display the page structure used by the classes.
|
||||
.\" Specifying the
|
||||
.\" .q -r
|
||||
.\" flag will cause the classes to be
|
||||
.\" treated as heap classes and for more information to be displayed.
|
||||
-->
|
||||
|
||||
<para>
|
||||
The first 8 bytes of each page consists of a page header
|
||||
(PageHeaderData).
|
||||
Within the header, the first three 2-byte integer fields
|
||||
(<firstterm>lower</firstterm>,
|
||||
<firstterm>upper</firstterm>,
|
||||
and
|
||||
<firstterm>special</firstterm>)
|
||||
represent byte offsets to the start of unallocated space, to the end
|
||||
of unallocated space, and to the start of <firstterm>special space</firstterm>.
|
||||
Special space is a region at the end of the page which is allocated at
|
||||
page initialization time and which contains information specific to an
|
||||
access method. The last 2 bytes of the page header,
|
||||
<firstterm>opaque</firstterm>,
|
||||
encode the page size and information on the internal fragmentation of
|
||||
the page. Page size is stored in each page because frames in the
|
||||
buffer pool may be subdivided into equal sized pages on a frame by
|
||||
frame basis within a class. The internal fragmentation information is
|
||||
used to aid in determining when page reorganization should occur.
|
||||
|
||||
<para>
|
||||
Following the page header are item identifiers
|
||||
(<firstterm>ItemIdData</firstterm>).
|
||||
New item identifiers are allocated from the first four bytes of
|
||||
unallocated space. Because an item identifier is never moved until it
|
||||
is freed, its index may be used to indicate the location of an item on
|
||||
a page. In fact, every pointer to an item
|
||||
(<firstterm>ItemPointer</firstterm>)
|
||||
created by <productname>Postgres</productname> consists of a frame number and an index of an item
|
||||
identifier. An item identifier contains a byte-offset to the start of
|
||||
an item, its length in bytes, and a set of attribute bits which affect
|
||||
its interpretation.
|
||||
|
||||
<para>
|
||||
The items themselves are stored in space allocated backwards from
|
||||
the end of unallocated space. Usually, the items are not interpreted.
|
||||
However when the item is too long to be placed on a single page or
|
||||
when fragmentation of the item is desired, the item is divided and
|
||||
each piece is handled as distinct items in the following manner. The
|
||||
first through the next to last piece are placed in an item
|
||||
continuation structure
|
||||
(<firstterm>ItemContinuationData</firstterm>).
|
||||
This structure contains
|
||||
itemPointerData
|
||||
which points to the next piece and the piece itself. The last piece
|
||||
is handled normally.
|
||||
|
||||
<sect1>
|
||||
<title>Files</title>
|
||||
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<filename>data/</filename>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Location of shared (global) database files.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<filename>data/base/</filename>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Location of local database files.
|
||||
|
||||
</variablelist>
|
||||
|
||||
<sect1>
|
||||
<title>Bugs</title>
|
||||
|
||||
<para>
|
||||
The page format may change in the future to provide more efficient
|
||||
access to large objects.
|
||||
|
||||
<para>
|
||||
This section contains insufficient detail to be of any assistance in
|
||||
writing a new access method.
|
||||
|
||||
</chapter>
|
||||
Loading…
Reference in New Issue
Block a user