-$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.
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
-*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.
+- 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.)
-- 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:
- pg_proc.h pg_type.h pg_attribute.h pg_class.h
+- 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). 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.
-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'
+- 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
+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.
-----------------------------------------------------------------
projects / postgresql / commitdiff