Как написать свое расширение postgres?

Приветствую, хабровчане! Сегодня я научу вас делать расширения для postgres на живом примере. Создадим расширения pg_plan_alternatives, которое будет логировать все пути, которые планировщик перебирает в поисках лучшего плана запроса

Для написания расширения нам потребуется выполнить следующее:

• Склонировать репозиторий postgres из официального репозитория (для тестирования расширения):

git clone git@github.com:postgres/postgres.git

• Перейти в директорию postgres:

cd postgres

• Создать директорию нашего расширения:

mkdir contrib/pg_plan_alternatives

• Создать необходимые файлы:

  • pg_plan_alternatives--1.0.sql — скрипт миграции, который Postgres выполняет при CREATE EXTENSION. Имя файла строго в формате <имя>--<версия>.sql: по нему Postgres находит, какой скрипт запускать. Сюда выносят объекты, видимые из SQL (функции, представления, GUC-обёртки). Нашему расширению таких объектов не нужно — вся логика живёт в C-хуке, поэтому файл содержит только защитную строку:

  -- Запрещаем запускать скрипт напрямую через psql (\i ...).-- Корректный способ загрузки — команда CREATE EXTENSION,-- которая выставляет нужное окружение перед выполнением файла.\echo Use "CREATE EXTENSION pg_plan_alternatives" to load this file. \quit
  

  • pg_plan_alternatives.control — манифест расширения. Postgres читает его, чтобы понять, какую версию ставить и где искать скомпилированную библиотеку. Без него CREATE EXTENSION не найдёт расширение.

    comment = 'pg_plan_alternatives'              # описание, видно в \dx и pg_available_extensionsdefault_version = '1.0'                       # версия по умолчанию; ищется файл --1.0.sqlmodule_pathname = '$libdir/pg_plan_alternatives'  # путь к .so; $libdir подставит Postgresrelocatable = true                            # расширение можно перенести в другую схему
    

  • Makefile — сборка по правилам PGXS (инфраструктура сборки расширений Postgres). Описывает, что компилировать и какие файлы установить, после чего достаточно make && make install:

    MODULES = pg_plan_alternatives pg_plan_alternatives.soEXTENSION = pg_plan_alternativesDATA = pg_plan_alternatives--1.0.sqlPG_CONFIG = pg_configPGXS := $(shell $(PG_CONFIG) --pgxs)include $(PGXS)
    

  • Наконец, создать сам файл расширения. Писать будем на си, как и ядро postgres и создадим первоначальную структуру файла pg_plan_alternatives.c:

    ```#include "postgres.h" /* базовые типы и макросы ядра; включается первым в любом .c */#include "fmgr.h"/* Обязательный маркер. Postgres проверяет его при загрузке .so и/* отказывается грузить библиотеку, собранную под другую версию сервера. */PG_MODULE_MAGIC;/* Прототипы хуков жизненного цикла модуля. */void _PG_init(void);void _PG_fini(void);/* Вызывается один раз при загрузке библиотеки (LOAD или shared_preload_libraries)./* Здесь будем регистрировать свой хук планировщика. */void_PG_init(void){}/* Вызывается при выгрузке библиотеки — сюда выносят освобождение ресурсов/* и восстановление перехваченных хуков. */void_PG_fini(void){}    ```
    

• Дальше мы не сможем продолжить без патча ядра postgres — простейший вариант для тестового расширения (если только не использовать eBPF, но это уже другая история). Каждый путь планировщик регистрирует через функцию add_path из postgres/src/backend/optimizer/util/pathnode.(h/c). В ядре нет готовой точки расширения для неё, поэтому добавим её сами — глобальный указатель на функцию (hook), который расширение сможет перехватить.

  В заголовке объявляем тип хука и сам указатель. extern означает «переменная определена в другом файле» (в .c), PGDLLIMPORT нужен, чтобы символ был виден из подгружаемых библиотек на Windows:

  // pathnode.h/* Сигнатура повторяет аргументы add_path: узел отношения и добавляемый путь. */typedef void (*add_path_hook_type) (RelOptInfo *parent_rel, Path *new_path);extern PGDLLIMPORT add_path_hook_type add_path_hook;
  

• В .c создаём саму переменную (по умолчанию NULL — хук не установлен) и вызываем её в начале add_path. Важно делать это именно в начале: дальше по коду add_path может отбросить и освободить new_path, и тогда мы бы читали уже освобождённую память:

  // pathnode.c/* Определение указателя. NULL, пока какое-нибудь расширение его не перехватит. */add_path_hook_type add_path_hook = NULL;voidadd_path(RelOptInfo *parent_rel, Path *new_path){/* Точка расширения: если хук установлен — отдаём ему путь. */if (add_path_hook)  add_path_hook(parent_rel, new_path);// ... дальше идёт оригинальный код add_path
  

После правки ядро нужно пересобрать и переустановить, если оно было собрано ранее (make && make install в корне дерева postgres), иначе новый символ не появится.

Что тут происходит? В .h мы объявили тип хука и extern-указатель, в .c — его определение и вызов. Пока указатель NULL, поведение ядра не меняется. Теперь в расширении мы присваиваем ему свою функцию: на каждый рассматриваемый путь будем писать строку в лог.

