1- $Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.1.1.1 1996/07/09 06:21:15 scrappy Exp $
1+ $Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.2 2002/01/04 17: 06:51 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.
@@ -29,7 +29,8 @@ contains back-pointers into pg_type (pg_proc.proargtypes). In these
2929cases, the references may be explicitly set by use of the "OID ="
3030clause of the .bki insert statement. If no such pointers are required
3131to a given tuple, then the OID may be set to the wildcard value 0
32- (i.e., the system generates a random OID in the usual way).
32+ (i.e., the system generates a random OID in the usual way, or leaves it
33+ 0 in a catalog that has no OIDs).
3334
3435If you need to find a valid OID for a set of tuples that refer to each
3536other, use the unused_oids script. It generates inclusive ranges of
@@ -38,25 +39,29 @@ not been allocated yet). However, you should not rely 100% on this
3839script, since it only looks at the .h files in the catalog/ directory.
3940Do a pg_grepsrc (recursive grep) of the source tree to insure that
4041there aren't any hidden crocks (i.e., explicit use of a numeric OID)
41- anywhere in the code.
42+ anywhere in the code. (tgl 1/2002: that advice is obsolete; there are
43+ no hardcoded uses of OIDs in the C files anymore. All OIDs that are known
44+ directly to C code should be referenced via #defines in the catalog .h files.
45+ So unused_oids is sufficient for assigning new OIDs.)
4246
4347-----------------------------------------------------------------
4448
4549When munging the .c files, you should be aware of certain conventions:
4650
4751- The system catalog cache code (and most catalog-munging code in
48- general) assumes that the fixed-length portion of all system catalog
49- tuples are in fact present. That is, only the variable-length
50- portions of a catalog tuple are assumed to be permitted to be
51- non-NULL. For example, if you set pg_type.typdelim to be NULL, a
52+ general) assumes that the fixed-length portions of all system catalog
53+ tuples are in fact present, because it maps C struct declarations onto
54+ them. Thus, the variable-length fields must all be at the end, and
55+ only the variable-length fields of a catalog tuple are permitted to be
56+ NULL. For example, if you set pg_type.typdelim to be NULL, a
5257piece of code will likely perform "typetup->typdelim" (or, worse,
5358"typetyp->typelem", which follows typdelim). This will result in
5459random errors or even segmentation violations. Hence, do NOT insert
5560catalog tuples that contain NULL attributes except in their
5661variable-length portions!
5762
5863- Modification of the catalogs must be performed with the proper
59- updating of catalog indexes! That is,several catalogs have indexes
64+ updating of catalog indexes! That is,most catalogs have indexes
6065on them; when you munge them using the executor, the executor will
6166take care of doing the index updates, but if you make direct access
6267method calls to insert new or modified tuples into a heap, you must