2002-04-27 23:24:34 +02:00
|
|
|
$Header: /cvsroot/pgsql/src/backend/catalog/README,v 1.7 2002/04/27 21:24:33 tgl Exp $
|
1996-07-09 08:22:35 +02:00
|
|
|
|
2002-04-16 01:46:13 +02:00
|
|
|
This directory contains .c files that manipulate the system catalogs;
|
|
|
|
src/include/catalog contains the .h files that define the structure
|
|
|
|
of the system catalogs.
|
1996-07-09 08:22:35 +02:00
|
|
|
|
|
|
|
When the compile-time scripts (such as Gen_fmgrtab.sh and genbki.sh)
|
|
|
|
execute, they grep the DATA statements out of the .h files and munge
|
|
|
|
these in order to generate the .bki files. The .bki files are then
|
|
|
|
used as input to initdb (which is just a wrapper around postgres
|
|
|
|
running single-user in bootstrapping mode) in order to generate the
|
|
|
|
initial (template) system catalog relation files.
|
|
|
|
|
|
|
|
-----------------------------------------------------------------
|
|
|
|
|
|
|
|
People who are going to hose around with the .h files should be aware
|
|
|
|
of the following facts:
|
|
|
|
|
|
|
|
- It is very important that the DATA statements be properly formatted
|
|
|
|
(e.g., no broken lines, proper use of white-space and _null_). The
|
|
|
|
scripts are line-oriented and break easily. In addition, the only
|
|
|
|
documentation on the proper format for them is the code in the
|
|
|
|
bootstrap/ directory. Just be careful when adding new DATA
|
|
|
|
statements.
|
|
|
|
|
|
|
|
- Some catalogs require that OIDs be preallocated to tuples because
|
2002-03-22 21:14:42 +01:00
|
|
|
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
|
2002-04-09 00:09:05 +02:00
|
|
|
"OID = n" clause of the .bki insert statement. If no such pointers are
|
|
|
|
required to a given tuple, then the OID = n clause may be omitted
|
|
|
|
(then the system generates a random OID in the usual way, or leaves it
|
2002-03-22 21:14:42 +01:00
|
|
|
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.
|
1996-07-09 08:22:35 +02:00
|
|
|
|
2002-03-22 21:14:42 +01:00
|
|
|
- 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
|
2002-04-09 00:09:05 +02:00
|
|
|
mechanism to create the necessary #define's automatically: see
|
|
|
|
backend/utils/Gen_fmgrtab.sh. For all the other system catalogs, you have
|
|
|
|
to manually create any #define's you need.)
|
2002-03-22 21:14:42 +01:00
|
|
|
|
|
|
|
- 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
|
2002-04-09 00:09:05 +02:00
|
|
|
*unused* OIDs (e.g., the line "45-900" means OIDs 45 through 900 have
|
2002-03-22 21:14:42 +01:00
|
|
|
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.
|
2002-03-19 02:14:41 +01:00
|
|
|
|
2002-04-09 00:09:05 +02:00
|
|
|
- OIDs 10000-16383 are reserved for assignment by the genbki.sh script:
|
|
|
|
it will insert these OIDs if it sees a clause "OID = 0" in a DATA
|
|
|
|
statement. You would typically use this feature if you don't care exactly
|
|
|
|
which OID is assigned to a catalog row (because it has no cross-references
|
|
|
|
you need to hardwire) but you want to give it a DESCR entry. The DESCR macro
|
|
|
|
will not work for rows that don't have any OID at genbki.sh time.
|
|
|
|
|
|
|
|
- The OID counter starts at 16384 at bootstrap. If a catalog row is in a
|
|
|
|
table that requires OIDs, but no OID was preassigned by hand or by genbki.sh,
|
|
|
|
then it will receive an OID of 16384 or above.
|
|
|
|
|
2002-03-22 21:14:42 +01:00
|
|
|
- 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
|
2002-04-27 23:24:34 +02:00
|
|
|
beginning in "Real ugly stuff".) Avoid making new catalogs be bootstrap
|
2002-03-22 21:14:42 +01:00
|
|
|
catalogs if at all possible; generally, only tables that must be written to
|
2002-04-09 00:09:05 +02:00
|
|
|
in order to create a table should be bootstrapped.
|
2002-03-19 02:14:41 +01:00
|
|
|
|
2002-03-22 21:14:42 +01:00
|
|
|
- Certain BOOTSTRAP tables must be at the start of the Makefile
|
2002-04-27 23:24:34 +02:00
|
|
|
POSTGRES_BKI_SRCS variable, as these will not be created through the standard
|
|
|
|
heap_create_with_catalog process, because it needs these tables to exist
|
|
|
|
already. The list of files this currently includes is:
|
2002-03-22 21:14:42 +01:00
|
|
|
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.
|
1996-07-09 08:22:35 +02:00
|
|
|
|
|
|
|
-----------------------------------------------------------------
|
|
|
|
|
|
|
|
When munging the .c files, you should be aware of certain conventions:
|
|
|
|
|
|
|
|
- The system catalog cache code (and most catalog-munging code in
|
2002-01-04 18:06:51 +01:00
|
|
|
general) assumes that the fixed-length portions of all system catalog
|
|
|
|
tuples are in fact present, because it maps C struct declarations onto
|
|
|
|
them. Thus, the variable-length fields must all be at the end, and
|
|
|
|
only the variable-length fields of a catalog tuple are permitted to be
|
|
|
|
NULL. For example, if you set pg_type.typdelim to be NULL, a
|
1996-07-09 08:22:35 +02:00
|
|
|
piece of code will likely perform "typetup->typdelim" (or, worse,
|
|
|
|
"typetyp->typelem", which follows typdelim). This will result in
|
|
|
|
random errors or even segmentation violations. Hence, do NOT insert
|
|
|
|
catalog tuples that contain NULL attributes except in their
|
|
|
|
variable-length portions!
|
|
|
|
|
|
|
|
- Modification of the catalogs must be performed with the proper
|
2002-01-04 18:06:51 +01:00
|
|
|
updating of catalog indexes! That is, most catalogs have indexes
|
1996-07-09 08:22:35 +02:00
|
|
|
on them; when you munge them using the executor, the executor will
|
|
|
|
take care of doing the index updates, but if you make direct access
|
|
|
|
method calls to insert new or modified tuples into a heap, you must
|
|
|
|
also make the calls to insert the tuple into ALL of its indexes! If
|
|
|
|
not, the new tuple will generally be "invisible" to the system because
|
|
|
|
most of the accesses to the catalogs in question will be through the
|
|
|
|
associated indexes.
|