aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/bki.sgml73
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>