1- $Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.3 2002/03/19 01 :14:41 momjian Exp $
1+ $Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.4 2002/03/22 20 :14:42 tgl Exp $
22
33This directory contains .c files that manipulate the system catalogs
44as 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
2323statements.
2424
2525- Some catalogs require that OIDs be preallocated to tuples because
26- certain catalogs contain circular references . For example, pg_type
27- contains pointers into pg_proc (pg_type.typinput), and pg_proc
28- contains back-pointers into pg_type (pg_proc.proargtypes).In these
29- cases, thereferences may be explicitly set by use of the "OID ="
30- clause of the .bki insert statement. If no such pointers are required
31- to a given tuple, then the OID may be set to the wildcard value 0
26+ of cross-references from other pre-loaded tuples . For example, pg_type
27+ contains pointers into pg_proc (e.g., pg_type.typinput), and pg_proc
28+ contains back-pointers into pg_type (pg_proc.proargtypes).For such
29+ cases, theOID assigned to a tuple may be explicitly set by use of the
30+ "OID =" clause of the .bki insert statement. If no such pointers are
31+ required to a given tuple, then the OID may be set to the wildcard value 0
3232(i.e., the system generates a random OID in the usual way, or leaves it
33- 0 in a catalog that has no OIDs).
33+ 0 in a catalog that has no OIDs). In practice we usually preassign OIDs
34+ for all or none of the pre-loaded tuples in a given catalog, even if only
35+ some of them are actually cross-referenced.
3436
35- If you need to find a valid OID fora set of tuplesthat refer to each
36- other, use theunused_oids script .It generates inclusive ranges of
37- *unused* OIDs (i.e., theline "45-900" means OIDs 45 through 900 have
38- not been allocated yet). All OIDs that are known directly to C code
39- should be referenced via #defines in the catalog .h files. So
40- unused_oids is sufficient for assigning new OIDs.). The unused_oids
41- script simply 'discovers' those which are free.
37+ - We also sometimes preallocate OIDs forcatalog tupleswhose OIDs must
38+ be known directly in theC code .In such cases, put a #define in the
39+ catalog's .h file, and use the#define symbol in the C code. Writing
40+ the actual numeric value of any OID in C code is considered very bad form.
41+ (Direct references to pg_proc OIDs are common enough that there's a special
42+ mechanism to create the necessary #define's automatically. For all the
43+ other system catalogs, you have to manually create any #define's you need.)
4244
43- -BOOTSTRAP tables must be at the start of the Makefile POSTGRES_BKI_SRCS
44- variable, as these will not be created through standard function means, but
45- will be written directly to disk. Thats how pg_class is created without
46- depending on functions which depend on the existance of pg_class. The
47- list of files this currently includes is:
48- pg_proc.h pg_type.h pg_attribute.h pg_class.h
45+ -If you need to find a valid OID for a tuple that will be referred to by
46+ others, use the unused_oids script. It generates inclusive ranges of
47+ *unused* OIDs (i.e., the line "45-900" means OIDs 45 through 900 have
48+ not been allocated yet). Currently, OIDs 1-9999 are reserved for manual
49+ assignment; the unused_oids script simply looks through the include/catalog
50+ headers to see which ones do not appear in "OID =" clauses.
4951
50- Don't forget to add the entry to heap.c to function heap_create() which
51- sets the OID of the relation when it's a bootstrapped system table. It's
52- near the top of the function with the comment beginning in 'Real ugly stuff'
52+ - To create a "BOOTSTRAP" table you have to do a lot of extra work: these
53+ tables are not created through a normal CREATE TABLE operation, but spring
54+ into existence when first written to during initdb. Therefore, you must
55+ manually create appropriate entries for them in the pre-loaded contents of
56+ pg_class, pg_attribute, and pg_type. You'll also need to add code to function
57+ heap_create() in heap.c to force the correct OID to be assigned when the table
58+ is first referenced. (It's near the top of the function with the comment
59+ beginning in 'Real ugly stuff'.) Avoid making new catalogs be bootstrap
60+ catalogs if at all possible; generally, only tables that must be written to
61+ to create a table should be bootstrapped.
5362
63+ - Certain BOOTSTRAP tables must be at the start of the Makefile
64+ POSTGRES_BKI_SRCS variable, as these will not be created through standard
65+ function means, but will be written directly to disk. That's how pg_class is
66+ created without depending on functions which depend on the existence of
67+ pg_class. The list of files this currently includes is:
68+ pg_proc.h pg_type.h pg_attribute.h pg_class.h
69+ Also, indexing.h must be last, since the indexes can't be created until all
70+ the tables are in place. There are reputedly some other order dependencies
71+ in the .bki list, too.
5472
5573-----------------------------------------------------------------
5674