From 3aa0395d4ed36f040f20da304c122b956529dd14 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 12 Mar 2019 12:30:35 -0400 Subject: Remove remaining hard-wired OID references in the initial catalog data. In the v11-era commits that taught genbki.pl to resolve symbolic OID references in the initial catalog data, we didn't bother to make every last reference symbolic; some of the catalogs have so few initial rows that it didn't seem worthwhile. However, the new project policy that OIDs assigned by new patches should be automatically renumberable changes this calculus. A patch that wants to add a row in one of these catalogs would have a problem when the OID it assigns gets renumbered. Hence, do the mop-up work needed to make all OID references in initial data be symbolic, and establish an associated project policy that we'll never again write a hard-wired OID reference there. No catversion bump since the contents of postgres.bki aren't actually changed by this commit. Discussion: https://postgr.es/m/CAH2-WzmMTGMcPuph4OvsO7Ykut0AOCF_i-=eaochT0dd2BN9CQ@mail.gmail.com --- doc/src/sgml/bki.sgml | 73 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 28 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/bki.sgml b/doc/src/sgml/bki.sgml index 5f80f9ed24d..0dd753bc6f5 100644 --- a/doc/src/sgml/bki.sgml +++ b/doc/src/sgml/bki.sgml @@ -187,11 +187,10 @@ # A comment could appear here. { oid => '1', oid_symbol => 'TemplateDbOid', descr => 'database\'s default template', - datname => 'template1', datdba => 'PGUID', encoding => 'ENCODING', - datcollate => 'LC_COLLATE', datctype => 'LC_CTYPE', datistemplate => 't', - datallowconn => 't', datconnlimit => '-1', datlastsysoid => '0', - datfrozenxid => '0', datminmxid => '1', dattablespace => '1663', - datacl => '_null_' }, + datname => 'template1', encoding => 'ENCODING', datcollate => 'LC_COLLATE', + datctype => 'LC_CTYPE', datistemplate => 't', datallowconn => 't', + datconnlimit => '-1', datlastsysoid => '0', datfrozenxid => '0', + datminmxid => '1', dattablespace => 'pg_default', datacl => '_null_' }, ] @@ -229,6 +228,9 @@ While the metadata keys are optional, the catalog's defined columns must all be provided, except when the catalog's .h file specifies a default value for the column. + (In the example above, the datdba field has + been omitted because pg_database.h supplies a + suitable default value for it.) @@ -264,8 +266,10 @@ - To aid readability, field values that are OIDs of other catalog - entries can be represented by names rather than numeric OIDs. + Field values that are OIDs of other catalog entries should be + represented by symbolic names rather than actual numeric OIDs. + (In the example above, dattablespace + contains such a reference.) This is described in below. @@ -438,13 +442,13 @@ OID Reference Lookup - Cross-references from one initial catalog row to another can be written - by just writing the preassigned OID of the referenced row. But - that's error-prone and hard to understand, so for frequently-referenced - catalogs, genbki.pl provides mechanisms to write - symbolic references instead. Currently this is possible for references - to access methods, functions, languages, - operators, opclasses, opfamilies, types, and encodings. + In principle, cross-references from one initial catalog row to another + could be written just by writing the preassigned OID of the referenced + row in the referencing field. However, that is against project + policy, because it is error-prone, hard to read, and subject to + breakage if a newly-assigned OID is renumbered. Therefore + genbki.pl provides mechanisms to write + symbolic references instead. The rules are as follows: @@ -455,19 +459,20 @@ Use of symbolic references is enabled in a particular catalog column by attaching BKI_LOOKUP(lookuprule) to the column's definition, where lookuprule - is pg_am, pg_proc, - pg_language, - pg_operator, pg_opclass, - pg_opfamily, - pg_type, - or encoding. + is the name of the referenced catalog, e.g. pg_proc. BKI_LOOKUP can be attached to columns of type Oid, regproc, oidvector, or Oid[]; in the latter two cases it implies performing a lookup on each element of the array. - It's also permissible to attach BKI_LOOKUP - to integer columns; this should be done only for encodings, - which are not currently represented as catalog OIDs. + + + + + + It's also permissible to attach BKI_LOOKUP(encoding) + to integer columns to reference character set encodings, which are + not currently represented as catalog OIDs, but have a set of values + known to genbki.pl. @@ -483,10 +488,11 @@ - Access methods are just represented by their names, as are types. - Type names must match the referenced pg_type - entry's typname; you do not get to use any - aliases such as integer + Most kinds of catalog objects are simply referenced by their names. + Note that type names must exactly match the + referenced pg_type + entry's typname; you do not get to use + any aliases such as integer for int4. @@ -530,7 +536,18 @@ In none of these cases is there any provision for schema-qualification; all objects created during bootstrap are - expected to be in the pg_catalog schema. + expected to be in the pg_catalog schema. + + + + + + In addition to the generic lookup mechanisms, there is a special + convention that PGNSP is replaced by the OID of + the pg_catalog schema, + and PGUID is replaced by the OID of the bootstrap + superuser role. These usages are somewhat historical but so far + there hasn't been a need to generalize them. -- cgit v1.2.3