From 37c55f9849ca487b64c63a8a0e7cbdc9e5537bee Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sat, 23 Dec 2000 16:24:29 +0000 Subject: [PATCH] Some of the stuff documented here hasn't existed since Postgres95. --- doc/src/sgml/bki.sgml | 636 +++++++++++++++--------------------------- 1 file changed, 222 insertions(+), 414 deletions(-) diff --git a/doc/src/sgml/bki.sgml b/doc/src/sgml/bki.sgml index 9736e93df0..2e4b12f91b 100644 --- a/doc/src/sgml/bki.sgml +++ b/doc/src/sgml/bki.sgml @@ -1,421 +1,229 @@ - + -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 that 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 zero (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. + <acronym>BKI</acronym> Backend Interface + + + Backend Interface (BKI) files are scripts in a + special language 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. (And they are probably not + useful for anything else.) + + + + initdb uses BKI files + to do part of its job when creating a new database cluster. The + input files used by initbd are created as + part of building and installing Postgres + by a program named genbki.sh from some + specially formatted C header files in the source tree. The created + BKI files are called global.bki (for global + catalogs) and template1.bki (for the catalogs + initially stored in the template1 database and then duplicated in + every created database) and are normally installed in the + share subdirectory of the installation tree. + + + + Related information may be found in the documentation for + initdb. + + + + <acronym>BKI</acronym> File Format + + + This section describes how the Postgres + backend interprets BKI files. This description + will be easier to understand if the global.bki + file is at hand as an example. You should also study the source + code of initdb to get an idea of how the + backend is invoked. + + + + BKI input consists of a sequence of commands. Commands are made up + of a number of tokens, depending on the syntax of the command. + Tokens are usually separated by whitespace, but need not be if + there is no ambiguity. There is not special command separator; the + next token that syntactically cannot belong to the preceeding + command starts a new one. (Usually you would put a new command on + a new line, for clarity.) Tokens can be certain key words, special + characters (parentheses, commas, etc.), numbers, or double-quoted + strings. Everything is case sensitive. + + + + Lines starting with a # are ignored. + + + + + + BKI Commands + + + + + open tablename + + + + + Open the table called + tablename + for further manipulation. + + + + + + + close tablename + + + + + Close the open table called tablename. It is an error if + tablename is not + already opened. If no tablename is given, then the + currently open table is closed. + + + + + + + create tablename + (name1 = + type1 , + name2 = type2, ...) + + + + + Create a table named tablename with the columns given + in parentheses. + + + + The type is not necessarily the data + type that the column will have in the SQL environment; that is + determined by the pg_attribute system + catalog. The type here is essentially only used to allocate + storage. The following types are allowed: bool, + bytea, char (1 byte), + name, int2, int2vector, + int4, regproc, text, + oid, tid, xid, + cid, oidvector, smgr, + _int4 (array), _aclitem (array). + Array types can also be indicated by writing + [] after the name of the element type. + + + + + 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 pg_class, + pg_attribute, etc. + + + + + + + + insert OID = oid_value (value1 value2 ...) + + + + + Insert a new row into the open table using value1, value2, etc., for its column + values and oid_value for its OID. If + oid_value is zero + (0) or the clause is ommitted, then the next available OID is + used. + + + + NULL values can be specified using the special key word + _null_. Values containing spaces should be + double quoted. + + + + + + + declare unique index indexname on tablename using amname (opclass1 name1 , ...) + + + + + Create an index named indexname on the table named + tablename using the + amname access + method. The fields to index are called name1, name2 etc., and the operator + classes to use are opclass1, opclass2 etc., respectively. + + + + + + build indices + + + + Build the indices that have previously been declared. + + + + + + + + + Example + + + The following sequence of commands will create the + test_table table with the two columns + cola and colb of type + int4 and text, respectively, and insert + two rows into the table. -create pg_opclass (opcname=name) -open pg_opclass -insert oid=421 (int_ops) -print -close pg_opclass +create test_table (cola = int4, colb = text) +open test_table +insert OID=421 ( 1 "value1" ) +insert OID=422 ( 2 _null_ ) +close test_table - - + +