pg_local_cache
Deutsch

pg_local_cache auf einem bestehenden PostgreSQL-Server installieren

Installieren Sie die Erweiterung mit einem verifizierten Linux-Paket oder bauen Sie sie mit PostgreSQLs PGXS-Toolchain. Beide Wege erfordern vor CREATE EXTENSION einen kontrollierten PostgreSQL-Neustart.

Wartungsfenster einplanen: Die erste Aktivierung ändert shared_preload_libraries. Bewahren Sie vorhandene Einträge und starten Sie den richtigen Cluster erst neu, wenn die Vorprüfungen erfolgreich sind.

Installationsweg wählen

Weg Geeignet für Zuständig für Neustart
Neueste verifizierte Binärdatei Lokaler Linux-amd64-Cluster pg_ctl-Bootstrap
Feste verifizierte Binärdatei Produktion und verwaltete Abläufe systemd, pg_ctl oder externer Operator
PGXS-Quellcode-Build Nicht unterstützte Plattform oder benutzerdefinierte PostgreSQL-Installation Ihr normaler Betriebsablauf

Veröffentlichte Binärdateien unterstützen PostgreSQL 14–18 unter Linux amd64 mit glibc oder musl. Die Beispiele mit fester Version verwenden pg_local_cache 2.0.1.

Schnelle Binärinstallation

Für einen lokalen, durch pg_ctl kontrollierten Cluster:

curl -fsSL https://github.com/profundium/pg_local_cache/releases/latest/download/install-latest.sh | bash -s -- app

Ersetzen Sie app durch den Datenbanknamen. Dadurch wird der reine SQL-Modus mit pg_local_cache.port = 0 aktiviert.

Der Bootstrap löst einen Release-Tag auf, verifiziert fetch-release.sh gegen die SHA256SUMS dieses Releases, wählt das passende PostgreSQL- und libc-Archiv, verifiziert es, installiert es, startet neu, erstellt die Erweiterung und führt local_cache.health() aus.

Wenn curl | bash außerhalb Ihrer Richtlinie liegt, prüfen Sie das Skript zuerst:

curl -fsSLO https://github.com/profundium/pg_local_cache/releases/latest/download/install-latest.sh
less install-latest.sh
bash install-latest.sh app

Kontrollierte Binärinstallation

Laden Sie ein festes Release mit seinem veröffentlichten Helfer herunter:

curl -fsSLO https://github.com/profundium/pg_local_cache/releases/download/v2.0.1/fetch-release.sh
bash fetch-release.sh --release-tag v2.0.1 --output-directory ./pg_local_cache-package

Führen Sie die Vorprüfung aus und wählen Sie den Zuständigen für den Neustart explizit:

sudo ./pg_local_cache-package/install.sh preflight --database app
sudo ./pg_local_cache-package/install.sh install \
  --database app \
  --restart-method systemd \
  --systemd-unit postgresql@16-main

Unterstützte Neustartmethoden sind systemd, pg_ctl und none. Verwenden Sie none mit Patroni, einem Kubernetes-Operator oder einer anderen externen Steuerung. Starten Sie über diese Steuerung neu und prüfen Sie anschließend:

sudo ./pg_local_cache-package/install.sh verify --database app

Das Installationsprogramm gibt ein Zustandsverzeichnis aus. Bewahren Sie es auf, bis die Prüfung erfolgreich ist; es enthält das für recover erforderliche Online-Backup.

Aus dem Quellcode bauen

Verwenden Sie dasselbe pg_config wie der Ziel-PostgreSQL-Server. Installieren Sie zuerst dessen Server-Entwicklungsheader, einen C-Compiler und GNU Make.

git clone --branch v2.0.1 --depth 1 https://github.com/profundium/pg_local_cache.git
cd pg_local_cache
make PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config
sudo make install PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config

Bauen Sie aus einem sauberen Checkout, damit die Binärdatei ihren Git-Commit aufzeichnet. Die Quellinstallation kopiert nur Erweiterungsdateien. Fahren Sie unten mit Preload-Konfiguration, Neustart und SQL-Initialisierung fort.

Vor dem Neustart konfigurieren

Minimale SQL-only-Konfiguration mit Standardkapazität und Speicherbudget:

shared_preload_libraries = 'pg_local_cache'
pg_local_cache.database = 'app'
pg_local_cache.role = 'local_cache_worker'
pg_local_cache.cache_entries = 16384
pg_local_cache.memory_budget_mb = 384
pg_local_cache.port = 0

