$Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.5 2002/04/08 22:09:05 tgl Exp $
This directory contains .c files that manipulate the system catalogs
as well as .h files that define the structure of the system catalogs.
When the compile-time scripts (such as Gen_fmgrtab.sh and genbki.sh)
execute, they grep the DATA statements out of the .h files and munge
these in order to generate the .bki files. The .bki files are then
used as input to initdb (which is just a wrapper around postgres
running single-user in bootstrapping mode) in order to generate the
initial (template) system catalog relation files.
-----------------------------------------------------------------
People who are going to hose around with the .h files should be aware
of the following facts:
- It is very important that the DATA statements be properly formatted
(e.g., no broken lines, proper use of white-space and _null_). The
scripts are line-oriented and break easily. In addition, the only
documentation on the proper format for them is the code in the
bootstrap/ directory. Just be careful when adding new DATA
statements.
- Some catalogs require that OIDs be preallocated to tuples because
of cross-references from other pre-loaded tuples. For example, pg_type
contains pointers into pg_proc (e.g., pg_type.typinput), and pg_proc
contains back-pointers into pg_type (pg_proc.proargtypes). For such
cases, the OID assigned to a tuple may be explicitly set by use of the
"OID = n" clause of the .bki insert statement. If no such pointers are
required to a given tuple, then the OID = n clause may be omitted
(then the system generates a random OID in the usual way, or leaves it
0 in a catalog that has no OIDs). In practice we usually preassign OIDs
for all or none of the pre-loaded tuples in a given catalog, even if only
some of them are actually cross-referenced.
- We also sometimes preallocate OIDs for catalog tuples whose OIDs must
be known directly in the C code. In such cases, put a #define in the
catalog's .h file, and use the #define symbol in the C code. Writing
the actual numeric value of any OID in C code is considered very bad form.
(Direct references to pg_proc OIDs are common enough that there's a special
mechanism to create the necessary #define's automatically: see
backend/utils/Gen_fmgrtab.sh. For all the other system catalogs, you have
to manually create any #define's you need.)
- If you need to find a valid OID for a tuple that will be referred to by
others, use the unused_oids script. It generates inclusive ranges of
*unused* OIDs (e.g., the line "45-900" means OIDs 45 through 900 have
not been allocated yet). Currently, OIDs 1-9999 are reserved for manual
assignment; the unused_oids script simply looks through the include/catalog
headers to see which ones do not appear in "OID =" clauses.
- OIDs 10000-16383 are reserved for assignment by the genbki.sh script:
it will insert these OIDs if it sees a clause "OID = 0" in a DATA
statement. You would typically use this feature if you don't care exactly
which OID is assigned to a catalog row (because it has no cross-references
you need to hardwire) but you want to give it a DESCR entry. The DESCR macro
will not work for rows that don't have any OID at genbki.sh time.
- The OID counter starts at 16384 at bootstrap. If a catalog row is in a
table that requires OIDs, but no OID was preassigned by hand or by genbki.sh,
then it will receive an OID of 16384 or above.
- To create a "BOOTSTRAP" table you have to do a lot of extra work: these
tables are not created through a normal CREATE TABLE operation, but spring
into existence when first written to during initdb. Therefore, you must
manually create appropriate entries for them in the pre-loaded contents of
pg_class, pg_attribute, and pg_type. You'll also need to add code to function
heap_create() in heap.c to force the correct OID to be assigned when the table
is first referenced. (It's near the top of the function with the comment
beginning in 'Real ugly stuff'.) Avoid making new catalogs be bootstrap
catalogs if at all possible; generally, only tables that must be written to
in order to create a table should be bootstrapped.
- Certain BOOTSTRAP tables must be at the start of the Makefile
POSTGRES_BKI_SRCS variable, as these will not be created through standard
function means, but will be written directly to disk. That's how pg_class is
created without depending on functions which depend on the existence of
pg_class. The list of files this currently includes is:
pg_proc.h pg_type.h pg_attribute.h pg_class.h
Also, indexing.h must be last, since the indexes can't be created until all
the tables are in place. There are reputedly some other order dependencies
in the .bki list, too.
-----------------------------------------------------------------
When munging the .c files, you should be aware of certain conventions:
- The system catalog cache code (and most catalog-munging code in
general) assumes that the fixed-length portions of all system catalog
tuples are in fact present, because it maps C struct declarations onto
them. Thus, the variable-length fields must all be at the end, and
only the variable-length fields of a catalog tuple are permitted to be
NULL. For example, if you set pg_type.typdelim to be NULL, a
piece of code will likely perform "typetup->typdelim" (or, worse,
"typetyp->typelem", which follows typdelim). This will result in
random errors or even segmentation violations. Hence, do NOT insert
catalog tuples that contain NULL attributes except in their
variable-length portions!
- Modification of the catalogs must be performed with the proper
updating of catalog indexes! That is, most catalogs have indexes
on them; when you munge them using the executor, the executor will
take care of doing the index updates, but if you make direct access
method calls to insert new or modified tuples into a heap, you must
also make the calls to insert the tuple into ALL of its indexes! If
not, the new tuple will generally be "invisible" to the system because
most of the accesses to the catalogs in question will be through the
associated indexes.
9999f5a10e