diff --git a/doc/src/sgml/bki.sgml b/doc/src/sgml/bki.sgml new file mode 100644 index 00000000000..0923b57c676 --- /dev/null +++ b/doc/src/sgml/bki.sgml @@ -0,0 +1,348 @@ + + + +Backend Interface + + +Backend Interface (BKI) files are scripts that are input +to the Postgres +backend running in the special "bootstrap" mode that allows it to perform +database functions without a database system already existing. BKI files +can therefore be used to create the database system in the first place. +initdb +uses BKI files to do just that: to create a database system. However, +initdb's +BKI files are generated internally. It generates them using the files +global1.bki.source and local1.template1.bki.source, which it finds in the +Postgres "library" directory. They get installed there as part of installing +Postgres. These .source files get build as part of the Postgres build +process, by a build program called + genbki. + genbki +takes as input Postgres source files that double as + genbki +input that builds tables and C header files that describe those +tables. + + +Related information may be found in documentation for +initdb, +createdb, +and the SQL command CREATE DATABASE. + + +<acronym>BKI</acronym> File Format + + +The Postgres backend interprets BKI files as described below. This +description will be easier to understand if the global1.bki.source file is +at hand as an example. (As explained above, this .source file isn't quite +a BKI file, but you'll be able to guess what the resulting BKI file would be +anyway). + + +Commands are composed of a command name followed by space separated +arguments. Arguments to a command which begin with a $ are +treated specially. If $$ are the first two characters, then +the first $ is ignored and the argument is then processed +normally. If the $ is followed by space, then it is treated +as a NULL +value. Otherwise, the characters following the $ 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. + + +Macros are defined using + +define macro macro_name = macro_value + +and are undefined using + +undefine macro macro_name + +and redefined using the same syntax as define. + + +Lists of general commands and macro commands +follow. + + +General Commands + + + + +OPEN classname + + + +Open the class called +classname +for further manipulation. + + + +CLOSE [classname] + + + +Close the open class called +classname. +It is an error if +classname +is not already opened. If no +classname +is given, then the currently open class is closed. + + + +PRINT + + + +Print the currently open class. + + + +INSERT [OID=oid_value] (value1 value2 ...) + + + +Insert a new instance to the open class using +value1, +value2, +etc., for its attribute values and +oid_value +for its OID. If +oid_value +is not 0, then this value will be used as the instance's +object identifier. Otherwise, it is an error. + + + +INSERT (value1 value2 ...) + + + +As above, but the system generates a unique object identifier. + + + +CREATE classname (name1 = type1 [,name2 = type2[,...]]) + + + +Create a class named +classname +with the attributes given in parentheses. + + + +OPEN (name1 = type1 [,name2 = type2[,...]]) AS classname + + + +Open a class named +classname +for writing but do not record its existence in the system catalogs. +(This is primarily to aid in bootstrapping.) + + + +DESTROY classname + + + +Destroy the class named +classname. + + + +DEFINE INDEX indexname ON class_name USING amname + (opclass attr | (function(attr)) + + + +Create an index named +indexname +on the class named +classname +using the +amname +access method. The fields to index are called +name1, +name2 +etc., and the operator collections to use are +collection_1, +collection_2 +etc., respectively. + + + + + + +This last sentence doesn't reference anything in the example. Should be changed to make sense. - Thomas 1998-08-04 + + + +Macro Commands + + + + + +DEFINE FUNCTION macro_name AS rettype function_name(args) + + + +Define a function prototype for a function named +macro_name +which has its value of type +rettype +computed from the execution +function_name +with the arguments +args +declared in a C-like manner. + + + +DEFINE MACRO macro_name FROM FILE filename + + + +Define a macro named +macro_name +which has its value +read from the file called +filename. + + + + + +Debugging Commands + + + + +This section on debugging commands was commented-out in the original documentation. Thomas 1998-08-05 + + + + + +r + + + +Randomly print the open class. + + + +m -1 + + + +Toggle display of time information. + + + +m 0 + + + +Set retrievals to now. + + + +m 1 Jan 1 01:00:00 1988 + + + +Set retrievals to snapshots of the specfied time. + + + +m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988 + + + +Set retrievals to ranges of the specified times. +Either time may be replaced with space +if an unbounded time range is desired. + + + +&A classname natts name1 type1 name2 type2 ... + + + +Add +natts +attributes named +name1, +name2, +etc. of +types +type1, +type2, +etc. to the class +classname. + + + +&RR oldclassname newclassname + + + +Rename the +oldclassname +class to +newclassname. + + + +&RA classname oldattname newattname +classname +oldattname +newattname + + + +Rename the +oldattname +attribute in the class named +classname +to +newattname. + + + + + +Example + + +The following set of commands will create the pg_opclass +class containing the +int_ops +collection as an object with an OID of +421, +print out the class, and then close it. + +create pg_opclass (opcname=name) +open pg_opclass +insert oid=421 (int_ops) +print +close pg_opclass + + + diff --git a/doc/src/sgml/page.sgml b/doc/src/sgml/page.sgml new file mode 100644 index 00000000000..b880dbdca00 --- /dev/null +++ b/doc/src/sgml/page.sgml @@ -0,0 +1,181 @@ + + +Page Files + + + +A description of the database file default page format. + + + + +This section provides an overview of the page format used by Postgres +classes. User-defined access methods need not use this page format. + + +In the following explanation, a +byte +is assumed to contain 8 bits. In addition, the term +item +refers to data which is stored in Postgres classes. + + +The following table shows how pages in both normal Postgres classes + and Postgres index +classes (e.g., a B-tree index) are structured. + + +Sample Page Layout +Page Layout + + + + + + + + + + + + +itemPointerData + + + +filler + + + +itemData... + + + +Unallocated Space + + + +ItemContinuationData + + + +Special Space + + + +``ItemData 2'' + + + +``ItemData 1'' + + + +ItemIdData + + + +PageHeaderData + + + +
+ + + + +The first 8 bytes of each page consists of a page header +(PageHeaderData). +Within the header, the first three 2-byte integer fields +(lower, +upper, +and +special) +represent byte offsets to the start of unallocated space, to the end +of unallocated space, and to the start of special space. +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, +opaque, +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. + + +Following the page header are item identifiers +(ItemIdData). +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 +(ItemPointer) +created by Postgres 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. + + +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 +(ItemContinuationData). +This structure contains +itemPointerData +which points to the next piece and the piece itself. The last piece +is handled normally. + + +Files + + + + + +data/ + + + +Location of shared (global) database files. + + + +data/base/ + + + +Location of local database files. + + + + +Bugs + + +The page format may change in the future to provide more efficient +access to large objects. + + +This section contains insufficient detail to be of any assistance in +writing a new access method. + +