Каждый файл .dat содержит описания структур данных Perl, в результате вычисления которых (функцией eval) в памяти формируется структура данных, состоящая из массива хеш-ссылок, соответствующих каждой строке каталога. Немного модифицированная выдержка из pg_database.dat иллюстрирует основные моменты:

[

# A comment could appear here.
{ oid => '1', oid_symbol => 'Template1DbOid',
  descr => 'database\'s default template',
  datname => 'template1', encoding => 'ENCODING',
  datlocprovider => 'LOCALE_PROVIDER', datistemplate => 't',
  datallowconn => 't', datconnlimit => '-1', datfrozenxid => '0',
  datminmxid => '1', dattablespace => 'pg_default', datcollate => 'LC_COLLATE',
  datctype => 'LC_CTYPE', daticulocale => 'ICU_LOCALE', datacl => '_null_' },

]

Замечания:

Строке каталога, фигурирующей в исходных данных, можно вручную присвоить OID, добавив поле метаданных oid => nnnn. Более того, когда строке присваивается OID, для этого OID можно создать макрос C, добавив поле метаданных oid_symbol => имя.

Предварительно загружаемым строкам каталога должны заранее назначаться OID, если на них по OID ссылаются другие предварительно загружаемые строки. Назначать OID также требуется, если на OID нужно будет ссылаться из кода на C. В отсутствие этих условий поле метаданных oid можно опустить, и тогда загрузочный код назначит OID автоматически. На практике мы обычно явно назначаем OID для всех строк в определённом каталоге (даже если фактически присутствуют ссылки только на часть из них) либо не назначаем их вовсе.

Указание фактического числового значения любого OID в коде на C считается крайне нежелательным; вместо этого всегда следует использовать макрос. Прямые обращения к OID в pg_proc требуются достаточно часто, поэтому был создан специальный механизм, создающий необходимые макросы автоматически; см. src/backend/utils/Gen_fmgrtab.pl. С аналогичной целью предусмотрен (но по историческим причинам реализован по-другому) метод создания макросов для OID в pg_type. Как следствие, записи oid_symbol в этих двух каталогах добавлять не нужно. Подобным образом в pg_class автоматически включаются макросы для OID системных каталогов и индексов. Для остальных системных каталогов все нужные вам макросы с oid_symbol вы должны добавлять вручную.

Чтобы найти свободный OID для новой предварительно загружаемой строки, запустите скрипт src/include/catalog/unused_oids. Он выводит диапазоны неиспользуемых OID, включающие граничные значения (например, выведенная строка 45-900 означает, что OID с 45 по 900 включительно ещё не задействованы). В настоящее время для назначения вручную зарезервированы значения OID 1–9999; скрипт unused_oids просто просматривает заголовки каталогов и файлы .dat и проверяет, какие значения в них отсутствуют. Для поиска ошибок вы можете воспользоваться скриптом duplicate_oids. (Скрипт genbki.pl назначит OID всем строкам, которым он не был назначен вручную, и также выявит дублирующиеся OID во время компиляции.)

Выбирая значения OID для разрабатываемой модификации кода, которая скорее всего не будет принята сразу, рекомендуется использовать группу более-менее последовательных OID, начиная с некоторого случайного числа в диапазоне 8000—9999. Это уменьшит риск конфликтов OID с другими параллельными разработками. Чтобы сохранить диапазон 8000—9999 для использования в процессе разработки после того, как модификация кода вносится в основной репозиторий git, привнесённые с ней новые значения OID должны быть перенумерованы и заменены свободными номерами ниже этого диапазона. Обычно это будет происходить в конце каждого цикла разработки; таким образом, разом перенумеруются все OID, появившиеся в коде в течение завершающегося цикла. Для этого может применяться скрипт renumber_oids.pl. Этот скрипт также может быть полезен, если окажется, что некоторая ещё разрабатываемая модификация конфликтует с недавно внесёнными изменениями.

Из этого положения о возможной перенумерации значений OID, вносимых модификациями, следует, что выбранные в них изначально значения OID не должны считаться стабильными, пока эта модификация не будет включена в официальный выпуск. После выпуска мы не будем менять вручную назначенные OID объектов, так как это может повлечь самые разные проблемы совместимости.

Если скрипту genbki.pl требуется назначить OID элементу каталога, для которого OID не назначен вручную, он выбирает значение в диапазоне 10000—11999. Счётчик OID сервера получает значение 10000 на стадии начальной инициализации. Поэтому все объекты, создаваемые в ходе начальной инициализации, также получают OID в данном диапазоне. (Обычный механизм назначения OID позаботится о предотвращении конфликтов).

