begriffs open source - ai-pg/blob - full-docs/html/system-catalog-declarations.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>68.1. System Catalog Declaration Rules</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="bki.html" title="Chapter 68. System Catalog Declarations and Initial Contents" /><link rel="next" href="system-catalog-initial-data.html" title="68.2. System Catalog Initial Data" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">68.1. System Catalog Declaration Rules</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="bki.html" title="Chapter 68. System Catalog Declarations and Initial Contents">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="bki.html" title="Chapter 68. System Catalog Declarations and Initial Contents">Up</a></td><th width="60%" align="center">Chapter 68. System Catalog Declarations and Initial Contents</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="system-catalog-initial-data.html" title="68.2. System Catalog Initial Data">Next</a></td></tr></table><hr /></div><div class="sect1" id="SYSTEM-CATALOG-DECLARATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">68.1. System Catalog Declaration Rules <a href="#SYSTEM-CATALOG-DECLARATIONS" class="id_link">#</a></h2></div></div></div><p>
   3    The key part of a catalog header file is a C structure definition
   4    describing the layout of each row of the catalog.  This begins with
   5    a <code class="literal">CATALOG</code> macro, which so far as the C compiler is
   6    concerned is just shorthand for <code class="literal">typedef struct
   7    FormData_<em class="replaceable"><code>catalogname</code></em></code>.
   8    Each field in the struct gives rise to a catalog column.
   9    Fields can be annotated using the BKI property macros described
  10    in <code class="filename">genbki.h</code>, for example to define a default value
  11    for a field or mark it as nullable or not nullable.
  12    The <code class="literal">CATALOG</code> line can also be annotated, with some
  13    other BKI property macros described in <code class="filename">genbki.h</code>, to
  14    define other properties of the catalog as a whole, such as whether
  15    it is a shared relation.
  16   </p><p>
  17    The system catalog cache code (and most catalog-munging code in general)
  18    assumes that the fixed-length portions of all system catalog tuples are
  19    in fact present, because it maps this C struct declaration onto them.
  20    Thus, all variable-length fields and nullable fields must be placed at
  21    the end, and they cannot be accessed as struct fields.
  22    For example, if you tried to
  23    set <code class="structname">pg_type</code>.<code class="structfield">typrelid</code>
  24    to be NULL, it would fail when some piece of code tried to reference
  25    <code class="literal">typetup-&gt;typrelid</code> (or worse,
  26    <code class="literal">typetup-&gt;typelem</code>, because that follows
  27    <code class="structfield">typrelid</code>).  This would result in
  28    random errors or even segmentation violations.
  29   </p><p>
  30    As a partial guard against this type of error, variable-length or
  31    nullable fields should not be made directly visible to the C compiler.
  32    This is accomplished by wrapping them in <code class="literal">#ifdef
  33    CATALOG_VARLEN</code> ... <code class="literal">#endif</code> (where
  34    <code class="literal">CATALOG_VARLEN</code> is a symbol that is never defined).
  35    This prevents C code from carelessly trying to access fields that might
  36    not be there or might be at some other offset.
  37    As an independent guard against creating incorrect rows, we
  38    require all columns that should be non-nullable to be marked so
  39    in <code class="structname">pg_attribute</code>.  The bootstrap code will
  40    automatically mark catalog columns as <code class="literal">NOT NULL</code>
  41    if they are fixed-width and are not preceded by any nullable or
  42    variable-width column.
  43    Where this rule is inadequate, you can force correct marking by using
  44    <code class="literal">BKI_FORCE_NOT_NULL</code>
  45    and <code class="literal">BKI_FORCE_NULL</code> annotations as needed.
  46   </p><p>
  47    Frontend code should not include any <code class="filename">pg_xxx.h</code>
  48    catalog header file, as these files may contain C code that won't compile
  49    outside the backend.  (Typically, that happens because these files also
  50    contain declarations for functions
  51    in <code class="filename">src/backend/catalog/</code> files.)
  52    Instead, frontend code may include the corresponding
  53    generated <code class="filename">pg_xxx_d.h</code> header, which will contain
  54    OID <code class="literal">#define</code>s and any other data that might be of use
  55    on the client side.  If you want macros or other code in a catalog header
  56    to be visible to frontend code, write <code class="literal">#ifdef
  57    EXPOSE_TO_CLIENT_CODE</code> ... <code class="literal">#endif</code> around that
  58    section to instruct <code class="filename">genbki.pl</code> to copy that section
  59    to the <code class="filename">pg_xxx_d.h</code> header.
  60   </p><p>
  61    A few of the catalogs are so fundamental that they can't even be created
  62    by the <acronym class="acronym">BKI</acronym> <code class="literal">create</code> command that's
  63    used for most catalogs, because that command needs to write information
  64    into these catalogs to describe the new catalog.  These are
  65    called <em class="firstterm">bootstrap</em> catalogs, and defining one takes
  66    a lot of extra work: you have to manually prepare appropriate entries for
  67    them in the pre-loaded contents of <code class="structname">pg_class</code>
  68    and <code class="structname">pg_type</code>, and those entries will need to be
  69    updated for subsequent changes to the catalog's structure.
  70    (Bootstrap catalogs also need pre-loaded entries
  71    in <code class="structname">pg_attribute</code>, but
  72    fortunately <code class="filename">genbki.pl</code> handles that chore nowadays.)
  73    Avoid making new catalogs be bootstrap catalogs if at all possible.
  74   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bki.html" title="Chapter 68. System Catalog Declarations and Initial Contents">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bki.html" title="Chapter 68. System Catalog Declarations and Initial Contents">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="system-catalog-initial-data.html" title="68.2. System Catalog Initial Data">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 68. System Catalog Declarations and Initial Contents </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 68.2. System Catalog Initial Data</td></tr></table></div></body></html>