Технический справочник pg_local_cache

pg_local_cache кэширует целые строки по полному первичному ключу в ограниченной общей памяти PostgreSQL. Расширение предоставляет явную SQL-функцию local_cache.mget и необязательную конечную точку RESP2.

Обычный SQL остаётся обычным: расширение не устанавливает хуки планировщика или исполнителя. Обычный SELECT всегда использует PostgreSQL и никогда не читает этот кэш.

Поддерживаемые таблицы и ключи

Исходные таблицы должны быть постоянными heap-таблицами с действующим первичным ключом, без RLS, секционирования, наследования или владения расширением.

Поддерживаемые типы ключей:

• smallint, integer и bigint;
• text, varchar и char с детерминированными сортировками;
• uuid;
• составные первичные ключи, состоящие только из этих типов.

Неподдерживаемые отношения отклоняются во время подключения, а не приводят к небезопасному частичному сопоставлению.

Подключение, сверка и отключение таблиц

local_cache.attach_table(regclass) выполняет одну защищённую последовательность настройки:

1. блокирует и проверяет отношение;
2. записывает его пространство имён, OID отношения и упорядоченные столбцы первичного ключа;
3. устанавливает принадлежащие расширению триггеры уровня оператора, строки и TRUNCATE;
4. перезагружает сопоставления воркеров.

Триггеры событий DDL инвалидируют метаданные сопоставления. После намеренных изменений схемы выполните local_cache.reconcile_table(...) или local_cache.reconcile_all(). local_cache.detach_table(...) удаляет сопоставление и его триггеры.

SQL API mget

Сигнатура:

local_cache.mget(relation regclass, key_values anyarray) RETURNS text[]

Для одноколоночных ключей используется собственный тип массива. Для составных ключей используется прямоугольный text[][]: один ключ на строку и один компонент на столбец первичного ключа.

Контракт:

• не более 1 024 ключей за вызов;
• порядок входных данных и дубликаты сохраняются;
• входной NULL и отсутствующие строки дают выровненные результаты NULL;
• компоненты составного ключа не могут быть NULL;
• каждый компонент разбирается входной функцией своего типа PostgreSQL;
• весь составной пакет проверяется до первого поиска;
• вызывающим сторонам нужен SELECT на исходной таблице;
• функция работает с правами SECURITY INVOKER.

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

Путь чтения и безопасный обход

Каждый запрошенный ключ проходит один и тот же путь:

1. канонизировать полный первичный ключ;
2. использовать общий кэш только в чистой транзакции READ COMMITTED на доступном для записи основном сервере;
3. проверить контрольную сумму полезной нагрузки, дескриптор строки, исходный xmin и видимость снимка;
4. в противном случае выполнить индексированный запрос к исходной таблице через SPI;
5. опубликовать положительную или отрицательную запись только после доказательства по последнему снимку.

REPEATABLE READ, SERIALIZABLE, восстановление, параллельное выполнение и транзакция, записавшая сопоставленные данные, обходят кэш. Строки больше лимита полезной нагрузки кэша всё равно возвращаются PostgreSQL, но не кэшируются.

Согласованность транзакций

До фиксации записи сопоставленной таблицы триггеры ограждают затронутый ключ или отношение. Заполнение кэша несёт поколения сопоставления, глобальное, отношения, ключа и загрузчика, поэтому устаревший загрузчик не сможет опубликовать результат после инвалидации или вытеснения.

Положительные записи сохраняют xmin исходного кортежа и горизонт наблюдения FullXID. Записи, недопустимые для текущего снимка, используют PostgreSQL. Для более старого активного снимка отрицательные записи никогда не считаются авторитетными.

Откат удаляет локальное состояние транзакции, не публикуя новые данные. Поэтому чтение собственных изменений выполняется через PostgreSQL, а не через предполагаемое содержимое кэша.

Общая память и конфигурация

Записи кэша, состояния отношений, счётчики, поколения воркеров и слоты клиентов RESP выделяются при запуске postmaster. Ёмкость ограничена. При вытеснении выбирается ограниченный вращающийся набор и предпочтение отдаётся устаревшим записям; при отказе в допуске новая запись читается из исходной таблицы вместо неограниченного выделения памяти.

Это параметры postmaster. Задайте их до перезапуска; предварительная проверка бинарного установщика проверяет общий план.

Необязательная конечная точка RESP2

RESP2 использует те же сопоставления и общий кэш. Ключи протокола имеют такой вид:

CRUD:database.schema.table:{"pk_column":<json-scalar>,...}

Поддерживаются аутентифицированные ограниченные команды MGET, SET, DEL и инвалидация в заданной области. Воркеры RESP используют одну настроенную роль PostgreSQL; они не наследуют ACL базы данных отдельных сетевых клиентов.

У конечной точки нет TLS. Привязывайте её к loopback или размещайте за аутентифицированным TLS-прокси. Предпочитайте файл токена с ограниченными правами вместо встроенного токена.

Состояние и мониторинг

local_cache.health() сообщает о готовности и согласованности сопоставлений. local_cache.stats() возвращает счётчики в JSON. local_cache.metrics() предоставляет типизированную строку метрик, используемую экспортёром.

Счётчики SQL-кэша описывают только явные вызовы mget:

• sql_cache_hits
• sql_cache_misses
• sql_cache_fills
• sql_cache_bypasses

Счётчики чтений базы данных, инвалидации, отклонения допуска, обхода из-за грязных ключей, singleflight, воркеров и RESP остаются отдельными.

Далее используйте руководство по установке, где описаны проверенные бинарные файлы, сборки исходников через PGXS, контролируемые перезапуски, проверка и безопасное восстановление.