Установка pg_local_cache на существующий сервер PostgreSQL
Это руководство предназначено для Linux и PostgreSQL 14–18. Для установки и настройки нужны права суперпользователя БД. Добавление расширения в shared_preload_libraries требует одного перезапуска PostgreSQL.
1. Требования
При сборке из исходников используйте pg_config целевого сервера. Запланируйте перезапуск через службу или оператор, управляющий кластером PostgreSQL.
2. Установка пакета
Скачайте пакет и файл SHA256SUMS для нужной версии PostgreSQL и архитектуры из одного релиза GitHub.
Debian и Ubuntu
Скачайте postgresql-<major>-pg-local-cache_<version>-1_<arch>.deb. Пакеты собраны на Debian 12 и требуют glibc версии 2.36 или новее. Манифест содержит все release-файлы; флаг --ignore-missing нужен, если скачаны не все файлы.
Проверьте контрольную сумму и происхождение сборки, затем установите пакет:
sha256sum -c --ignore-missing SHA256SUMS
gh attestation verify <file>.deb --repo profundium/pg_local_cache
sudo apt install ./<file>.deb
RHEL, Rocky Linux и AlmaLinux 9
Эти RPM требуют PostgreSQL той же основной версии из репозитория PGDG.
Подключите репозиторий PGDG
для своей версии EL и нужной основной версии PostgreSQL, затем сначала
установите из PGDG пакет postgresql<major>-server. Пакет расширения
устанавливается в /usr/pgsql-<major>. В дистрибутивных пакетах PostgreSQL
другие имена пакетов, пути и имена служб; для таких серверов используйте
инструкцию по сборке из исходников.
Скачайте подходящий .rpm для версии PostgreSQL и архитектуры. Проверьте и установите его:
sha256sum -c --ignore-missing SHA256SUMS
gh attestation verify <file>.rpm --repo profundium/pg_local_cache
sudo dnf install ./<file>.rpm
PGXN
Установите клиент PGXN, заголовки разработки целевого сервера PostgreSQL,
компилятор C и GNU Make. Укажите pg_config целевого сервера; иначе
PGXN выберет первый найденный в PATH. Для установки системных
файлов нужны права root. См. параметры команды PGXN install.
pgxn install --pg_config /path/to/pg_config --sudo sudo pg_local_cache
Сборка из исходников
Установите заголовки разработки целевой версии PostgreSQL, компилятор C и GNU Make. Соберите и установите расширение с помощью pg_config этой версии:
make PG_CONFIG=/path/to/pg_config && \
sudo make PG_CONFIG=/path/to/pg_config install
3. Настройка postgresql.conf
Сохраните существующие значения shared_preload_libraries и добавьте
pg_local_cache. Замените app на имя базы данных, обслуживаемой расширением.
Настройте RESP listener
Настройте RESP listener с отдельной ролью worker, защищённым файлом токена и встроенным TLS. Эта конфигурация включает mTLS, доверяя CA клиентов. Для встроенного TLS RESP требуется сборка PostgreSQL с поддержкой OpenSSL.
shared_preload_libraries = 'pg_local_cache'
pg_local_cache.database = 'app'
pg_local_cache.role = 'local_cache_worker'
pg_local_cache.port = 6380
pg_local_cache.bind_address = '10.0.0.10'
pg_local_cache.auth_token_file = '/secure/path/token'
pg_local_cache.cache_entries = 16384
pg_local_cache.memory_budget_mb = 384
pg_local_cache.tls = on
pg_local_cache.tls_cert_file = '/secure/path/resp.crt'
pg_local_cache.tls_key_file = '/secure/path/resp.key'
pg_local_cache.tls_ca_file = '/secure/path/client-ca.crt'
pg_local_cache.tls_min_protocol_version = 'TLSv1.2'
pg_local_cache.allow_plaintext_network = off
Замените 10.0.0.10 на адрес, доступный клиентам. По умолчанию TLS выключен;
для включения нужны сертификат и ключ сервера. Эта конфигурация защищает TLS
non-loopback RESP listener и проверяет сертификаты клиентов через заданный CA.
Для TLS только с проверкой сервера оставьте pg_local_cache.tls_ca_file пустым
и не задавайте сертификаты клиента. TLS RESP независим от параметров PostgreSQL
ssl_*. Без TLS listener вне loopback требует
pg_local_cache.allow_plaintext_network = on; используйте это явное разрешение
только в доверенной сети.
Для закрытого ключа действует правило PostgreSQL для файлов ключей
сервера: режим 0600,
если файл принадлежит системному пользователю PostgreSQL, либо владелец root,
режим 0640 и чтение для группы сервера.
Совместно рассчитывайте размер кэша, состояния отношений, число workers и
клиентов, а также memory_budget_mb. Рекомендации по ёмкости и памяти см. в
технической справке.
4. Перезапуск PostgreSQL
Используйте службу или оператор, управляющий кластером. Для systemd:
# Debian and Ubuntu
sudo systemctl restart postgresql@<major>-main
# RHEL, Rocky Linux, and AlmaLinux
sudo systemctl restart postgresql-<major>
В Patroni измените конфигурацию кластера и выполните перезапуск через Patroni:
patronictl edit-config <cluster>
patronictl restart <cluster>
Для Kubernetes создайте собственный образ PostgreSQL с нужным пакетом и разверните его через оператор. Образы расширений для CloudNativePG запланированы.
5. Инициализация
Подключитесь к настроенной базе данных с правами суперпользователя БД. Создайте расширение и отдельную роль worker, затем предоставьте ей доступ к метаданным:
CREATE EXTENSION IF NOT EXISTS pg_local_cache;
CREATE ROLE local_cache_worker LOGIN NOINHERIT NOSUPERUSER
NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
GRANT CONNECT ON DATABASE app TO local_cache_worker;
GRANT USAGE ON SCHEMA local_cache TO local_cache_worker;
GRANT SELECT ON TABLE local_cache.mapping TO local_cache_worker;
Не используйте роль worker для владельцев таблиц приложения. Подключите каждую постоянную таблицу с поддерживаемым первичным ключом:
Подключение таблицы
SELECT local_cache.attach_table('public.items'::regclass);
Проверка состояния
SELECT local_cache.health();
Проверьте готовность расширения и актуальность связей.
6. Обновление
Следуйте руководству по обновлению при переходе с 3.0.0 на 3.1.0. Для 2.x используйте описанную там последовательную миграцию через 3.0.0 и затем на 3.1.0.
Замените в приложениях SQL mget на RESP MGET, установите пакет
3.1.0 для нужной версии PostgreSQL, перезапустите PostgreSQL и обновите
расширение в каждой базе данных, где оно установлено:
ALTER EXTENSION pg_local_cache UPDATE;
7. Удаление
Отсоедините все связанные таблицы и удалите расширение от имени суперпользователя БД. Удалите pg_local_cache из shared_preload_libraries, перезапустите PostgreSQL и удалите пакет подходящим менеджером:
SELECT local_cache.detach_table('public.items'::regclass);
DROP EXTENSION pg_local_cache;
sudo apt remove postgresql-<major>-pg-local-cache
sudo dnf remove pg_local_cache_<major>
Далее: см. техническую справку об SQL, размере памяти, мониторинге и безопасности RESP.
Документация для 2.x: https://github.com/profundium/pg_local_cache/tree/v2.0.4/docs
Обновлено .