// pg_plan_alternatives.c#include "optimizer/pathnode.h"#include "miscadmin.h"/* Сохраняем то, что лежало в хуке до нас: расширений может быть несколько, *//* и цепочку хуков нельзя разрывать. */static add_path_hook_type prev_add_path_hook = NULL;static voidpg_plan_alternatives_add_path_hook(RelOptInfo *parent_rel, Path *new_path){  /* Сначала отдаём управление предыдущему хуку в цепочке. */  if (prev_add_path_hook)    prev_add_path_hook(parent_rel, new_path);  /* Логируем сам путь: тип узла и оценки планировщика. */  /* MyProcPid — PID backend-процесса, удобно различать параллельные сессии. */  elog(LOG,       "[PID %d] ADD_PATH: %d (startup=%.2f, total=%.2f, rows=%.0f)",       MyProcPid,       new_path->pathtype,       new_path->startup_cost,       new_path->total_cost,       new_path->rows);}void_PG_init(void){  /* Встраиваемся в цепочку: запоминаем старый хук и ставим свой. */  prev_add_path_hook = add_path_hook;  add_path_hook = pg_plan_alternatives_add_path_hook;}void_PG_fini(void){  /* Возвращаем хук в исходное состояние. */  /* На практике PostgreSQL не выгружает загруженные модули, поэтому  /* _PG_fini почти никогда не вызывается, но восстановление хука —*/  /* правильный тон и страховка. */  add_path_hook = prev_add_path_hook;}

• Проверяем расширение:

  1. Собираем и устанавливаем пропатченное ядро (из корня дерева postgres). Перед первой сборкой дерево нужно сконфигурировать — иначе make выдаст ошибку You need to run the 'configure' program first:

     ./configure --prefix=$HOME/pgsql --enable-debug --enable-cassertmake && make install
     

     --prefix — каталог установки (отдельный от системного PostgreSQL), --enable-debug --enable-cassert удобны при разработке (символы для отладчика и внутренние проверки ядра). configure запускается один раз; после правок ядра достаточно make && make install.

  2. Собираем и устанавливаем само расширение (из contrib/pg_plan_alternatives). Указываем PG_CONFIG явно — иначе make возьмёт pg_config из PATH (часто это системный PostgreSQL), и .so установится в чужой $libdir; запускаемый сервер её не найдёт и упадёт с ошибкой could not access file "pg_plan_alternatives":

     cd <path_to_postgres>/contrib/pg_plan_alternativesPGC=$HOME/pgsql/bin/pg_configmake PG_CONFIG=$PGC cleanmake PG_CONFIG=$PGCmake PG_CONFIG=$PGC install
     

  3. make install ставит только бинарники в --prefix; кластер данных (а вместе с ним и postgresql.conf) создаётся отдельно командой initdb. Создаём кластер и запускаем сервер:

     export PATH=$HOME/pgsql/bin:$PATHinitdb -D $HOME/pgdata -U postgres --auth=trustpg_ctl -D $HOME/pgdata -l $HOME/pgdata/server.log start
     

     postgresql.conf после этого лежит в каталоге данных — $HOME/pgdata/postgresql.conf (это путь из -D, он же PGDATA; у работающего сервера его покажет SHOW config_file;).

  4. Расширение не объявляет SQL-функций, поэтому CREATE EXTENSION сам по себе библиотеку не подгрузит. Хук ставится в PGinit, который должен отработать до планирования запроса, — значит модуль нужно загрузить заранее через shared_preload_libraries в postgresql.conf:

  shared_preload_libraries = 'pg_plan_alternatives'
  

  shared_preload_libraries читается только при старте сервера, поэтому делать это нужно до работы в psql и обязательно перезапустить PostgreSQL:

  pg_ctl -D $HOME/pgdata -l $HOME/pgdata/server.log restart
  

• Теперь заходим в psql:

  psql -U postgres -d postgres
  

• Создаём простую таблицу с данными (на пустой таблице планировщик рассмотрит один путь — не на что смотреть), регистрируем расширение и выполняем SELECT:

  -- простая таблица с даннымиCREATE TABLE t (id int, val text);INSERT INTO t SELECT g, 'row' || g FROM generate_series(1, 1000) g;-- регистрируем расширениеCREATE EXTENSION pg_plan_alternatives;SELECT * FROM t WHERE id = 42;
  

• Смотрим лог-файл сервера ($HOME/pgdata/server.log) — на каждый рассмотренный планировщиком путь будет строка от нашего хука:

  [53454] LOG: [PID 53454] ADD_PATH: 357 (startup=0.00, total=33.91, rows=1)[53454] STATEMENT: SELECT * FROM t WHERE id = 42;[53454] LOG: [PID 53454] ADD_PATH: 357 (startup=0.00, total=33.91, rows=1)[53454] STATEMENT: SELECT * FROM t WHERE id = 42;
  

  Если строк нет — проверьте, что библиотека действительно загружена (SHOW shared_preload_libraries;)

На этом у меня всё, делитесь своим опытом и задавайте вопросы, с удовольствием отвечу!

Полезные ссылки:

• Документация PostgreSQL: Extending SQL — общий раздел о расширении возможностей PostgreSQL.

• Документация PostgreSQL: Packaging Related Objects into an Extension — про .control, скрипты версий и упаковку расширения.

• Документация PostgreSQL: Extension Building Infrastructure (PGXS) — сборка расширений через Makefile/PGXS.

• Илья Евдокимов — «Как писать расширения для PostgreSQL» (PG Bootcamp 2023) — доклад с разбором на практике.