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

1 files changed, 45 insertions, 28 deletions

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_' },
 
 ]
 </programlisting>
@@ -229,6 +228,9 @@
       While the metadata keys are optional, the catalog's defined columns
       must all be provided, except when the catalog's <literal>.h</literal>
       file specifies a default value for the column.
+      (In the example above, the <structfield>datdba</structfield> field has
+      been omitted because <filename>pg_database.h</filename> supplies a
+      suitable default value for it.)
      </para>
     </listitem>
 
@@ -264,8 +266,10 @@
 
     <listitem>
      <para>
-      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, <structfield>dattablespace</structfield>
+      contains such a reference.)
       This is described in <xref linkend="system-catalog-oid-references"/>
       below.
      </para>
@@ -438,13 +442,13 @@
    <title>OID Reference Lookup</title>
 
    <para>
-    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, <filename>genbki.pl</filename> 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
+    <filename>genbki.pl</filename> provides mechanisms to write
+    symbolic references instead.
     The rules are as follows:
    </para>
 
@@ -455,19 +459,20 @@
       Use of symbolic references is enabled in a particular catalog column
       by attaching <literal>BKI_LOOKUP(<replaceable>lookuprule</replaceable>)</literal>
       to the column's definition, where <replaceable>lookuprule</replaceable>
-      is <literal>pg_am</literal>, <literal>pg_proc</literal>,
-      <literal>pg_language</literal>,
-      <literal>pg_operator</literal>, <literal>pg_opclass</literal>,
-      <literal>pg_opfamily</literal>,
-      <literal>pg_type</literal>,
-      or <literal>encoding</literal>.
+      is the name of the referenced catalog, e.g. <literal>pg_proc</literal>.
       <literal>BKI_LOOKUP</literal> can be attached to columns of
       type <type>Oid</type>, <type>regproc</type>, <type>oidvector</type>,
       or <type>Oid[]</type>; in the latter two cases it implies performing a
       lookup on each element of the array.
-      It's also permissible to attach <literal>BKI_LOOKUP</literal>
-      to integer columns; this should be done only for encodings,
-      which are not currently represented as catalog OIDs.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      It's also permissible to attach <literal>BKI_LOOKUP(encoding)</literal>
+      to integer columns to reference character set encodings, which are
+      not currently represented as catalog OIDs, but have a set of values
+      known to <filename>genbki.pl</filename>.
      </para>
     </listitem>
 
@@ -483,10 +488,11 @@
 
     <listitem>
      <para>
-      Access methods are just represented by their names, as are types.
-      Type names must match the referenced <structname>pg_type</structname>
-      entry's <structfield>typname</structfield>; you do not get to use any
-      aliases such as <literal>integer</literal>
+      Most kinds of catalog objects are simply referenced by their names.
+      Note that type names must exactly match the
+      referenced <structname>pg_type</structname>
+      entry's <structfield>typname</structfield>; you do not get to use
+      any aliases such as <literal>integer</literal>
       for <literal>int4</literal>.
      </para>
     </listitem>
@@ -530,7 +536,18 @@
      <para>
       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 <literal>pg_catalog</literal> schema.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      In addition to the generic lookup mechanisms, there is a special
+      convention that <literal>PGNSP</literal> is replaced by the OID of
+      the <literal>pg_catalog</literal> schema,
+      and <literal>PGUID</literal> 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.
      </para>
     </listitem>
    </itemizedlist>