Объекты с OID ниже FirstUnpinnedObjectId (12000) считаются «закреплёнными», то есть они не могут быть удалены. (Существует небольшое количество исключений, жёстко заданных в IsPinnedObject().) Когда initdb доходит до фазы создания незакреплённых объектов, значение счётчика OID увеличивается до FirstUnpinnedObjectId. Таким образом, объекты, созданные на более поздних этапах initdb, например объекты, созданные при выполнении сценария information_schema.sql, не будут закреплёнными, а все объекты, известные genbki.pl, будут.

В процессе обычной работы сервер назначает OID от 16384 и выше. Тем самым гарантируется, что диапазон 10000—16383 свободен для значений OID, назначаемых автоматически скриптом genbki.pl или во время работы initdb. Эти автоматически назначаемые OID не считаются стабильными и могут меняться от одного кластера к другому.

Вообще говоря, из одной строки исходного каталога можно сослаться на другую, просто указав предопределённый OID целевой строки в поле ссылки. Однако политика проекта не приветствует такой подход, так как он провоцирует ошибки, а подобные ссылки сложны для восприятия и могут нарушиться при перенумерации OID. Поэтому в genbki.pl реализованы механизмы записи символических ссылок, работающие по следующим правилам:

Скрипт genbki.pl разрешает все символические ссылки при запуске и помещает в формируемый файл BKI обычные числовые OID. Таким образом, при начальной загрузке отпадает необходимость в разрешении имён.

Желательно добавить в определение столбцов с OID макрос BKI_LOOKUP или BKI_LOOKUP_OPT, даже если в каталоге нет исходных данных, требующих поиска для распознавания. Благодаря этому, genbki.pl сохранит существующую в системных каталогах связь по внешнему ключу. Эта информация используется в регрессионных тестах для выявления некорректных записей. Также обратите внимание на макросы DECLARE_FOREIGN_KEY, DECLARE_FOREIGN_KEY_OPT, DECLARE_ARRAY_FOREIGN_KEY и DECLARE_ARRAY_FOREIGN_KEY_OPT, позволяющие обозначить связи по внешним ключам, которые слишком сложны для BKI_LOOKUP (обычно внешние ключи со связями по нескольким столбцам).

Для большинства скалярных типов данных должны создаваться соответствующие типы массивов (то есть стандартный тип массива переменной длины с элементами скалярного типа, ссылка на который содержится в поле typarray скалярного типа pg_type). Как правило, скрипт genbki.pl может создать запись в pg_type для типа массива автоматически.

Для использования этой возможности достаточно записать array_type_oid => nnnn в поле метаданных записи pg_type для скалярного типа, указав OID, который будет использоваться для типа массива. После этого поле typarray можно не задавать, так как этот OID окажется в нём автоматически.

В качестве имени сгенерированного типа массива выбирается имя скалярного типа с добавленным спереди подчёркиванием. Другие поля в записи массива заполняются из определений BKI_ARRAY_DEFAULT(значение) в pg_type.h или, если соответствующего определения нет, копируются из скалярного типа. (Поле typalign заполняется особым образом.) Затем в полях typelem и typarray двух записей устанавливаются перекрёстные ссылки друг на друга.

Ниже приведены некоторые предложения по оптимальному решению некоторых распространённых задач при изменении файлов каталогов.

Добавление в каталог нового столбца со значением по умолчанию: Добавьте столбец в заголовочный файл с указанием BKI_DEFAULT(значение). Файл данных потребуется редактировать, только если в каких-либо существующих строках в добавленном поле должно быть не значение по умолчанию.

Указание значения по умолчанию для существующего столбца, который его не имел: Добавьте указание BKI_DEFAULT в заголовочный файл, а затем выполните make reformat-dat-files для удаления ставших избыточными записей поля.

Удаление столбца, со значением по умолчанию или без: Удалите столбец из заголовочного файла, а затем выполните make reformat-dat-files для удаления ставших избыточными записей поля.

Изменение или удаление существующего значения по умолчанию: Просто изменить заголовочный файл недостаточно, так как при этом текущие данные будут интерпретироваться некорректно. Сначала выполните make expand-dat-files, чтобы перезаписать в файлах данных все явно заданные значения по умолчанию, затем удалите или измените указания BKI_DEFAULT, и в завершение выполните make reformat-dat-files для повторного удаления избыточных полей.

Разовая массовая модификация: Скрипт reformat_dat_file.pl можно скорректировать для выполнения самых разных массовых модификаций. Просмотрев в нём блочные комментарии, вы найдёте место, куда можно вставить модифицирующий код. В следующем примере мы произведём объединение двух логических полей в pg_proc в символьном поле:

Примеры кода, производящего массовые модификации, вы можете найти в скриптах convert_oid2name.pl и remove_pg_type_oid_symbols.pl, вложенных в сообщение: https://www.postgresql.org/message-id/CAJVSVGVX8gXnPm+Xa=DxR7kFYprcQ1tNcCT5D0O3ShfnM6jehA@mail.gmail.com