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

   1
   2 68.1. System Catalog Declaration Rules #
   3
   4    The key part of a catalog header file is a C structure definition
   5    describing the layout of each row of the catalog. This begins with a
   6    CATALOG macro, which so far as the C compiler is concerned is just
   7    shorthand for typedef struct FormData_catalogname. Each field in the
   8    struct gives rise to a catalog column. Fields can be annotated using
   9    the BKI property macros described in genbki.h, for example to define a
  10    default value for a field or mark it as nullable or not nullable. The
  11    CATALOG line can also be annotated, with some other BKI property macros
  12    described in genbki.h, to define other properties of the catalog as a
  13    whole, such as whether it is a shared relation.
  14
  15    The system catalog cache code (and most catalog-munging code in
  16    general) assumes that the fixed-length portions of all system catalog
  17    tuples are in fact present, because it maps this C struct declaration
  18    onto them. Thus, all variable-length fields and nullable fields must be
  19    placed at the end, and they cannot be accessed as struct fields. For
  20    example, if you tried to set pg_type.typrelid to be NULL, it would fail
  21    when some piece of code tried to reference typetup->typrelid (or worse,
  22    typetup->typelem, because that follows typrelid). This would result in
  23    random errors or even segmentation violations.
  24
  25    As a partial guard against this type of error, variable-length or
  26    nullable fields should not be made directly visible to the C compiler.
  27    This is accomplished by wrapping them in #ifdef CATALOG_VARLEN ...
  28    #endif (where CATALOG_VARLEN is a symbol that is never defined). This
  29    prevents C code from carelessly trying to access fields that might not
  30    be there or might be at some other offset. As an independent guard
  31    against creating incorrect rows, we require all columns that should be
  32    non-nullable to be marked so in pg_attribute. The bootstrap code will
  33    automatically mark catalog columns as NOT NULL if they are fixed-width
  34    and are not preceded by any nullable or variable-width column. Where
  35    this rule is inadequate, you can force correct marking by using
  36    BKI_FORCE_NOT_NULL and BKI_FORCE_NULL annotations as needed.
  37
  38    Frontend code should not include any pg_xxx.h catalog header file, as
  39    these files may contain C code that won't compile outside the backend.
  40    (Typically, that happens because these files also contain declarations
  41    for functions in src/backend/catalog/ files.) Instead, frontend code
  42    may include the corresponding generated pg_xxx_d.h header, which will
  43    contain OID #defines and any other data that might be of use on the
  44    client side. If you want macros or other code in a catalog header to be
  45    visible to frontend code, write #ifdef EXPOSE_TO_CLIENT_CODE ... #endif
  46    around that section to instruct genbki.pl to copy that section to the
  47    pg_xxx_d.h header.
  48
  49    A few of the catalogs are so fundamental that they can't even be
  50    created by the BKI create command that's used for most catalogs,
  51    because that command needs to write information into these catalogs to
  52    describe the new catalog. These are called bootstrap catalogs, and
  53    defining one takes a lot of extra work: you have to manually prepare
  54    appropriate entries for them in the pre-loaded contents of pg_class and
  55    pg_type, and those entries will need to be updated for subsequent
  56    changes to the catalog's structure. (Bootstrap catalogs also need
  57    pre-loaded entries in pg_attribute, but fortunately genbki.pl handles
  58    that chore nowadays.) Avoid making new catalogs be bootstrap catalogs
  59    if at all possible.