layout: doc lang: en translation_key: INSTALL_EXISTING title: Install pg_local_cache on PostgreSQL 14-18 seo_title: Install pg_local_cache on PostgreSQL 14-18 description: Install a verified Debian or RPM package, use PGXN or PGXS, configure preload, restart PostgreSQL, and initialize, upgrade, or uninstall pg_local_cache. section: Install permalink: /docs/INSTALL_EXISTING.html

last_modified_at: “2026-10-04”

Install pg_local_cache on an existing PostgreSQL server {#install-pg_local_cache-on-an-existing-postgresql-server}

This guide covers Linux with PostgreSQL 14-18. Installation and configuration require a database superuser, and adding the extension to shared_preload_libraries requires one PostgreSQL restart.

1. Requirements {#choose-an-installation-path}

Use the pg_config for the target server when building from source. Plan the restart with the operator or service that owns the PostgreSQL cluster.

2. Install a package {#fast-binary-install}

Download the package and SHA256SUMS for your PostgreSQL major version and architecture from the same GitHub release.

Debian and Ubuntu {#controlled-binary-install}

Download postgresql-<major>-pg-local-cache_<version>-1_<arch>.deb. Packages are built on Debian 12 and require glibc 2.36 or later.

The checksum manifest lists every release asset. Use --ignore-missing when checking only the files you downloaded. Verify the checksum and build provenance, then install:

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

RHEL, Rocky Linux, and AlmaLinux 9

These RPMs require matching PostgreSQL from the PGDG Yum repository. Enable the PGDG repository for your EL version and PostgreSQL major, then install postgresql<major>-server from PGDG before installing the extension. The RPM installs under /usr/pgsql-<major>. Distribution-native PostgreSQL packages use different package names, paths, and service names; use Build from source for those servers.

Download the matching .rpm and SHA256SUMS for your PostgreSQL major version and architecture from the same release. Verify and install it:

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

PGXN

Install the PGXN client, the target PostgreSQL server development headers, a C compiler, and GNU Make. Specify the target server’s pg_config; PGXN otherwise uses the first one on PATH. Its install phase needs root privileges. See the PGXN install options.

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

Build from source {#build-from-source}

Install the target PostgreSQL server development headers, a C compiler, and GNU Make. Build and install with that server’s pg_config:

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

3. Configure postgresql.conf {#configure-before-restart}

Keep existing entries in shared_preload_libraries and add pg_local_cache. Replace app with the database served by the extension.

Configure the RESP listener {#enable-optional-resp2}

Configure the RESP listener with a dedicated worker role, protected token file, and native TLS. The configuration below enables mutual TLS by trusting a client CA. Native RESP TLS requires PostgreSQL built with OpenSSL support.

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

Replace 10.0.0.10 with an address reachable by clients. TLS is off by default; enabling it requires the server certificate and key. This configuration protects a non-loopback RESP listener with TLS, and the CA setting verifies client certificates. For server-authenticated TLS only, leave pg_local_cache.tls_ca_file empty and omit client certificates. RESP TLS is independent of PostgreSQL’s ssl_* settings. Without TLS, a non-loopback listener requires pg_local_cache.allow_plaintext_network = on; use that explicit opt-in only on a trusted network.

The private key must follow PostgreSQL’s server key file rule: mode 0600 when owned by the PostgreSQL OS user, or root-owned with mode 0640 and readable by the server’s group.

Size cache entries, relation states, workers, clients, and memory_budget_mb together. See the technical reference for capacity and memory guidance.

4. Restart PostgreSQL

Use the service or operator that owns the cluster. On systemd:

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

For Patroni, update the cluster configuration and restart through Patroni:

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

For Kubernetes, build a custom PostgreSQL image that includes the matching package, then roll it out through your operator. CloudNativePG extension images are planned.

5. Initialize {#initialize-a-source-installation}

Connect to the configured database as a database superuser. Create the extension and dedicated worker role, then grant access to its metadata:

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;

Keep the worker role separate from application table owners. Attach each permanent table that has a supported primary key:

Attach a table {#attach-a-table}

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

Check readiness and mapping convergence:

Verify health {#verify-cold-fill-and-warm-hit}

SELECT local_cache.health();

6. Upgrade {#recover-a-failed-binary-install}

For a 2.x to 3.0 upgrade, follow the upgrade guide first. In short, migrate applications from SQL mget to RESP MGET, install the new package, restart PostgreSQL through the correct service or operator, verify the loaded library version, then update the extension in every database that has it:

ALTER EXTENSION pg_local_cache UPDATE;

7. Uninstall {#troubleshooting}

Detach every mapped table and drop the extension as a database superuser. Remove pg_local_cache from shared_preload_libraries, restart PostgreSQL, then remove the package with the matching package manager:

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>

Next: see the technical reference for SQL behavior, memory sizing, monitoring, and RESP security.