From 48c916490179e4a1db93e0924a72c3e4f1f00e55 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 22 Mar 2002 20:14:42 +0000 Subject: [PATCH] Improve catalog commentary. --- src/backend/catalog/README | 66 ++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/src/backend/catalog/README b/src/backend/catalog/README index a39131b09f..f6f6210970 100644 --- a/src/backend/catalog/README +++ b/src/backend/catalog/README @@ -1,4 +1,4 @@ -$Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.3 2002/03/19 01:14:41 momjian Exp $ +$Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.4 2002/03/22 20:14:42 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. @@ -23,34 +23,52 @@ bootstrap/ directory. Just be careful when adding new DATA statements. - Some catalogs require that OIDs be preallocated to tuples because -certain catalogs contain circular references. For example, pg_type -contains pointers into pg_proc (pg_type.typinput), and pg_proc -contains back-pointers into pg_type (pg_proc.proargtypes). In these -cases, the references may be explicitly set by use of the "OID =" -clause of the .bki insert statement. If no such pointers are required -to a given tuple, then the OID may be set to the wildcard value 0 +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 =" clause of the .bki insert statement. If no such pointers are +required to a given tuple, then the OID may be set to the wildcard value 0 (i.e., the system generates a random OID in the usual way, or leaves it -0 in a catalog that has no OIDs). +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. -If you need to find a valid OID for a set of tuples that refer to each -other, use the unused_oids script. It generates inclusive ranges of +- 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. 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 (i.e., the line "45-900" means OIDs 45 through 900 have -not been allocated yet). All OIDs that are known directly to C code -should be referenced via #defines in the catalog .h files. So -unused_oids is sufficient for assigning new OIDs.). The unused_oids -script simply 'discovers' those which are free. +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. -- 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. Thats how pg_class is created without -depending on functions which depend on the existance of pg_class. The -list of files this currently includes is: +- 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 +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 - -Don't forget to add the entry to heap.c to function heap_create() which -sets the OID of the relation when it's a bootstrapped system table. It's -near the top of the function with the comment beginning in 'Real ugly stuff' - +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. -----------------------------------------------------------------