pg_local_cache
Français

Installer pg_local_cache sur un serveur PostgreSQL existant

Ce guide concerne Linux et PostgreSQL 14–18. L’installation et la configuration nécessitent les droits de superutilisateur de la base de données. Ajouter l’extension à shared_preload_libraries nécessite un redémarrage de PostgreSQL.

1. Prérequis

Pour compiler depuis les sources, utilisez le pg_config du serveur cible. Planifiez le redémarrage avec le service ou l’opérateur qui gère le cluster PostgreSQL.

2. Installer un paquet

Téléchargez le paquet et SHA256SUMS correspondant à la version majeure de PostgreSQL et à l’architecture depuis la même publication GitHub.

Debian et Ubuntu

Téléchargez postgresql-<major>-pg-local-cache_<version>-1_<arch>.deb. Les paquets sont construits sur Debian 12 et nécessitent glibc 2.36 ou ultérieure. Le manifeste contient tous les fichiers de la publication ; utilisez --ignore-missing si vous n’en téléchargez que certains.

Vérifiez la somme de contrôle et la provenance de la compilation, puis installez le paquet :

sha256sum -c --ignore-missing SHA256SUMS
gh attestation verify <file>.deb --repo profundium/pg_local_cache
sudo apt install ./<file>.deb

RHEL, Rocky Linux et AlmaLinux 9

Ces RPM nécessitent PostgreSQL de PGDG dans la même version majeure. Configurez le dépôt Yum PGDG pour votre version d’EL et la version majeure de PostgreSQL, puis installez postgresql<major>-server depuis PGDG avant l’extension. Le paquet de l’extension s’installe sous /usr/pgsql-<major>. Les paquets PostgreSQL fournis par la distribution utilisent d’autres noms de paquets, chemins et noms de services ; pour ces serveurs, suivez les instructions de compilation depuis les sources.

Téléchargez le .rpm correspondant à la version majeure de PostgreSQL et à l’architecture. Vérifiez-le puis installez-le :

sha256sum -c --ignore-missing SHA256SUMS
gh attestation verify <file>.rpm --repo profundium/pg_local_cache
sudo dnf install ./<file>.rpm

PGXN

Installez le client PGXN, les en-têtes de développement du serveur PostgreSQL cible, un compilateur C et GNU Make. Indiquez le pg_config du serveur cible ; sinon PGXN utilise le premier trouvé dans PATH. L’installation des fichiers système nécessite les droits root. Consultez les options de la commande PGXN install.

pgxn install --pg_config /path/to/pg_config --sudo sudo pg_local_cache

Compiler depuis les sources

Installez les en-têtes de développement de la version cible de PostgreSQL, un compilateur C et GNU Make. Compilez puis installez l’extension avec le pg_config de cette version :

make PG_CONFIG=/path/to/pg_config && \
  sudo make PG_CONFIG=/path/to/pg_config install

3. Configurer postgresql.conf

Conservez les entrées existantes de shared_preload_libraries et ajoutez pg_local_cache. Remplacez app par le nom de la base servie par l’extension.

Configurer le listener RESP

Configurez le listener RESP avec un rôle worker dédié, un fichier de jeton protégé et TLS natif. La configuration ci-dessous active mTLS en approuvant une CA cliente. TLS natif pour RESP nécessite PostgreSQL compilé avec le support 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

Remplacez 10.0.0.10 par une adresse accessible aux clients. TLS est désactivé par défaut ; son activation exige le certificat et la clé serveur. Cette configuration protège par TLS un listener RESP hors loopback et vérifie les certificats clients via la CA. Pour un TLS avec authentification du serveur uniquement, laissez pg_local_cache.tls_ca_file vide et omettez les certificats clients. TLS RESP est indépendant des paramètres ssl_* de PostgreSQL. Sans TLS, un listener hors loopback exige pg_local_cache.allow_plaintext_network = on ; limitez cet opt-in explicite à un réseau de confiance.

La clé privée doit suivre la règle PostgreSQL sur les fichiers de clé serveur : mode 0600 si elle appartient à l’utilisateur système de PostgreSQL, ou propriété de root avec le mode 0640 et un accès en lecture pour le groupe du serveur.

Dimensionnez ensemble les entrées de cache, les états de relation, les workers, les clients et memory_budget_mb. Consultez les conseils de capacité et de mémoire dans la référence technique.

4. Redémarrer PostgreSQL

Utilisez le service ou l’opérateur qui gère le cluster. Avec systemd :

# Debian and Ubuntu
sudo systemctl restart postgresql@<major>-main
# RHEL, Rocky Linux, and AlmaLinux
sudo systemctl restart postgresql-<major>

Avec Patroni, modifiez la configuration du cluster puis redémarrez-le avec Patroni :

patronictl edit-config <cluster>
patronictl restart <cluster>

Pour Kubernetes, créez une image PostgreSQL personnalisée contenant le paquet correspondant, puis déployez-la via votre opérateur. Les images d’extension CloudNativePG sont prévues.

5. Initialiser

Connectez-vous à la base configurée en tant que superutilisateur de base de données. Créez l’extension et un rôle worker dédié, puis accordez-lui l’accès aux métadonnées :

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;

Séparez le rôle worker des rôles propriétaires des tables applicatives. Attachez chaque table permanente dotée d’une clé primaire prise en charge :

Attacher une table

SELECT local_cache.attach_table('public.items'::regclass);

Vérifier l’état

SELECT local_cache.health();

Vérifiez que l’extension est prête et que les associations sont à jour.

6. Mettre à niveau

Pour passer de 3.0.0 à 3.1.0, suivez le guide de mise à niveau. Depuis 2.x, suivez d’abord le parcours indiqué dans le guide via 3.0.0 jusqu’à 3.1.0. Migrez les applications de SQL mget vers RESP MGET, installez le paquet 3.1.0 correspondant, redémarrez PostgreSQL et mettez à niveau l’extension dans chaque base où elle est installée :

ALTER EXTENSION pg_local_cache UPDATE;

7. Désinstaller

Détachez toutes les tables associées et supprimez l’extension en tant que superutilisateur de la base. Retirez pg_local_cache de shared_preload_libraries, redémarrez PostgreSQL puis supprimez le paquet avec le gestionnaire approprié :

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>

À suivre : consultez la référence technique pour SQL, le dimensionnement mémoire, la supervision et la sécurité RESP.

Documentation pour 2.x : https://github.com/profundium/pg_local_cache/tree/v2.0.4/docs

Mis à jour .