granicus.if.org Git - postgresql/blob - src/backend/catalog/README

   1 $Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.2 2002/01/04 17:06:51 tgl Exp $
   2
   3 This directory contains .c files that manipulate the system catalogs
   4 as well as .h files that define the structure of the system catalogs.
   5
   6 When the compile-time scripts (such as Gen_fmgrtab.sh and genbki.sh)
   7 execute, they grep the DATA statements out of the .h files and munge
   8 these in order to generate the .bki files.  The .bki files are then
   9 used as input to initdb (which is just a wrapper around postgres
  10 running single-user in bootstrapping mode) in order to generate the
  11 initial (template) system catalog relation files.
  12
  13 -----------------------------------------------------------------
  14
  15 People who are going to hose around with the .h files should be aware
  16 of the following facts:
  17
  18 - It is very important that the DATA statements be properly formatted
  19 (e.g., no broken lines, proper use of white-space and _null_).  The
  20 scripts are line-oriented and break easily.  In addition, the only
  21 documentation on the proper format for them is the code in the
  22 bootstrap/ directory.  Just be careful when adding new DATA
  23 statements.
  24
  25 - 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, the references 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
  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).
  34
  35 If you need to find a valid OID for a set of tuples that refer to each
  36 other, use the unused_oids script.  It generates inclusive ranges of
  37 *unused* OIDs (i.e., the line "45-900" means OIDs 45 through 900 have
  38 not been allocated yet).  However, you should not rely 100% on this
  39 script, since it only looks at the .h files in the catalog/ directory.
  40 Do a pg_grepsrc (recursive grep) of the source tree to insure that
  41 there aren't any hidden crocks (i.e., explicit use of a numeric OID)
  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.)
  46
  47 -----------------------------------------------------------------
  48
  49 When munging the .c files, you should be aware of certain conventions:
  50
  51 - The system catalog cache code (and most catalog-munging code in
  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
  57 piece of code will likely perform "typetup->typdelim" (or, worse,
  58 "typetyp->typelem", which follows typdelim).  This will result in
  59 random errors or even segmentation violations.  Hence, do NOT insert
  60 catalog tuples that contain NULL attributes except in their
  61 variable-length portions!
  62
  63 - Modification of the catalogs must be performed with the proper
  64 updating of catalog indexes!  That is, most catalogs have indexes
  65 on them; when you munge them using the executor, the executor will
  66 take care of doing the index updates, but if you make direct access
  67 method calls to insert new or modified tuples into a heap, you must
  68 also make the calls to insert the tuple into ALL of its indexes!  If
  69 not, the new tuple will generally be "invisible" to the system because
  70 most of the accesses to the catalogs in question will be through the
  71 associated indexes.