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

   1 $PostgreSQL: pgsql/src/backend/catalog/README,v 1.10 2006/07/31 01:16:36 tgl Exp $
   2
   3 This directory contains .c files that manipulate the system catalogs;
   4 src/include/catalog contains the .h files that define the structure
   5 of the system catalogs.
   6
   7 When the compile-time scripts (such as Gen_fmgrtab.sh and genbki.sh)
   8 execute, they grep the DATA statements out of the .h files and munge
   9 these in order to generate the postgres.bki file.  The .bki file is then
  10 used as input to initdb (which is just a wrapper around postgres
  11 running single-user in bootstrapping mode) in order to generate the
  12 initial (template) system catalog relation files.
  13
  14 -----------------------------------------------------------------
  15
  16 People who are going to hose around with the .h files should be aware
  17 of the following facts:
  18
  19 - It is very important that the DATA statements be properly formatted
  20 (e.g., no broken lines, proper use of white-space and _null_).  The
  21 scripts are line-oriented and break easily.  In addition, the only
  22 documentation on the proper format for them is the code in the
  23 bootstrap/ directory.  Just be careful when adding new DATA
  24 statements.
  25
  26 - Some catalogs require that OIDs be preallocated to tuples because
  27 of cross-references from other pre-loaded tuples.  For example, pg_type
  28 contains pointers into pg_proc (e.g., pg_type.typinput), and pg_proc
  29 contains back-pointers into pg_type (pg_proc.proargtypes).  For such
  30 cases, the OID assigned to a tuple may be explicitly set by use of the
  31 "OID = n" clause of the .bki insert statement.  If no such pointers are
  32 required to a given tuple, then the OID = n clause may be omitted
  33 (then the system generates an OID in the usual way, or leaves it 0 in a
  34 catalog that has no OIDs).  In practice we usually preassign OIDs
  35 for all or none of the pre-loaded tuples in a given catalog, even if only
  36 some of them are actually cross-referenced.
  37
  38 - We also sometimes preallocate OIDs for catalog tuples whose OIDs must
  39 be known directly in the C code.  In such cases, put a #define in the
  40 catalog's .h file, and use the #define symbol in the C code.  Writing
  41 the actual numeric value of any OID in C code is considered very bad form.
  42 Direct references to pg_proc OIDs are common enough that there's a special
  43 mechanism to create the necessary #define's automatically: see
  44 backend/utils/Gen_fmgrtab.sh.  We also have standard conventions for setting
  45 up #define's for the pg_class OIDs of system catalogs and indexes.  For all
  46 the other system catalogs, you have to manually create any #define's you
  47 need.
  48
  49 - If you need to find a valid OID for a new predefined tuple,
  50 use the unused_oids script.  It generates inclusive ranges of
  51 *unused* OIDs (e.g., the line "45-900" means OIDs 45 through 900 have
  52 not been allocated yet).  Currently, OIDs 1-9999 are reserved for manual
  53 assignment; the unused_oids script simply looks through the include/catalog
  54 headers to see which ones do not appear in "OID =" clauses in DATA lines.
  55 (As of Postgres 8.1, it also looks at CATALOG and DECLARE_INDEX lines.)
  56 You can also use the duplicate_oids script to check for mistakes.
  57
  58 - The OID counter starts at 10000 at bootstrap.  If a catalog row is in a
  59 table that requires OIDs, but no OID was preassigned by an "OID =" clause,
  60 then it will receive an OID of 10000 or above.
  61
  62 - To create a "BOOTSTRAP" table you have to do a lot of extra work: these
  63 tables are not created through a normal CREATE TABLE operation, but spring
  64 into existence when first written to during initdb.  Therefore, you must
  65 manually create appropriate entries for them in the pre-loaded contents of
  66 pg_class, pg_attribute, and pg_type.  Avoid making new catalogs be bootstrap
  67 catalogs if at all possible; generally, only tables that must be written to
  68 in order to create a table should be bootstrapped.
  69
  70 - Certain BOOTSTRAP tables must be at the start of the Makefile
  71 POSTGRES_BKI_SRCS variable, as these cannot be created through the standard
  72 heap_create_with_catalog process, because it needs these tables to exist
  73 already.  The list of files this currently includes is:
  74         pg_proc.h pg_type.h pg_attribute.h pg_class.h
  75 Also, indexing.h must be last, since the indexes can't be created until all
  76 the tables are in place, and toasting.h should probably be next-to-last
  77 (or at least after all the tables that need toast tables).  There are
  78 reputedly some other order dependencies in the .bki list, too.
  79
  80 -----------------------------------------------------------------
  81
  82 When munging the .c files, you should be aware of certain conventions:
  83
  84 - The system catalog cache code (and most catalog-munging code in
  85 general) assumes that the fixed-length portions of all system catalog
  86 tuples are in fact present, because it maps C struct declarations onto
  87 them.  Thus, the variable-length fields must all be at the end, and
  88 only the variable-length fields of a catalog tuple are permitted to be
  89 NULL.  For example, if you set pg_type.typdelim to be NULL, a
  90 piece of code will likely perform "typetup->typdelim" (or, worse,
  91 "typetyp->typelem", which follows typdelim).  This will result in
  92 random errors or even segmentation violations.  Hence, do NOT insert
  93 catalog tuples that contain NULL attributes except in their
  94 variable-length portions!  (The bootstrapping code is fairly good about
  95 marking NOT NULL each of the columns that can legally be referenced via
  96 C struct declarations ... but those markings won't be enforced against
  97 DATA commands, so you must get it right in a DATA line.)
  98
  99 - Modification of the catalogs must be performed with the proper
 100 updating of catalog indexes!  That is, most catalogs have indexes
 101 on them; when you munge them using the executor, the executor will
 102 take care of doing the index updates, but if you make direct access
 103 method calls to insert new or modified tuples into a heap, you must
 104 also make the calls to insert the tuple into ALL of its indexes!  If
 105 not, the new tuple will generally be "invisible" to the system because
 106 most of the accesses to the catalogs in question will be through the
 107 associated indexes.