Behalten Sie vorhandene Einträge in shared_preload_libraries bei. Ersetzen Sie hier und in den folgenden SQL-Grants app durch den tatsächlichen Datenbanknamen. Das Speicherbudget gilt für die Erweiterung, nicht für den gesamten PostgreSQL-Server.

Dimensionieren Sie cache_entries, Relationszustände, Clients, Worker und memory_budget_mb gemeinsam. Die Vorprüfung des Binärinstallers weist widersprüchliche Pläne zurück. Bei Quellcode-Builds ist dieselbe Kapazitätsprüfung vor dem Neustart erforderlich; erhöhen Sie die Zahl der Einträge nicht, ohne das Speicherbudget zu überprüfen.

Eine Quellinstallation initialisieren

Verbinden Sie sich nach dem Neustart als Datenbank-Superuser mit der konfigurierten Datenbank. Führen Sie bei einer ersten manuellen Installation Folgendes aus:

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;

Der Binärinstaller erstellt diese Rolle und ihre Metadaten-Grants; überspringen Sie diesen Block, wenn diese Einrichtung bereits erfolgt ist. Verwenden Sie bei einem eigenen pg_local_cache.role diesen Namen konsequent. Verwenden Sie keine Rolle wieder, der Anwendungstabellen gehören.

Die Rolle ist auch bei pg_local_cache.port = 0 erforderlich. Das Anhängen von Tabellen validiert sie auch im SQL-only-Modus. Sie muss vom Eigentümer der Tabelle getrennt sein und die oben gezeigten Attribute und Metadaten-Grants besitzen. attach_table verwaltet ihren Zugriff auf jede zugeordnete Tabelle. Für den SQL-only-Betrieb sind weder Passwort noch Netzwerk-Listener erforderlich.

Eine Tabelle anhängen

Verwenden Sie eine vorhandene dauerhafte Tabelle mit einem unterstützten Primärschlüssel. Als Datenbank-Superuser in der konfigurierten Datenbank:

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

Gewähren Sie einer vorhandenen Anwendungsrolle nur die nötigen Rechte:

GRANT SELECT ON public.items TO app_user;
GRANT USAGE ON SCHEMA local_cache TO app_user;
GRANT EXECUTE ON FUNCTION local_cache.mget(regclass, anyarray) TO app_user;

Gewöhnliche SELECT-Abfragen werden von der Erweiterung nicht umgeschrieben.

Kaltes Füllen und warmen Treffer prüfen

SELECT local_cache.invalidate('public.items');
SELECT local_cache.mget('public.items'::regclass, ARRAY[1]::bigint[]);
SELECT local_cache.mget('public.items'::regclass, ARRAY[1]::bigint[]);
SELECT local_cache.stats();

Bestätigen Sie, dass local_cache.health() bereit ist, die Zuordnung konvergiert ist und sich die SQL-Cache-Zähler wie erwartet bewegen.

Optionales RESP2 aktivieren

RESP2 fügt einen Listener, Worker-Prozesse und ein gemeinsames Token hinzu. Es verwendet dieselbe dedizierte PostgreSQL-Rolle, die für das Anhängen von Tabellen erforderlich ist:

sudo ./pg_local_cache-package/install.sh preflight \
  --database app \
  --mode resp \
  --token-file /secure/path/token

sudo ./pg_local_cache-package/install.sh install \
  --database app \
  --mode resp \
  --token-file /secure/path/token \
  --restart-method systemd \
  --systemd-unit postgresql@16-main

Halten Sie den Listener auf 127.0.0.1 oder hinter authentifiziertem TLS. RESP- Clients teilen sich die konfigurierte Worker-Rolle und erhalten keinen PostgreSQL-ACL-Kontext pro Client.

Fehlgeschlagene Binärinstallation wiederherstellen

Verwenden Sie das vom Installer ausgegebene Zustandsverzeichnis:

sudo ./pg_local_cache-package/install.sh recover \
  --state-directory /path/printed/by/install

Stellen Sie nicht wieder her, nachdem ein neuer Postmaster Datenverkehr akzeptiert hat, bevor Sie den aufgezeichneten Zustand und die betrieblichen Auswirkungen geprüft haben.

Fehlerbehebung

Als Nächstes lesen Sie die technische Referenz zu SQL-Verträgen, Konsistenz, Speichergrößen, Monitoring und RESP-Sicherheit.

Aktualisiert .