Home Explore Blog CI



postgresql

8th chunk of `doc/src/sgml/bki.sgml`
3666e1693cf5d37d31f4ffaea42b5b3b511a4b9999682dea0000000100000fa7
 follows:
   </para>

   <itemizedlist>

    <listitem>
     <para>
      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 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.
     </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>

    <listitem>
     <para>
      In some catalog columns, it's allowed for entries to be zero instead
      of a valid reference.  If this is allowed, write
      <literal>BKI_LOOKUP_OPT</literal> instead
      of <literal>BKI_LOOKUP</literal>.  Then you can
      write <literal>0</literal> for an entry.  (If the column is
      declared <type>regproc</type>, you can optionally
      write <literal>-</literal> instead of <literal>0</literal>.)
      Except for this special case, all entries in
      a <literal>BKI_LOOKUP</literal> column must be symbolic references.
      <filename>genbki.pl</filename> will warn about unrecognized names.
     </para>
    </listitem>

    <listitem>
     <para>
      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>

    <listitem>
     <para>
      A function can be represented by
      its <structfield>proname</structfield>, if that is unique among
      the <filename>pg_proc.dat</filename> entries (this works like regproc
      input).  Otherwise, write it
      as <replaceable>proname(argtypename,argtypename,...)</replaceable>,
      like regprocedure.  The argument type names must be spelled exactly as
      they are in the <filename>pg_proc.dat</filename> entry's
      <structfield>proargtypes</structfield> field.  Do not insert any
      spaces.
     </para>
    </listitem>

    <listitem>
     <para>
      Operators are represented
      by <replaceable>oprname(lefttype,righttype)</replaceable>,
      writing the type names exactly as they appear in
      the <filename>pg_operator.dat</filename>
      entry's <structfield>oprleft</structfield>
      and <structfield>oprright</structfield> fields.
      (Write <literal>0</literal> for the omitted operand of a unary
      operator.)
     </para>
    </listitem>

    <listitem>
     <para>
      The names of opclasses and opfamilies are only unique within an
      access method, so they are represented
      by <replaceable>access_method_name</replaceable><literal>/</literal><replaceable>object_name</replaceable>.
     </para>
    </listitem>

    <listitem>
     <para>
      In none of these cases is there any provision for
      schema-qualification; all objects created during bootstrap are
      expected to be in the <literal>pg_catalog</literal> schema.
     </para>
    </listitem>
   </itemizedlist>

   <para>
    <filename>genbki.pl</filename> resolves all symbolic references while it
    runs, and puts simple numeric OIDs into the emitted BKI file.  There is
    therefore no need for the bootstrap backend to deal with symbolic
    references.
   </para>

   <para>
    It's desirable to mark OID reference columns
    with <literal>BKI_LOOKUP</literal>

Title: Symbolic References and BKI_LOOKUP Details
Summary
This section details the use of symbolic references in catalog definitions via the BKI_LOOKUP macro, allowing references to catalog objects by name instead of OID. It covers how to use BKI_LOOKUP for different data types, including Oid, regproc, oidvector, and integer (for encodings). It explains BKI_LOOKUP_OPT for optional references, and how to specify names for various objects like types, functions (including argument type specification), operators, opclasses, and opfamilies. It emphasizes that all objects are expected to be in the pg_catalog schema and genbki.pl resolves these references before bootstrap.