Patroni 4.1.5 Dokumentation

• 1: Einführung
• 2: Installation
• 3: Patroni-Konfiguration
  • 3.1: Dynamische Konfigurationseinstellungen
  • 3.2: YAML-Konfigurationseinstellungen
  • 3.3: Umgebungskonfiguration
• 4: Patroni REST API
• 5: patronictl
• 6: Replikaterstellung und Cluster-Initialisierung
• 7: Replikationsmodi
• 8: Standby-Cluster
• 9: Watchdog-Unterstützung
• 10: Cluster-Verwaltung pausieren und fortsetzen
• 11: DCS-Failsafe-Modus
• 12: Patroni mit Kubernetes verwenden
• 13: Citus-Unterstützung
• 14: Eine eigenständige Instanz in einen Patroni-Cluster überführen
• 15: Integration mit anderen Werkzeugen
• 16: Sicherheitshinweise
• 17: Hochverfügbarkeit über mehrere Rechenzentren
• 18: Häufige Fragen
• 19: Versionshinweise
• 20: Leitfaden zur Mitarbeit

Warnung

Betrieb von Patroni auf Systemen mit begrenztem Arbeitsspeicher und Python 3.11+

Wenn Sie Patroni auf einem System mit strengen Speichergrenzen betreiben, beispielsweise mit vm.overcommit_memory=2 (für PostgreSQL empfohlen), und Python 3.11 oder neuer verwenden, kann unerwartetes Verhalten auftreten:

• Patroni scheint ordnungsgemäß zu funktionieren
• PostgreSQL läuft weiter
• Die REST API von Patroni reagiert nicht mehr
• Das Betriebssystem meldet, dass Patroni auf dem REST API-Port lauscht
• Die Patroni-Protokolle erscheinen normal; einmalig können jedoch folgende Meldungen auftreten: Exception ignored in thread started by: <object repr() failed>, MemoryError
• Die Kernel-Protokolle können Meldungen wie not enough memory for the allocation enthalten

Dieses Verhalten wird durch einen Fehler in Python 3.11+ verursacht. Bei strengen Speichergrenzen kann der Start eines neuen Threads auf unbestimmte Zeit hängen bleiben, wenn nicht genügend freier Arbeitsspeicher verfügbar ist.

Empfohlene Lösung

Neuere Patroni-Versionen (4.1.1+, 4.0.8+) verringern die Auswirkungen dieses Problems, indem sie alle erforderlichen Threads früh beim Start erzeugen, bevor das System unter Speicherdruck gerät.

Weitere Empfehlungen (Linux, glibc)

Beim Betrieb mit vm.overcommit_memory=2 (für PostgreSQL empfohlen) empfehlen wir außerdem, Patroni mit den folgenden Umgebungsvariablen zu starten:

• MALLOC_ARENA_MAX=1 - verringert den von glibc für Anwendungen mit mehreren Threads reservierten virtuellen Speicher
• PG_MALLOC_ARENA_MAX= - setzt den Wert von MALLOC_ARENA_MAX für PostgreSQL-Prozesse zurück, die Patroni startet.

Zusätzlich können Sie folgende Patroni-Konfigurationsparameter anpassen:

• thread_stack_size - Stackgröße der von Patroni gestarteten Threads. Ein niedrigerer Wert verringert den Speicherbedarf des Patroni-Prozesses. Der von Patroni vorgegebene Standardwert ist 512kB. Erhöhen Sie thread_stack_size, wenn Patroni aufgrund von Stackproblemen abstürzt; andernfalls reicht der Standardwert aus.
• thread_pool_size - Größe des Threadpools, den Patroni für asynchrone Aufgaben und die REST API-Kommunikation mit anderen Mitgliedern bei der Leader-Wahl oder bei Failsafe-Prüfungen verwendet. Der Standardwert ist 5 und reicht für Cluster mit drei Knoten aus.
• restapi.thread_pool_size - Größe des Threadpools zur Bearbeitung von REST API-Anfragen. Der Standardwert ist 5 und erlaubt bis zu fünf parallele REST API-Anfragen. Anfragen mit SQL-Abfragen werden jedoch praktisch nacheinander verarbeitet, da nur eine Datenbankverbindung verwendet wird. Eine Erhöhung dieses Wertes bringt daher üblicherweise keinen Vorteil.

---

Patroni ist eine Vorlage für PostgreSQL-Lösungen zur Hochverfügbarkeit (HA) auf Basis von Python. Für eine möglichst breite Einsetzbarkeit unterstützt Patroni verschiedene verteilte Konfigurationsspeicher wie ZooKeeper , etcd , Consul oder Kubernetes . Datenbankentwickler, DBAs, DevOps-Fachleute und SREs, die PostgreSQL mit HA schnell in Rechenzentren oder anderswo bereitstellen möchten, finden darin hoffentlich ein hilfreiches Werkzeug.

Wir nennen Patroni eine „Vorlage“, weil es keineswegs ein universelles oder sofort einsatzbereites Replikationssystem ist. Es hat seine Besonderheiten und Einschränkungen. Setzen Sie es mit Bedacht ein. Es gibt viele Möglichkeiten, PostgreSQL hochverfügbar zu betreiben; eine Übersicht bietet die PostgreSQL-Dokumentation .

Derzeit unterstützte PostgreSQL-Versionen: 9.3 bis 18.

Hinweis für Citus-Anwender: Ab Version 3.0 integriert sich Patroni gut mit der Postgres-Datenbankerweiterung Citus . Weitere Informationen zur gemeinsamen Nutzung der Patroni-Hochverfügbarkeit mit einem verteilten Citus-Cluster finden Sie auf der Seite zur Citus-Unterstützung in der Patroni-Dokumentation.

Hinweis für Kubernetes-Anwender: Patroni kann direkt auf Kubernetes laufen. Lesen Sie dazu das Kapitel Kubernetes der Patroni-Dokumentation.

1 - Einführung

Patroni ist eine Vorlage für PostgreSQL-Lösungen zur Hochverfügbarkeit (HA) auf Basis von Python. Es entstand als Fork von Governor , einem Projekt von Compose, und enthält zahlreiche neue Funktionen.

Weitere Hintergrundinformationen:

• PostgreSQL-HA mit Kubernetes und Patroni , Vortrag von Josh Berkus auf der KubeCon 2016 (Video)
• Beitrag im Zalando-Tech-Blog vom Februar 2016

Entwicklungsstand

Patroni wird aktiv weiterentwickelt und nimmt Beiträge entgegen. Weitere Einzelheiten stehen im Abschnitt Mitwirken weiter unten.

Informationen zu neuen Versionen veröffentlichen wir hier .

Technische Voraussetzungen und Installation

Anleitungen zur Installation und zum Upgrade von Patroni auf verschiedenen Plattformen stehen hier .

Anzahl der PostgreSQL-Knoten planen

Patroni-/PostgreSQL-Knoten sind von den DCS-Knoten unabhängig (außer wenn Patroni RAFT selbst implementiert). Daher gibt es keine Mindestanzahl an Knoten. Ein Cluster aus einem Primärserver und einem Standby kann problemlos betrieben werden. Weitere Standby-Knoten können später hinzugefügt werden.

Cluster mit 2 Knoten (Primärserver + Standby) sind üblich und bieten automatisches Failover mit Hochverfügbarkeit. Während eines Failovers besteht vorübergehend keine Redundanz, bis der ausgefallene Knoten wieder beitritt.

DCS-Anforderungen: Der DCS (etcd, ZooKeeper, Consul) muss für zuverlässigen Konsens und Fehlertoleranz mit 3 oder 5 Knoten betrieben werden. Ein einzelner DCS-Cluster kann Informationen für Hunderte oder Tausende Patroni-Cluster speichern, die unterschiedliche namespace/scope-Kombinationen verwenden.

Ausführen und Konfigurieren

Der folgende Abschnitt setzt voraus, dass das Patroni-Repository von https://github.com/patroni/patroni geklont wurde. Insbesondere werden die Beispielkonfigurationen postgres0.yml und postgres1.yml benötigt. Wurde Patroni mit pip installiert, können diese Dateien aus dem Git-Repository bezogen werden; ./patroni.py ist dann unten durch den Befehl patroni zu ersetzen.

Die folgenden Befehle verwenden die etcd-v2-API und erfordern eine etcd-Version mit Unterstützung für --enable-v2, etwa etcd 3.5. Bei etcd 3.6 oder neuer stattdessen die etcd3-Konfiguration von Patroni verwenden, da etcd 3.6 die Unterstützung der v2-API entfernt hat .

Zum Einstieg die folgenden Befehle in verschiedenen Terminals ausführen:

> etcd --data-dir=data/etcd --enable-v2=true
> ./patroni.py postgres0.yml
> ./patroni.py postgres1.yml

Daraufhin startet ein hochverfügbarer Cluster. Verschiedene Einstellungen in den YAML-Dateien ausprobieren, um ihre Auswirkungen auf das Clusterverhalten zu beobachten. Einzelne Komponenten beenden, um das Verhalten des Systems zu testen.

Weitere Dateien postgres*.yml hinzufügen, um einen noch größeren Cluster zu erstellen.

Patroni stellt eine HAProxy -Konfiguration bereit, die der Anwendung einen einzelnen Endpunkt für Verbindungen zum Cluster-Leader bietet. Zur Einrichtung folgende Befehle ausführen:

> haproxy -f haproxy.cfg

> psql --host 127.0.0.1 --port 5000 postgres

YAML-Konfiguration

Ausführliche Informationen zu den Einstellungen für etcd, Consul und ZooKeeper stehen hier . Ein Beispiel enthält postgres0.yml .

Konfiguration über Umgebungsvariablen

Ausführliche Informationen zum Festlegen und Überschreiben von Einstellungen über Umgebungsvariablen stehen hier .

Replikationsmöglichkeiten

Patroni verwendet die Streaming-Replikation von Postgres, die standardmäßig asynchron arbeitet. In der asynchronen Replikationskonfiguration von Patroni lässt sich maximum_lag_on_failover setzen. Diese Einstellung verhindert die Hochstufung eines Followers bei einem Failover, wenn er mehr als die festgelegte Anzahl Bytes hinter dem Leader liegt. Ihr Wert sollte je nach geschäftlichen Anforderungen erhöht oder verringert werden. Für stärkere Garantien zur Dauerhaftigkeit kann auch synchrone Replikation verwendet werden. Einzelheiten stehen in der Dokumentation zu Replikationsmodi .

Anwendungen sollten keine Superuser verwenden

Für Verbindungen aus Anwendungen immer einen Benutzer ohne Superuser-Rechte verwenden. Patroni benötigt Datenbankzugriff, um ordnungsgemäß zu funktionieren. Verwendet eine Anwendung einen Superuser, kann sie möglicherweise den gesamten Verbindungspool belegen, einschließlich der über superuser_reserved_connections für Superuser reservierten Verbindungen. Kann Patroni wegen eines vollen Verbindungspools nicht auf den Primärserver zugreifen, führt dies zu unerwünschtem Verhalten.

Die HA-Lösung testen

Das Testen einer HA-Lösung ist zeitaufwendig und umfasst viele Einflussgrößen. Dies gilt besonders für eine plattformübergreifende Anwendung. Dafür wird ein geschulter Systemadministrator oder Berater benötigt. Die Dokumentation kann dies nicht im Detail abdecken.

Folgende Teile der Infrastruktur sollten auf jeden Fall getestet werden:

• Netzwerk (sowohl das dem System vorgelagerte Netzwerk als auch die NICs $$physisch oder virtuell$$selbst)
• Datenträger-IO
• Dateilimits (nofile unter Linux)
• RAM. Auch bei deaktiviertem oomkiller kann fehlender Arbeitsspeicher Probleme verursachen.
• CPU
• Ressourcenkonkurrenz bei der Virtualisierung (Überbelegung des Hypervisors)
• Sämtliche cgroup-Beschränkungen (wahrscheinlich im Zusammenhang mit den obigen Punkten)
• kill -9 für einen beliebigen postgres-Prozess (außer postmaster!). Dies simuliert einen Segmentation Fault recht gut.

Ein postmaster-Prozess sollte dagegen nicht mit kill -9 beendet werden, da das Beenden des Prozesses allein die zugrunde liegenden Bedingungen eines Ressourcenmangels oder anderer Infrastrukturfehler nicht nachbildet. Besteht die Sorge, dass die Infrastruktur unsicher ist und ein Angreifer kill -9 ausführen könnte, kann kein HA-Verfahren das beheben. Der Angreifer würde den Prozess einfach erneut beenden oder auf andere Weise Schaden anrichten.

2 - Installation

Voraussetzungen unter Mac OS

Zum Installieren der Voraussetzungen auf einem Mac folgenden Befehl ausführen:

brew install postgresql etcd haproxy libyaml python

Psycopg

Seit psycopg2-2.8 wird die Binärversion von psycopg2 nicht mehr standardmäßig installiert. Für die Installation aus dem Quellcode werden ein C-Compiler sowie die Entwicklungspakete für Postgres und Python benötigt. Da sich in Python keine Abhängigkeit in der Form psycopg2 OR psycopg2-binary angeben lässt, muss die Installationsart selbst gewählt werden.

Es stehen mehrere Möglichkeiten zur Verfügung:

1. Den Paketmanager der Distribution verwenden.

sudo apt-get install python3-psycopg2  # install psycopg2 module on Debian/Ubuntu
sudo yum install python3-psycopg2      # install psycopg2 on RedHat/Fedora/CentOS

2. Bei der Installation von Patroni mit pip eines der Pakete psycopg3, psycopg2 oder psycopg2-binary in der Liste der Abhängigkeiten angeben.

Allgemeine Installation mit pip

Patroni lässt sich mit pip installieren:

pip install patroni[dependencies]

Dabei kann dependencies leer sein oder aus einem oder mehreren der folgenden Einträge bestehen:

etcd oder etcd3
Modul python-etcd, um etcd als verteilten Konfigurationsspeicher (DCS) zu verwenden

consul
Modul py-consul, um Consul als DCS zu verwenden

zookeeper
Modul kazoo, um ZooKeeper als DCS zu verwenden

exhibitor
Modul kazoo, um Exhibitor als DCS zu verwenden (dieselben Abhängigkeiten wie für ZooKeeper)

kubernetes
Modul kubernetes , um Kubernetes als DCS in Patroni zu verwenden

raft
Modul pysyncobj, um die Python-Implementierung von Raft als DCS zu verwenden

aws
boto3, um AWS-Callbacks zu verwenden

jsonlogger
Modul python-json-logger, um die Protokollierung im JSON-Format zu aktivieren

systemd
systemd-python, um die sd_notify-Integration zu verwenden

all
Alle oben genannten Abhängigkeiten (außer der psycopg-Familie)

psycopg3
Modul psycopg[binary]>=3.0.0

psycopg2
Modul psycopg2>=2.5.4

psycopg2-binary
Modul psycopg2-binary

Um Patroni zusammen mit psycopg3, den Abhängigkeiten für etcd als DCS und den AWS-Callbacks zu installieren, lautet der Befehl beispielsweise:

pip install patroni[psycopg3,etcd3,aws]

Externe Werkzeuge, die in Skripten zur Replikaterstellung oder benutzerdefinierten Cluster-Initialisierung aufgerufen werden (z. B. WAL-E), sollten unabhängig von Patroni installiert werden.

Paketinstallation unter Linux

Für das verwendete Betriebssystem sind möglicherweise Patroni-Pakete verfügbar. Die Postgres-Community erstellt solche Pakete für:

• RHEL, RockyLinux, AlmaLinux;
• Debian und Ubuntu;
• SUSE Enterprise Linux.

Es gibt auch Pakete für direkte Abhängigkeiten von Patroni, etwa Python-Module, die möglicherweise nicht in den offiziellen Paketquellen des Betriebssystems enthalten sind.

Weitere Informationen stehen in der Dokumentation des PGDG-Repositorys .

Bei einem auf RedHat Enterprise Linux basierenden Betriebssystem werden möglicherweise zusätzlich Pakete aus EPEL benötigt; siehe die Dokumentation des EPEL-Repositorys .

Nach dem Einrichten des PGDG-Repositorys für das Betriebssystem kann Patroni installiert werden.

Installation auf Debian-basierten Distributionen

Nach dem Einrichten des PGDG-Repositorys, siehe oben , Patroni mit apt installieren:

apt-get install patroni

Installation auf RedHat-basierten Distributionen

Nach dem Einrichten des PGDG-Repositorys, siehe oben , Patroni mit etcd als DCS unter RHEL 9 (und davon abgeleiteten Distributionen) über dnf installieren:

dnf install patroni patroni-etcd

Bietet die RedHat-basierte Distribution keine etcd-Pakete an, kann etcd aus PGDG installiert werden. Auf den für den DCS vorgesehenen Knoten folgende Befehle ausführen:

dnf install 'dnf-command(config-manager)'
dnf config-manager --enable pgdg-rhel9-extras
dnf install etcd

Falls erforderlich, die RHEL-Version im Repository durch 8 ersetzen, sodass sich pgdg-rhel8-extras ergibt. Auch auf RockyLinux, AlmaLinux, Oracle Linux usw. lautet der Repository-Name pgdg-rhelN-extras.

Installation unter SUSE Enterprise Linux

Für einige Abhängigkeiten müssen möglicherweise die SUSE-PackageHub-Repositorys aktiviert werden. Siehe die Dokumentation von SUSE PackageHub .

Unter SLES 15 kann Patroni nach dem Einrichten des PGDG-Repositorys, siehe oben , wie folgt installiert werden:

zypper install patroni patroni-etcd

Mit aktiviertem SUSE-PackageHub-Repository lässt sich auch etcd installieren:

SUSEConnect -p PackageHub/15.5/x86_64
zypper install etcd

Upgrade

Ein Upgrade von Patroni ist sehr einfach: Die Softwareinstallation aktualisieren und den Patroni-Daemon auf jedem Knoten im Cluster neu starten.

Der Neustart des Patroni-Daemons führt jedoch zu einem Neustart der Postgres-Datenbank. Dies kann unter bestimmten Umständen ein Failover des Primärservers auslösen. Deshalb wird empfohlen, den Cluster bis zum Abschluss des Patroni-Daemon-Neustarts in den Wartungsmodus zu versetzen.

Dazu auf einem der Patroni-Knoten folgenden Befehl ausführen:

patronictl pause --wait

Anschließend auf jedem Clusterknoten das für das Betriebssystem erforderliche Paketupgrade durchführen:

apt-get update && apt-get install patroni

Den Patroni-Daemon-Prozess auf jedem Knoten neu starten:

systemctl restart patroni

Abschließend die Postgres-Überwachung durch Patroni wieder aufnehmen und damit den Wartungsmodus beenden:

patronictl resume --wait

Der Cluster ist nun mit der neuen Patroni-Version wieder voll betriebsbereit.

3 - Patroni-Konfiguration

Es gibt 3 Arten der Patroni-Konfiguration:

• Globale dynamische Konfiguration .
  Diese Optionen werden im DCS (verteilter Konfigurationsspeicher) gespeichert und auf allen Clusterknoten angewendet. Die dynamische Konfiguration kann jederzeit mit dem Werkzeug patronictl_edit_config oder der REST API von Patroni festgelegt werden. Gehören die geänderten Optionen nicht zur Startkonfiguration, werden sie asynchron (beim nächsten Aufwachen der Verarbeitungsschleife) auf jedem Knoten angewendet; dessen Konfiguration wird anschließend neu geladen. Erfordert ein Knoten einen Neustart, um die Konfiguration anzuwenden (wenn sich Werte von PostgreSQL-Parametern mit dem Kontext postmaster geändert haben), wird dies durch das spezielle Flag pending_restart im JSON members.data gekennzeichnet. Zusätzlich zeigt der Knotenstatus "restart_pending": true an.

• Lokale Konfigurationsdatei (patroni.yml).
  Diese Optionen werden in der Konfigurationsdatei definiert und haben Vorrang vor der dynamischen Konfiguration. patroni.yml kann zur Laufzeit geändert und neu geladen werden (ohne Patroni neu zu starten), indem SIGHUP an den Patroni-Prozess gesendet, die REST-API-Anfrage POST /reload gestellt oder patronictl_reload ausgeführt wird. Die lokale Konfiguration kann entweder aus einer einzelnen YAML-Datei oder einem Verzeichnis bestehen. Bei einem Verzeichnis werden alle darin enthaltenen YAML-Dateien nacheinander in sortierter Reihenfolge geladen. Ist ein Schlüssel in mehreren Dateien definiert, hat sein Vorkommen in der letzten Datei Vorrang.

• Umgebungskonfiguration .
  Einige „lokale“ Konfigurationsparameter können über Umgebungsvariablen festgelegt oder überschrieben werden. Die Umgebungskonfiguration ist sehr nützlich in dynamischen Umgebungen, in denen einige Parameter nicht im Voraus bekannt sind (beispielsweise lässt sich beim Betrieb in docker die externe IP-Adresse nicht im Voraus kennen).

Wichtige Regeln

Von Patroni gesteuerte PostgreSQL-Parameter

Einige PostgreSQL-Parameter müssen auf dem Primärserver und den Replikaten dieselben Werte haben. Für diese Parameter haben Werte aus den lokalen Patroni-Konfigurationsdateien oder aus Umgebungsvariablen keine Wirkung. Um ihre Werte zu ändern oder festzulegen, muss die gemeinsame Konfiguration im DCS geändert werden. Die folgende Liste enthält diese Parameter mit ihren Standard- und Mindestwerten:

• max_connections: Standardwert 100, Mindestwert 25
• max_locks_per_transaction: Standardwert 64, Mindestwert 32
• max_worker_processes: Standardwert 8, Mindestwert 2
• max_prepared_transactions: Standardwert 0, Mindestwert 0
• wal_level: Standardwert hot_standby, zulässige Werte: hot_standby, replica, logical
• track_commit_timestamp: Standardwert off

Für die folgenden Parameter verlangt PostgreSQL keine gleichen Werte auf dem Primärserver und allen Replikaten. Da ein Replikat jedoch jederzeit zum Primärserver werden kann, sind unterschiedliche Werte kaum sinnvoll; daher erlaubt Patroni das Festlegen ihrer Werte ausschließlich über die dynamische Konfiguration .

• max_wal_senders: Standardwert 10, Mindestwert 3
• max_replication_slots: Standardwert 10, Mindestwert 4
• wal_keep_segments: Standardwert 8, Mindestwert 1
• wal_keep_size: Standardwert 128MB, Mindestwert 16MB
• wal_log_hints: on

Diese Parameter werden auf sinnvolle Werte beziehungsweise die Einhaltung eines Mindestwerts geprüft.

Patroni steuert außerdem einige weitere Postgres-Parameter:

• listen_addresses - wird aus postgresql.listen oder der Umgebungsvariablen PATRONI_POSTGRESQL_LISTEN gesetzt
• port - wird aus postgresql.listen oder der Umgebungsvariablen PATRONI_POSTGRESQL_LISTEN gesetzt
• cluster_name - wird aus scope oder der Umgebungsvariablen PATRONI_SCOPE gesetzt
• hot_standby: on

Zur Sicherheit werden die Parameter aus den obigen Listen in postgresql.conf geschrieben und als Argumentliste an postgres übergeben. Dadurch haben sie die höchste Priorität (ausgenommen wal_keep_segments und wal_keep_size), noch vor ALTER SYSTEM .

Einige Parameter wie postgresql.listen und postgresql.data_dir können nur lokal festgelegt werden, also in der Patroni-Konfigurationsdatei oder über eine Konfigurationsvariable . In den meisten Fällen überschreibt die lokale Konfiguration die dynamische Konfiguration.

Beim Anwenden lokaler oder dynamischer Konfigurationsoptionen werden folgende Schritte ausgeführt:

• Der Knoten prüft zunächst, ob eine Datei postgresql.base.conf vorhanden oder der Parameter custom_conf gesetzt ist.
• Ist custom_conf gesetzt, dient die dort angegebene Datei als Basiskonfiguration; postgresql.base.conf und postgresql.conf werden ignoriert.
• Ist custom_conf nicht gesetzt und existiert postgresql.base.conf, enthält diese Datei die umbenannte „ursprüngliche“ Konfiguration und dient als Basiskonfiguration.
• Ist weder custom_conf gesetzt noch postgresql.base.conf vorhanden, wird die ursprüngliche postgresql.conf in postgresql.base.conf umbenannt und als Basiskonfiguration verwendet.
• Die dynamischen Optionen werden (mit den obigen Ausnahmen) in postgresql.conf geschrieben. In postgresql.conf wird außerdem ein include für die Basiskonfiguration gesetzt (entweder postgresql.base.conf oder die Datei aus custom_conf). So lassen sich neue Optionen anwenden, ohne die Konfigurationsdatei erneut einzulesen, um das Vorhandensein des include zu prüfen.
• Einige Parameter, die für die Clusterverwaltung durch Patroni wesentlich sind, werden über die Befehlszeile überschrieben.
• Wird eine Option geändert, die einen Neustart erfordert (hierfür sollten der Kontext in pg_settings und die tatsächlichen Werte dieser Optionen betrachtet werden), wird auf diesem Knoten das Flag pending_restart gesetzt. Dieses Flag wird bei jedem Neustart zurückgesetzt.

Die Parameter werden in der folgenden Reihenfolge angewendet (Laufzeitparameter haben die höchste Priorität):

1. Parameter aus der Datei postgresql.base.conf laden (oder aus einer custom_conf-Datei, falls gesetzt)
2. Parameter aus der Datei postgresql.conf laden
3. Parameter aus der Datei postgresql.auto.conf laden
4. Laufzeitparameter über -o --name=value

Dies ermöglicht die Konfiguration aller Knoten (2) sowie eines bestimmten Knotens mit ALTER SYSTEM (3) und stellt sicher, dass für den Betrieb von Patroni wesentliche Parameter durchgesetzt werden (4). Zugleich bleibt Raum für Konfigurationswerkzeuge, die postgresql.conf direkt ohne Beteiligung von Patroni verwalten (1).

PostgreSQL-Parameter mit Einfluss auf den gemeinsam genutzten Speicher

PostgreSQL hat einige Parameter, die die Größe des von ihnen verwendeten gemeinsam genutzten Speichers bestimmen:

• max_connections
• max_prepared_transactions
• max_locks_per_transaction
• max_wal_senders
• max_worker_processes

Änderungen dieser Parameter werden erst nach einem PostgreSQL-Neustart wirksam. Ihre Strukturen im gemeinsam genutzten Speicher dürfen auf den Standby-Knoten nicht kleiner sein als auf dem Primärserver.

Wie bereits erläutert, erlaubt Patroni Änderungen ihrer Werte nur über die dynamische Konfiguration . Dies umfasst üblicherweise:

1. Änderungen mit patronictl_edit_config anwenden (oder über den REST-API-Endpunkt /config)
2. Knoten mit patronictl_restart neu starten (oder über den REST-API-Endpunkt /restart)

Hinweis: PostgreSQL-Knoten sollten mit dem Befehl patronictl_restart oder über den REST-API-Endpunkt /restart neu gestartet werden. Der Versuch, PostgreSQL durch einen Neustart des Patroni-Daemons neu zu starten, etwa mit systemctl restart patroni, kann beim Neustart des Primärservers ein Failover im Cluster auslösen.

Da diese Einstellungen den gemeinsam genutzten Speicher steuern, ist beim Neustart der Knoten zusätzliche Sorgfalt erforderlich:

• Wenn der Wert einer dieser Einstellungen erhöht werden soll:

  1. Zuerst alle Standbys neu starten
  2. Danach den Primärserver neu starten

• Wenn der Wert einer dieser Einstellungen verringert werden soll:

  1. Zuerst den Primärserver neu starten
  2. Danach alle Standbys neu starten

Hinweis: Wenn nach einer Verringerung einer dieser Einstellungen alle Knoten auf einmal neu gestartet werden, ignoriert Patroni die Änderung und startet den Standby mit dem ursprünglichen Wert neu. Daher müssen die Standbys später erneut neu gestartet werden. So verhindert Patroni eine endlose Absturzschleife des Standbys: PostgreSQL beendet sich mit einer FATAL-Meldung, wenn einer dieser Parameter auf einen niedrigeren Wert gesetzt wird als den, den pg_controldata auf dem Standby-Knoten ausweist. Die Einstellung kann auf dem Standby also erst verringert werden, wenn dessen pg_controldata hinsichtlich dieser Änderungen auf dem Primärserver aktuell ist.

Weitere Informationen dazu enthält die Administrationsübersicht von PostgreSQL .

Patroni-Konfigurationsparameter

Auch die folgenden Patroni-Konfigurationsoptionen können nur dynamisch geändert werden:

• ttl: 30
• loop_wait: 10
• retry_timeout: 10
• maximum_lag_on_failover: 1048576
• max_timelines_history: 0
• check_timeline: false
• postgresql.use_slots: true

Bei einer Änderung dieser Optionen liest Patroni den entsprechenden Abschnitt der im DCS gespeicherten Konfiguration und ändert seine Laufzeitwerte.

Patroni-Knoten schreiben den Zustand der DCS-Optionen bei jeder Konfigurationsänderung in die Datei patroni.dynamic.json im Postgres-Datenverzeichnis. Nur der Leader darf diese Optionen aus der gespeicherten Datei wiederherstellen, wenn sie im DCS vollständig fehlen oder ungültig sind.

Konfiguration erzeugen und validieren

Patroni bietet Befehlszeilenschnittstellen zum Erzeugen und Validieren einer lokalen Patroni-Konfiguration . Mit dem ausführbaren Programm patroni lässt sich:

• Eine lokale Patroni-Beispielkonfiguration erstellen;
• Eine Patroni-Konfigurationsdatei für die lokal laufende PostgreSQL-Instanz erstellen (etwa als Vorbereitung für die Patroni-Integration );
• Eine angegebene Patroni-Konfigurationsdatei validieren.

Patroni-Beispielkonfiguration

patroni --generate-sample-config [configfile]

Beschreibung

Erzeugt eine Patroni-Beispielkonfigurationsdatei im Format yaml. Parameterwerte werden über die Umgebungskonfiguration festgelegt. Sind sie dort nicht gesetzt, werden die Standardwerte von Patroni verwendet oder die Zeichenfolge #FIXME für Werte, die der Benutzer später festlegen sollte.

Einige Standardwerte werden anhand der lokalen Umgebung bestimmt:

• postgresql.listen: die von getaddrinfo aufgelöste IP-Adresse zum Hostnamen des aktuellen Rechners, den gethostname zurückgibt, und der Standardport 5432.
• postgresql.connect_address: die von getaddrinfo aufgelöste IP-Adresse zum Hostnamen des aktuellen Rechners, den gethostname zurückgibt, und der Standardport 5432.
• postgresql.authentication.rewind: wird nur definiert, wenn die PostgreSQL-Version anhand der Programmdatei ermittelt werden kann und mindestens 11 ist.
• restapi.listen: die von getaddrinfo aufgelöste IP-Adresse zum Hostnamen des aktuellen Rechners, den gethostname zurückgibt, und der Standardport 8008.
• restapi.connect_address: die von getaddrinfo aufgelöste IP-Adresse zum Hostnamen des aktuellen Rechners, den gethostname zurückgibt, und der Standardport 8008.

Parameter

configfile - vollständiger Pfad zur Konfigurationsdatei, in der das Ergebnis gespeichert wird. Fehlt die Angabe, wird das Ergebnis an stdout ausgegeben.

Patroni-Konfiguration für eine laufende Instanz

patroni --generate-config [--dsn DSN] [configfile]

Beschreibung

Erzeugt eine Patroni-Konfiguration im Format yaml für die lokal laufende PostgreSQL-Instanz. Für die Verbindung zu PostgreSQL wird entweder der angegebene DSN (hat Vorrang) oder die PostgreSQL-Umgebungsvariablen verwendet. Ist kein Passwort angegeben, sollte es auf Aufforderung eingegeben werden.

Alle nicht internen GUCs der Quellinstanz von Postgres dienen als Quelle für die folgenden Patroni-Konfigurationsparameter, unabhängig davon, ob sie über eine Konfigurationsdatei, die postmaster-Befehlszeile oder Umgebungsvariablen gesetzt wurden:

• scope: Wert des GUC cluster_name;
• postgresql.listen: Werte der GUCs listen_addresses und port;
• postgresql.data_dir: Wert des GUC data_directory;
• postgresql.parameters: Werte der GUCs archive_command, restore_command, archive_cleanup_command, recovery_end_command, ssl_passphrase_command, hba_file, ident_file, config_file;
• bootstrap.dcs: alle anderen ermittelten PostgreSQL-GUCs.

Wird scope, postgresql.listen oder postgresql.data_dir nicht aus den Postgres-GUCs gesetzt, wird der jeweilige Wert aus der Umgebungskonfiguration verwendet.

Weitere Regeln zur Bestimmung der Werte:

• name: Wert der Umgebungsvariablen PATRONI_NAME, falls gesetzt, andernfalls der Hostname des aktuellen Rechners.
• postgresql.bin_dir: Pfad zu den Postgres-Programmdateien, ermittelt aus der laufenden Instanz.
• postgresql.connect_address: die von getaddrinfo aufgelöste IP-Adresse zum Hostnamen des aktuellen Rechners, den gethostname zurückgibt, und der für die Verbindung zur Instanz verwendete Port oder der Wert des GUC port.
• postgresql.authentication.superuser: die für die Verbindung zur Instanz verwendete Konfiguration;
• postgresql.pg_hba: die aus der hba_file der Quellinstanz gelesenen Zeilen.
• postgresql.pg_ident: die aus der ident_file der Quellinstanz gelesenen Zeilen.
• restapi.listen: die von getaddrinfo aufgelöste IP-Adresse zum Hostnamen des aktuellen Rechners, den gethostname zurückgibt, und der Standardport 8008.
• restapi.connect_address: die von getaddrinfo aufgelöste IP-Adresse zum Hostnamen des aktuellen Rechners, den gethostname zurückgibt, und der Standardport 8008.

Weitere über die Umgebungskonfiguration definierte Parameter werden ebenfalls in die Konfiguration aufgenommen.

Parameter

configfile
Vollständiger Pfad zur Konfigurationsdatei, in der das Ergebnis gespeichert wird. Fehlt die Angabe, wird das Ergebnis an stdout ausgegeben.

dsn
Optionale DSN-Zeichenfolge für die lokale PostgreSQL-Instanz, aus der die GUC-Werte ermittelt werden sollen.

Patroni-Konfiguration validieren

patroni --validate-config [configfile] [--ignore-listen-port | -i]

Beschreibung

Validiert die angegebene Patroni-Konfiguration und gibt Informationen zu fehlgeschlagenen Prüfungen aus.

Parameter

configfile
Vollständiger Pfad zur zu prüfenden Konfigurationsdatei. Ist er nicht angegeben oder existiert die Datei nicht, wird versucht, die Konfiguration aus der Umgebungsvariablen PATRONI_CONFIGURATION oder, falls diese nicht gesetzt ist, aus den Patroni-Umgebungsvariablen zu lesen.

--ignore-listen-port | -i
Optionales Flag, um bei der Validierung von configfile Bindungsfehler für bereits belegte listen-Ports zu ignorieren.

--print | -p
Optionales Flag, um die lokale Konfiguration (einschließlich der durch die Umgebungskonfiguration überschriebenen Werte) nach erfolgreicher Validierung auszugeben.

3.1 - Dynamische Konfigurationseinstellungen

Die dynamische Konfiguration wird im DCS (verteilter Konfigurationsspeicher) gespeichert und auf allen Clusterknoten angewendet.

Zum Ändern der dynamischen Konfiguration kann entweder das Werkzeug patronictl_edit_config oder die REST API von Patroni verwendet werden.

• loop_wait: Anzahl der Sekunden, die die Schleife schläft. Standardwert: 10, kleinster zulässiger Wert: 1
• ttl: TTL für den Erwerb der Leader-Sperre (in Sekunden). Sie entspricht der Zeitspanne bis zum Beginn eines automatischen Failovers. Standardwert: 30, kleinster zulässiger Wert: 20
• retry_timeout: Zeitüberschreitung für Wiederholungsversuche bei DCS- und PostgreSQL-Operationen (in Sekunden). Kürzer andauernde DCS- oder Netzwerkprobleme führen nicht dazu, dass Patroni den Leader herabstuft. Standardwert: 10, kleinster zulässiger Wert: 3

loop_wait + 2 * retry_timeout <= ttl

• maximum_lag_on_failover: maximaler Rückstand eines Followers in Bytes, mit dem er noch an der Leader-Wahl teilnehmen darf.
• primary_race_backoff: verschiebt die Leader-Wahl auf Standbys um primary_race_backoff Sekunden, wenn die WAL-Replikation vom Primärserver noch voranschreitet. Dies minimiert unnötige Failovers durch ein kurzzeitig nicht reagierendes Patroni. Standardwert: 0 (deaktiviert).
• maximum_lag_on_syncnode: maximaler Rückstand eines synchronen Followers in Bytes, bevor er als fehlerhafter Kandidat gilt und durch einen fehlerfreien asynchronen Follower ersetzt wird. Bei mehr als einem Follower verwendet Patroni die höchste Replikat-LSN, andernfalls die aktuelle WAL-LSN des Leaders. Der Standardwert ist -1. Bei einem Wert von 0 oder weniger tauscht Patroni einen fehlerhaften synchronen Follower nicht aus. Den Wert ausreichend hoch wählen, damit Patroni bei hohem Transaktionsaufkommen synchrone Follower nicht häufig austauscht.
• max_timelines_history: maximale Anzahl der im DCS gespeicherten Einträge des Timeline-Verlaufs. Standardwert: 0. Bei 0 wird der vollständige Verlauf im DCS gespeichert.
• primary_start_timeout: Zeit, die ein Primärserver zur Erholung von Fehlern erhält, bevor ein Failover ausgelöst wird (in Sekunden). Der Standardwert beträgt 300 Sekunden. Bei 0 erfolgt das Failover nach Möglichkeit sofort nach Erkennung eines Absturzes. Bei asynchroner Replikation kann ein Failover zum Verlust von Transaktionen führen. Im schlimmsten Fall beträgt die Failover-Zeit bei Ausfall des Primärservers: loop_wait + primary_start_timeout + loop_wait. Ist primary_start_timeout jedoch null, beträgt sie nur loop_wait. Den Wert entsprechend der Abwägung zwischen Dauerhaftigkeit und Verfügbarkeit festlegen.
• primary_stop_timeout: Anzahl der Sekunden, die Patroni beim Stoppen von Postgres warten darf; wirkt nur bei aktiviertem synchronous_mode. Ist der Wert auf > 0 gesetzt und synchronous_mode aktiviert, sendet Patroni SIGKILL an den postmaster, wenn der Stoppvorgang länger als primary_stop_timeout dauert. Den Wert entsprechend der Abwägung zwischen Dauerhaftigkeit und Verfügbarkeit festlegen. Ist der Parameter nicht gesetzt oder auf <= 0 gesetzt, wird primary_stop_timeout nicht angewendet.
• synchronous_mode: aktiviert den synchronen Replikationsmodus. Mögliche Werte: off, on, quorum. In diesem Modus verwaltet der Leader synchronous_standby_names; nur der zuletzt bekannte Leader oder eines der synchronen Replikate darf an der Leader-Wahl teilnehmen. Der synchrone Modus gewährleistet, dass erfolgreich festgeschriebene Transaktionen bei einem Failover nicht verloren gehen. Dafür entfällt die Schreibverfügbarkeit, wenn Patroni die Dauerhaftigkeit der Transaktionen nicht sicherstellen kann. Einzelheiten enthält die Dokumentation der Replikationsmodi .
• synchronous_mode_strict: verhindert das Deaktivieren der synchronen Replikation, wenn keine synchronen Replikate verfügbar sind, und blockiert dadurch alle Schreibzugriffe von Clients auf den Primärserver. Im prioritätsbasierten synchronen Modus (synchronous_mode: on) setzt Patroni 4.1.5 synchronous_standby_names auf *, wenn kein geeignetes synchrones Replikat verfügbar ist. Einzelheiten enthält die Dokumentation der Replikationsmodi .
• synchronous_node_count: bei aktiviertem synchronous_mode verwaltet Patroni mit diesem Parameter die genaue Anzahl synchroner Standby-Instanzen und passt beim Hinzukommen und Ausscheiden von Mitgliedern den Zustand im DCS und den PostgreSQL-Parameter synchronous_standby_names an. Ist der Wert höher als die Anzahl geeigneter Knoten, wird er automatisch angepasst. Standardwert: 1.
• failsafe_mode: aktiviert den DCS-Failsafe-Modus . Standardwert: false.
• postgresql:
  • use_pg_rewind: bestimmt, ob pg_rewind verwendet wird. Standardwert: false. Der Cluster muss mit data page checksums (Option --data-checksums für initdb) initialisiert worden sein und/oder wal_log_hints muss auf on gesetzt sein, andernfalls funktioniert pg_rewind nicht.
  • use_slots: bestimmt, ob Replikationsslots verwendet werden. Standardwert unter PostgreSQL 9.4+: true.
  • recovery_conf: zusätzliche Konfigurationseinstellungen, die beim Konfigurieren eines Followers in recovery.conf geschrieben werden. Ab PostgreSQL 12 gibt es keine recovery.conf mehr; dieser Abschnitt kann dennoch weiter verwendet werden, da Patroni dies transparent handhabt.
  • parameters: Konfigurationsparameter (GUCs) für Postgres im Format {max_connections: 100, wal_level: "replica", max_wal_senders: 10, wal_log_hints: "on"}. Viele davon sind für die Replikation erforderlich.
  • parameters_primary: (optional) rollenspezifische Parameterüberschreibungen für primary. Diese Werte werden mit den grundlegenden parameters zusammengeführt und überschreiben sie.
  • parameters_replica: (optional) rollenspezifische Parameterüberschreibungen für replica. Diese Werte werden mit den grundlegenden parameters zusammengeführt und überschreiben sie.
  • parameters_standby_leader: (optional) rollenspezifische Parameterüberschreibungen für standby_leader. Diese Werte werden mit den grundlegenden parameters zusammengeführt und überschreiben sie.
  • pg_hba: Liste der Zeilen, aus denen Patroni pg_hba.conf erzeugt. Patroni ignoriert diesen Parameter, wenn der PostgreSQL-Parameter hba_file auf einen anderen Wert als den Standardwert gesetzt ist.
    • - host all all 0.0.0.0/0 md5
    • - host replication replicator 127.0.0.1/32 md5: Eine solche Zeile ist für die Replikation erforderlich.
  • pg_hba_primary: (optional) rollenspezifische pg_hba-Einträge für primary. Sie ersetzen pg_hba vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_hba verwendet.
  • pg_hba_replica: (optional) rollenspezifische pg_hba-Einträge für replica. Sie ersetzen pg_hba vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_hba verwendet.
  • pg_hba_standby_leader: (optional) rollenspezifische pg_hba-Einträge für standby_leader. Sie ersetzen pg_hba vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_hba verwendet.
  • pg_ident: Liste der Zeilen, aus denen Patroni pg_ident.conf erzeugt. Patroni ignoriert diesen Parameter, wenn der PostgreSQL-Parameter ident_file auf einen anderen Wert als den Standardwert gesetzt ist.
    • - mapname1 systemname1 pguser1
    • - mapname1 systemname2 pguser2
  • pg_ident_primary: (optional) rollenspezifische pg_ident-Einträge für primary. Sie ersetzen pg_ident vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_ident verwendet.
  • pg_ident_replica: (optional) rollenspezifische pg_ident-Einträge für replica. Sie ersetzen pg_ident vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_ident verwendet.
  • pg_ident_standby_leader: (optional) rollenspezifische pg_ident-Einträge für standby_leader. Sie ersetzen pg_ident vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_ident verwendet.
• standby_cluster: ist dieser Abschnitt definiert, soll ein Standby-Cluster initialisiert werden.
  • host: Adresse des entfernten Knotens
  • port: Port des entfernten Knotens
  • primary_slot_name: auf dem entfernten Knoten für die Replikation zu verwendender Slot. Dieser Parameter ist optional; der Standardwert wird aus dem Instanznamen abgeleitet (siehe Funktion slot_name_from_member_name).
  • create_replica_methods: geordnete Liste der Methoden, mit denen ein Standby-Leader vom entfernten Primärserver initialisiert werden kann. Sie kann sich von der in postgresql_settings definierten Liste unterscheiden.
  • restore_command: Befehl zur Wiederherstellung von WAL-Einträgen des entfernten Primärservers auf den Knoten eines Standby-Clusters. Er kann sich von der in postgresql_settings definierten Liste unterscheiden.
  • archive_cleanup_command: Bereinigungsbefehl für den Standby-Leader
  • recovery_min_apply_delay: Wartezeit vor dem tatsächlichen Anwenden von WAL-Einträgen auf einem Standby-Leader
• member_slots_ttl: Aufbewahrungszeit physischer Replikationsslots für heruntergefahrene Replikate. Standardwert: 30min. Bei 0 bleibt das bisherige Verhalten erhalten (der Slot wird sofort entfernt, wenn der Mitgliedsschlüssel im DCS abläuft). Die Funktion wird erst ab PostgreSQL 11 unterstützt.
• slots: definiert permanente Replikationsslots. Diese Slots bleiben bei einem Switchover/Failover erhalten. Nicht vorhandene permanente Slots werden von Patroni erstellt. Ab PostgreSQL 11 werden permanente physische Slots auf allen Knoten angelegt und ihre Position alle loop_wait Sekunden vorgerückt. Bei PostgreSQL-Versionen vor 11 werden permanente physische Replikationsslots nur auf dem aktuellen Primärserver verwaltet. Logische Slots werden mit einem Neustart vom Primärserver auf einen Standby kopiert; anschließend wird ihre Position bei Bedarf alle loop_wait Sekunden vorgerückt. Das Kopieren der Dateien logischer Slots erfolgt über eine libpq-Verbindung mit den Zugangsdaten für rewind oder den Superuser (siehe Abschnitt postgresql.authentication). Die Position eines logischen Slots auf dem Replikat kann immer etwas hinter der des bisherigen Primärservers liegen. Daher sollte die Anwendung darauf vorbereitet sein, dass einige Nachrichten nach einem Failover erneut empfangen werden können. Am einfachsten lässt sich dies durch Verfolgen von confirmed_flush_lsn handhaben. Permanente Replikationsslots erfordern, dass postgresql.use_slots auf true gesetzt ist. Sind permanente logische Replikationsslots definiert, aktiviert Patroni automatisch hot_standby_feedback. Da das Failover logischer Replikationsslots unter PostgreSQL 9.6 und älter unsicher ist und PostgreSQL 10 einige wichtige Funktionen fehlen, wird diese Funktion nur unter PostgreSQL 11+ unterstützt.
  • my_slot_name: Name des permanenten Replikationsslots. Entspricht der Name des permanenten Slots dem Namen des aktuellen Knotens, wird er auf diesem Knoten nicht erstellt. Wird ein permanenter physischer Replikationsslot hinzugefügt, dessen Name dem eines Patroni-Mitglieds entspricht, stellt Patroni sicher, dass der erstellte Slot auch dann nicht entfernt wird, wenn das zugehörige Mitglied nicht mehr reagiert. Normalerweise würde Patroni den Slot in dieser Situation entfernen. Das kann nützlich sein, etwa wenn die von Mitgliedern verwendeten Replikationsslots während vorübergehender Ausfälle erhalten bleiben sollen oder bestehende Mitglieder in einen neuen Patroni-Cluster übernommen werden (siehe Eine eigenständige Instanz in einen Patroni-Cluster überführen ). Betreiber sollten jedoch darauf achten, solche Namensüberschneidungen nicht im DCS zu belassen, wenn der Slot nicht mehr benötigt wird, da sie den normalen Betrieb von Patroni beeinflussen.
    • type: Slot-Typ. Möglich sind physical oder logical. Bei einem logischen Slot müssen zusätzlich database und plugin definiert werden. Bei einem physischen Slot kann optional cluster_type definiert werden.
    • database: Name der Datenbank, in der logische Slots erstellt werden sollen.
    • plugin: Name des Plugins für den logischen Slot.
    • cluster_type: Clustertyp (primary oder standby), auf dem der Slot ausschließlich erstellt werden soll. Andernfalls wird er nicht erstellt beziehungsweise ein bereits vorhandener Slot gelöscht.
• ignore_slots: Liste von Gruppen von Replikationsslot-Eigenschaften; Patroni soll Slots ignorieren, die diesen Eigenschaften entsprechen. Diese Konfiguration/Funktion ist nützlich, wenn einige Replikationsslots außerhalb von Patroni verwaltet werden. Jede passende Teilmenge von Eigenschaften führt dazu, dass ein Slot ignoriert wird.
  • name: Name des Replikationsslots.
  • type: Slot-Typ. Möglich sind physical oder logical. Bei einem logischen Slot können zusätzlich database und/oder plugin definiert werden.
  • database: Datenbankname (beim Abgleich eines logical-Slots).
  • plugin: Plugin für logische Dekodierung (beim Abgleich eines logical-Slots).

Hinweis: slots ist eine Hashmap, ignore_slots dagegen ein Array. Beispiel:

slots:
  permanent_logical_slot_name:
    type: logical
    database: my_db
    plugin: test_decoding
  permanent_physical_slot_name:
    type: physical
  ...
ignore_slots:
  - name: ignored_logical_slot_name
    type: logical
    database: my_db
    plugin: test_decoding
  - name: ignored_physical_slot_name
    type: physical
  ...

Hinweis: Unter PostgreSQL v11 oder neuer verwaltet Patroni physische Replikationsslots auf allen Knoten, die potenziell Leader werden können. Replikatknoten halten dadurch WAL-Segmente vor, die andere Knoten möglicherweise benötigen. Ist ein Knoten nicht verfügbar und läuft sein Mitgliedsschlüssel im DCS ab, wird der zugehörige Replikationsslot nach member_slots_ttl entfernt (Standardwert 30min). Die Aufbewahrungszeit kann je nach Bedarf erhöht oder verringert werden. Bei einer statischen Clustertopologie (feste Anzahl von Knoten, deren Namen sich nie ändern) können alternativ permanente physische Replikationsslots mit den Namen der Knoten konfiguriert werden. So werden Slots nicht entfernt und WAL-Dateien nicht wiederverwendet, während ein Replikat vorübergehend ausgefallen ist:

slots:
  node_name1:
    type: physical
  node_name2:
    type: physical
  node_name3:
    type: physical
  ...

3.2 - YAML-Konfigurationseinstellungen

Global/Allgemein

• thread_pool_size: Größe des Threadpools, mit dem Patroni asynchrone Aufgaben ausführt und während der Leader-Wahl oder bei Failsafe-Prüfungen über die REST API mit anderen Mitgliedern kommuniziert. Mindestwert: 5, Standardwert: 5.
• thread_stack_size: legt die Stackgröße für von Patroni gestartete Threads fest. Der Wert muss an 64kB ausgerichtet sein. Mindestwert: 64kB, Standardwert (von Patroni gesetzt): 512kB.
• name: Name des Hosts. Er muss im Cluster eindeutig sein.
• namespace: Pfad im Konfigurationsspeicher, unter dem Patroni Informationen über den Cluster speichert. Standardwert: “/service”
• scope: Clustername

Protokollierung

• type: legt das Protokollformat fest. Mögliche Werte sind plain und json. Für das Format json muss jsonlogger installiert sein. Der Standardwert ist plain.
• level: legt die allgemeine Protokollierungsstufe fest. Standardwert: INFO (siehe Dokumentation der Python-Protokollierung )
• traceback_level: legt die Stufe fest, auf der Tracebacks sichtbar sind. Standardwert: ERROR. Auf DEBUG setzen, wenn Tracebacks nur bei aktiviertem log.level=DEBUG sichtbar sein sollen.
• format: legt die Formatzeichenfolge für Protokolle fest. Beim Protokolltyp plain sollte das Format eine Zeichenfolge sein. Verfügbare Attribute stehen unter LogRecord-Attribute . Beim Protokolltyp json kann das Format neben einer Zeichenfolge auch eine Liste sein. Jeder Listeneintrag sollte einem LogRecord-Attribut entsprechen. Dabei wird nur der Feldname benötigt; %( und ) sollten weggelassen werden. Um ein Protokollfeld unter einem anderen Schlüsselnamen auszugeben, ein Dictionary verwenden: Der Schlüssel bezeichnet das Protokollfeld, der Wert den im Protokoll auszugebenden Feldnamen. Standardwert: %(asctime)s %(levelname)s: %(message)s
• dateformat: legt die Formatzeichenfolge für Datum und Uhrzeit fest (siehe Dokumentation zu formatTime() ).
• static_fields: fügt dem Protokoll zusätzliche Felder hinzu. Diese Option ist nur verfügbar, wenn der Protokolltyp auf json gesetzt ist.
• max_queue_size: Patroni verwendet eine zweistufige Protokollierung. Protokolleinträge werden in eine Warteschlange im Arbeitsspeicher geschrieben; ein separater Thread entnimmt sie und schreibt sie nach stderr oder in eine Datei. Die interne Warteschlange ist standardmäßig auf 1000 Einträge begrenzt, was für die Protokolle der letzten 1h20m ausreicht.
• dir: Verzeichnis für die Anwendungsprotokolle. Es muss existieren und für den Benutzer, der Patroni ausführt, beschreibbar sein. Ist dieser Wert gesetzt, bewahrt die Anwendung standardmäßig 4 Protokolldateien mit jeweils 25MB auf. Diese Aufbewahrungswerte lassen sich mit file_num und file_size anpassen (siehe unten).
• mode: Berechtigungen für Protokolldateien (z. B. 0644). Ohne Angabe werden die Berechtigungen anhand des aktuellen umask-Werts gesetzt.
• file_num: Anzahl der aufzubewahrenden Anwendungsprotokolle.
• file_size: Größe der Datei patroni.log (in Bytes), bei der eine Protokollrotation ausgelöst wird.
• loggers: dieser Abschnitt ermöglicht das Neufestlegen der Protokollierungsstufe je Python-Modul
  • patroni.postmaster: WARNING
  • urllib3: DEBUG
• deduplicate_heartbeat_logs: bei true werden aufeinanderfolgende identische Heartbeat-Protokolleinträge nicht ausgegeben. Standardwert: false.

Das folgende Beispiel konfiguriert Patroni für die Protokollierung im JSON-Format.

log:
   type: json
   format:
      - message
      - module
      - asctime: '@timestamp'
      - levelname: level
   static_fields:
      app: patroni

Bootstrap-Konfiguration

• bootstrap:

  • dcs: dieser Abschnitt wird nach der Initialisierung des neuen Clusters in /<namespace>/<scope>/config des angegebenen Konfigurationsspeichers geschrieben. Er enthält die globale dynamische Konfiguration des Clusters. Unter bootstrap.dcs können alle unter Dynamische Konfigurationseinstellungen beschriebenen Parameter angegeben werden. Nachdem Patroni den neuen Cluster initialisiert hat (Bootstrap), schreibt es diesen Abschnitt in /<namespace>/<scope>/config des Konfigurationsspeichers.

  • method: benutzerdefiniertes Skript zur Initialisierung dieses Clusters.

    Einzelheiten enthält die Dokumentation benutzerdefinierter Bootstrap-Methoden . Bei Angabe von initdb wird der standardmäßige Befehl initdb verwendet. initdb wird auch aufgerufen, wenn die Konfigurationsdatei keinen Parameter method enthält.

  • initdb: (optional) Liste der an initdb zu übergebenden Optionen.

    • - data-checksums: muss aktiviert sein, wenn pg_rewind unter 9.3 benötigt wird.
    • - encoding: UTF8: Standardzeichencodierung für neue Datenbanken.
    • - locale: UTF8: Standard-Locale für neue Datenbanken.

  • post_bootstrap oder post_init: Zusätzliches Skript, das nach der Initialisierung des Clusters ausgeführt wird. Es erhält eine Verbindungs-URL (mit dem Cluster-Superuser als Benutzername). Die Variable PGPASSFILE wird auf den Pfad der pgpass-Datei gesetzt.

Citus

Aktiviert die Integration von Patroni mit Citus . Ist sie konfiguriert, übernimmt Patroni die Registrierung der Citus-Worker-Knoten beim Coordinator. Weitere Informationen zur Citus-Unterstützung stehen hier .

• group: Citus-Gruppen-ID als Ganzzahl. Für den Coordinator 0 verwenden, für Worker 1, 2 usw.
• database: Datenbank, in der die Erweiterung citus erstellt werden sollte. Sie muss auf dem Coordinator und allen Workern identisch sein. Derzeit wird nur eine Datenbank unterstützt.

Consul

Die meisten Parameter sind optional, aber host oder url muss angegeben werden.

• host: host:port des lokalen Consul-Agenten.
• url: URL des lokalen Consul-Agenten im Format: http(s)://host:port
• port: (optional) Consul-Port
• scheme: (optional) http oder https, Standardwert http
• token: (optional) ACL-Token
• verify: (optional) bestimmt, ob das SSL-Zertifikat bei HTTPS-Anfragen geprüft wird
• cacert: (optional) CA-Zertifikat. Falls vorhanden, wird die Validierung aktiviert.
• cert: (optional) Datei mit dem Clientzertifikat
• key: (optional) Datei mit dem Clientschlüssel. Kann leer sein, wenn der Schlüssel Bestandteil von cert ist.
• dc: (optional) Rechenzentrum, mit dem kommuniziert werden soll. Standardmäßig wird das Rechenzentrum des Hosts verwendet.
• consistency: (optional) wählt den Konsistenzmodus von Consul. Mögliche Werte: default, consistent oder stale (Einzelheiten in der Consul-API-Referenz )
• checks: (optional) Liste der für die Sitzung verwendeten Consul Health Checks. Standardmäßig wird eine leere Liste verwendet.
• register_service: (optional) bestimmt, ob ein Dienst registriert wird, dessen Name durch den Parameter scope festgelegt ist und der je nach Knotenrolle das Tag master, primary, replica oder standby-leader erhält. Standardwert false
• service_tags: (optional) zusätzliche statische Tags für den Consul-Dienst neben der Rolle (primary/replica/standby-leader). Standardmäßig wird eine leere Liste verwendet.
• service_check_interval: (optional) Häufigkeit der Health Checks für die registrierte URL. Standardwert: ‘5s’.
• service_check_tls_server_name: (optional) überschreibt den SNI-Host bei TLS-Verbindungen; siehe auch die API-Referenz für Consul-Agent-Prüfungen .

token benötigt folgende ACL-Berechtigungen:

service_prefix "${scope}" {
    policy = "write"
}
key_prefix "${namespace}/${scope}" {
    policy = "write"
}
session_prefix "" {
    policy = "write"
}

etcd

Die meisten Parameter sind optional, aber einer der Parameter host, hosts, url, proxy oder srv muss angegeben werden.

• host: host:port des etcd-Endpunkts.
• hosts: Liste der etcd-Endpunkte im Format host1:port1,host2:port2,etc… Möglich sind eine durch Kommas getrennte Zeichenfolge oder eine YAML-Liste.
• use_proxies: ist dieser Parameter auf true gesetzt, behandelt Patroni hosts als Liste von Proxys und ermittelt nicht die Topologie des etcd-Clusters.
• url: URL für etcd.
• proxy: Proxy-URL für etcd. Bei einer Verbindung zu etcd über einen Proxy diesen Parameter anstelle von url verwenden.
• srv: Domain, in der nach SRV-Einträgen für die automatische Clustererkennung gesucht wird. Patroni fragt für die angegebene Domain diese SRV-Dienstnamen ab (in dieser Reihenfolge bis zum ersten Erfolg): _etcd-client-ssl, _etcd-client, _etcd-ssl, _etcd, _etcd-server-ssl, _etcd-server. Werden SRV-Einträge für _etcd-server-ssl oder _etcd-server gefunden, wird über das ETCD-Peer-Protokoll bei ETCD nach verfügbaren Mitgliedern gefragt. Andernfalls werden die Hosts aus den SRV-Einträgen verwendet.
• srv_suffix: konfiguriert ein Suffix für den bei der Erkennung abgefragten SRV-Namen. Mit diesem Flag lassen sich mehrere etcd-Cluster unter derselben Domain unterscheiden. Es funktioniert nur zusammen mit srv. Sind beispielsweise srv_suffix: foo und srv: example.org gesetzt, wird folgende DNS-SRV-Abfrage ausgeführt: _etcd-client-ssl-foo._tcp.example.org (entsprechend für jeden möglichen ETCD-SRV-Dienstnamen).
• protocol: (optional) http oder https; ohne Angabe wird http verwendet. Ist url oder proxy angegeben, wird das Protokoll daraus übernommen.
• username: (optional) Benutzername für die etcd-Authentifizierung.
• password: (optional) Passwort für die etcd-Authentifizierung.
• cacert: (optional) CA-Zertifikat. Falls vorhanden, wird die Validierung aktiviert.
• cert: (optional) Datei mit dem Clientzertifikat
• key: (optional) Datei mit dem Clientschlüssel. Kann leer sein, wenn der Schlüssel Bestandteil von cert ist.

Etcdv3

Damit Patroni mit dem etcd-Cluster über Protokollversion 3 arbeitet, muss in der Patroni-Konfigurationsdatei der Abschnitt etcd3 verwendet werden. Alle Konfigurationsparameter entsprechen denen für etcd.

ZooKeeper

• hosts: Liste der ZooKeeper-Clustermitglieder im Format: $$'host1:port1', 'host2:port2', 'etc...'$$.
• use_ssl: (optional) bestimmt, ob SSL verwendet wird. Standardwert: false. Bei false werden alle SSL-spezifischen Parameter ignoriert.
• cacert: (optional) CA-Zertifikat. Falls vorhanden, wird die Validierung aktiviert.
• cert: (optional) Datei mit dem Clientzertifikat.
• key: (optional) Datei mit dem Clientschlüssel.
• key_password: (optional) Passwort für den Clientschlüssel.
• verify: (optional) bestimmt, ob das Zertifikat geprüft wird. Standardwert: true.
• set_acls: (optional) falls gesetzt, wird Kazoo so konfiguriert, dass es auf jeden neu erstellten ZNode eine Standard-ACL anwendet. ACLs können das Schema x509 (Standard) oder andere unterstützte ZooKeeper-Schemata wie digest verwenden. Sie sollten als Dictionary angegeben werden, dessen Schlüssel der vollständige Principal (optional mit vorangestelltem Schema) und dessen Wert eine Liste von Berechtigungen ist. Als Berechtigungen sind eine oder mehrere aus CREATE, READ, WRITE, DELETE, ADMIN oder ALL möglich. Beispiel: set_acls: {CN=principal1: [CREATE, READ], digest:principal2:+pjROuBuuwNNSujKyH8dGcEnFPQ=: [ALL]}.
• auth_data: (optional) Zugangsdaten für die Verbindung. Sollte ein Dictionary mit scheme als Schlüssel und credential als Wert sein. Standardwert ist ein leeres Dictionary.

Exhibitor

• hosts: anfängliche Liste der Exhibitor-Knoten (ZooKeeper) im Format: ‘host1,host2,etc…’. Diese Liste wird bei jeder Änderung der Topologie des Exhibitor-Clusters (ZooKeeper) automatisch aktualisiert.
• poll_interval: Häufigkeit, mit der die Liste der ZooKeeper- und Exhibitor-Knoten von Exhibitor aktualisiert werden sollte.
• port: Exhibitor-Port.

Kubernetes

• bypass_api_service: (optional) bei der Kommunikation mit der Kubernetes API verwendet Patroni normalerweise den Dienst kubernetes , dessen Adresse den Pods über die Umgebungsvariable KUBERNETES_SERVICE_HOST bereitgestellt wird. Ist bypass_api_service auf true gesetzt, ermittelt Patroni die Liste der API-Knoten hinter dem Dienst und verbindet sich direkt mit ihnen.
• namespace: (optional) Kubernetes-Namespace, in dem der Patroni-Pod läuft. Standardwert: default.
• labels: Labels im Format {label1: value1, label2: value2}. Mit diesen Labels werden vorhandene Objekte (Pods sowie Endpoints oder ConfigMaps) gesucht, die zum aktuellen Cluster gehören. Außerdem setzt Patroni sie auf jedem von ihm erstellten Objekt (Endpoint oder ConfigMap).
• scope_label: (optional) Name des Labels mit dem Clusternamen. Standardwert: cluster-name.
• bootstrap_labels: (optional) Labels im Format {label1: value1, label2: value2}. Sie werden einem Patroni-Pod zugewiesen, wenn sein Zustand initializing new cluster, running custom bootstrap script, starting after custom bootstrap oder creating replica ist.
• role_label: (optional) Name des Labels mit der Rolle (primary, replica oder ein anderer benutzerdefinierter Wert). Patroni setzt dieses Label auf dem Pod, in dem es läuft. Standardwert: role.
• leader_label_value: (optional) Wert des Pod-Labels, wenn die Postgres-Rolle primary ist. Standardwert: primary.
• follower_label_value: (optional) Wert des Pod-Labels, wenn die Postgres-Rolle replica ist. Standardwert: replica.
• standby_leader_label_value: (optional) Wert des Pod-Labels, wenn die Postgres-Rolle standby_leader ist. Standardwert: primary.
• tmp_role_label: (optional) Name des temporären Labels mit der Rolle (primary oder replica). Der Wert dieses Labels entspricht immer dem Standardwert der jeweiligen Rolle. Nur bei Bedarf setzen.
• use_endpoints: (optional) bei true verwendet Patroni Endpoints anstelle von ConfigMaps für die Leader-Wahl und zum Speichern des Clusterzustands.
• pod_ip: (optional) IP-Adresse des Pods, in dem Patroni läuft. Dieser Wert ist erforderlich, wenn use_endpoints aktiviert ist, und wird beim Hochstufen von PostgreSQL im Pod zum Befüllen der Subsets des Leader-Endpoints verwendet.
• ports: (optional) enthält das Service-Objekt einen Namen für den Port, muss derselbe Name im Endpoint-Objekt erscheinen; andernfalls funktioniert der Dienst nicht. Ist der Dienst beispielsweise als {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}} definiert, muss kubernetes.ports: [{"name": "postgresql", "port": 5432}] gesetzt werden. Patroni verwendet dies zum Aktualisieren der Subsets des Leader-Endpoints. Dieser Parameter wird nur verwendet, wenn kubernetes.use_endpoints gesetzt ist.
• cacert: (optional) gibt die CA_BUNDLE-Datei mit den Zertifikaten vertrauenswürdiger CAs an, die zum Prüfen der SSL-Zertifikate der Kubernetes API verwendet werden. Ohne Angabe verwendet Patroni den Wert aus dem ServiceAccount-Secret.
• retriable_http_codes: (optional) Liste der HTTP-Statuscodes der K8s API, bei denen ein erneuter Versuch erfolgt. Standardmäßig wiederholt Patroni die Anfrage bei 500, 503 und 504 oder wenn die Antwort der K8s API den HTTP-Header retry-after enthält.

Raft (veraltet)

• self_addr: ip:port, an dem auf Raft-Verbindungen gewartet wird. self_addr muss von anderen Clusterknoten aus erreichbar sein. Ohne Angabe nimmt der Knoten nicht am Konsens teil.

• bind_addr: (optional) ip:port, an dem auf Raft-Verbindungen gewartet wird. Ohne Angabe wird self_addr verwendet.

• partner_addrs: Liste der anderen Patroni-Knoten im Cluster im Format:

  $$'ip1:port', 'ip2:port', 'etc...'$$

• data_dir: Verzeichnis zum Speichern des Raft-Logs und des Snapshots. Ohne Angabe wird das aktuelle Arbeitsverzeichnis verwendet.

• password: (optional) verschlüsselt den Raft-Datenverkehr mit dem angegebenen Passwort; erfordert das Python-Modul cryptography.

• min_timeout: (optional) minimale Zeitüberschreitung für Wahlen in der zugrunde liegenden Raft-Implementierung pysyncobj, in Sekunden. Muss größer als 3 * append_entries_period sein. Standardwert: 0.4.

• max_timeout: (optional) maximale Zeitüberschreitung für Wahlen in der zugrunde liegenden Raft-Implementierung pysyncobj, in Sekunden. Muss größer als min_timeout sein. Standardwert: 1.4.

• connection_timeout: (optional) Zeit in Sekunden, nach der eine Verbindung ohne Datenempfang als unterbrochen gilt. Muss größer oder gleich max_timeout sein. Standardwert: 3.5.

• append_entries_period: (optional) Intervall in Sekunden zum Senden von Heartbeat-Befehlen (append_entries). Muss kleiner als ein Drittel von min_timeout sein. Standardwert: 0.1.

• connection_retry_time: (optional) Intervall in Sekunden zwischen erneuten Verbindungsversuchen zu nicht erreichbaren Knoten. Standardwert: 5.0.

• leader_fallback_timeout: (optional) Zeit in Sekunden, nach der ein Leader ohne Antwort von der Mehrheit in den Follower-Zustand zurückkehrt. Muss größer als append_entries_period sein. Standardwert: 30.0.

Kurze FAQ zur Raft-Implementierung

• F: Wie lassen sich alle am Konsens beteiligten Knoten auflisten?

  A: syncobj_admin -conn host:port -status, wobei host:port die Adresse eines Clusterknotens ist.

• F: Ein am Konsens beteiligter Knoten ist ausgefallen, und seine IP-Adresse kann nicht für einen anderen Knoten wiederverwendet werden. Wie lässt sich dieser Knoten aus dem Konsens entfernen?

  A: syncobj_admin -conn host:port -remove host2:port2, wobei host2:port2 die Adresse des Knotens ist, der aus dem Konsens entfernt werden soll.

• F: Woher bekommt man das Werkzeug syncobj_admin?

  A: Es wird zusammen mit dem Modul pysyncobj (RAFT-Implementierung in Python) installiert, von dem Patroni abhängt.

• F: Kann ein Patroni-Knoten betrieben werden, ohne ihn in den Konsens aufzunehmen?

  A: Ja, dazu raft.self_addr in der Patroni-Konfiguration auskommentieren oder entfernen.

• F: Können Patroni und PostgreSQL auf nur zwei Knoten betrieben werden?

  A: Ja, auf dem dritten Knoten kann patroni_raft_controller laufen (ohne Patroni und PostgreSQL). Bei dieser Konfiguration kann ein Knoten vorübergehend ausfallen, ohne den Primärserver zu beeinträchtigen.

PostgreSQL

• postgresql:

  • authentication:

    • superuser:
      • username: Name des Superusers, der bei der Initialisierung (initdb) festgelegt und später von Patroni für Verbindungen zu Postgres verwendet wird.
      • password: Passwort des Superusers, das bei der Initialisierung (initdb) festgelegt wird.
      • sslmode: (optional) entspricht dem Verbindungsparameter sslmode , der dem Client die Auswahl des Modus für die TLS-Aushandlung mit dem Server erlaubt. Einzelheiten zur Funktionsweise der einzelnen Modi stehen in der PostgreSQL-Dokumentation . Der Standardmodus ist prefer.
      • sslkey: (optional) entspricht dem Verbindungsparameter sslkey , der den Speicherort des geheimen Schlüssels für das Clientzertifikat angibt.
      • sslpassword: (optional) entspricht dem Verbindungsparameter sslpassword , der das Passwort für den in sslkey angegebenen geheimen Schlüssel festlegt.
      • sslcert: (optional) entspricht dem Verbindungsparameter sslcert , der den Speicherort des Clientzertifikats angibt.
      • sslrootcert: (optional) entspricht dem Verbindungsparameter sslrootcert , der den Pfad zu einer Datei mit einem oder mehreren Zertifikaten von Zertifizierungsstellen (CA) angibt, mit denen der Client ein Serverzertifikat prüft.
      • sslcrl: (optional) entspricht dem Verbindungsparameter sslcrl , der den Pfad zu einer Datei mit einer Zertifikatsperrliste angibt. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
      • sslcrldir: (optional) entspricht dem Verbindungsparameter sslcrldir , der den Pfad zu einem Verzeichnis mit Dateien angibt, die eine Zertifikatsperrliste enthalten. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
      • sslnegotiation: (optional) entspricht dem Verbindungsparameter sslnegotiation , der steuert, wie die SSL-Verschlüsselung mit dem Server ausgehandelt wird, falls SSL verwendet wird.
      • gssencmode: (optional) entspricht dem Verbindungsparameter gssencmode , der bestimmt, ob und mit welcher Priorität eine sichere GSS-Verbindung über TCP/IP mit dem Server ausgehandelt wird.
      • channel_binding: (optional) entspricht dem Verbindungsparameter channel_binding , der die Verwendung von Channel Binding durch den Client steuert.
    • replication:
      • username: Benutzername für die Replikation; der Benutzer wird bei der Initialisierung erstellt. Replikate verwenden ihn, um per Streaming-Replikation auf die Replikationsquelle zuzugreifen.
      • password: Passwort für die Replikation; der Benutzer wird bei der Initialisierung erstellt.
      • sslmode: (optional) entspricht dem Verbindungsparameter sslmode , der dem Client die Auswahl des Modus für die TLS-Aushandlung mit dem Server erlaubt. Einzelheiten zur Funktionsweise der einzelnen Modi stehen in der PostgreSQL-Dokumentation . Der Standardmodus ist prefer.
      • sslkey: (optional) entspricht dem Verbindungsparameter sslkey , der den Speicherort des geheimen Schlüssels für das Clientzertifikat angibt.
      • sslpassword: (optional) entspricht dem Verbindungsparameter sslpassword , der das Passwort für den in sslkey angegebenen geheimen Schlüssel festlegt.
      • sslcert: (optional) entspricht dem Verbindungsparameter sslcert , der den Speicherort des Clientzertifikats angibt.
      • sslrootcert: (optional) entspricht dem Verbindungsparameter sslrootcert , der den Pfad zu einer Datei mit einem oder mehreren Zertifikaten von Zertifizierungsstellen (CA) angibt, mit denen der Client ein Serverzertifikat prüft.
      • sslcrl: (optional) entspricht dem Verbindungsparameter sslcrl , der den Pfad zu einer Datei mit einer Zertifikatsperrliste angibt. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
      • sslcrldir: (optional) entspricht dem Verbindungsparameter sslcrldir , der den Pfad zu einem Verzeichnis mit Dateien angibt, die eine Zertifikatsperrliste enthalten. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
      • sslnegotiation: (optional) entspricht dem Verbindungsparameter sslnegotiation , der steuert, wie die SSL-Verschlüsselung mit dem Server ausgehandelt wird, falls SSL verwendet wird.
      • gssencmode: (optional) entspricht dem Verbindungsparameter gssencmode , der bestimmt, ob und mit welcher Priorität eine sichere GSS-Verbindung über TCP/IP mit dem Server ausgehandelt wird.
      • channel_binding: (optional) entspricht dem Verbindungsparameter channel_binding , der die Verwendung von Channel Binding durch den Client steuert.
    • rewind:
      • username: (optional) Name des Benutzers für pg_rewind; er wird bei der Initialisierung von Postgres 11+ erstellt und erhält alle erforderlichen Berechtigungen .
      • password: (optional) Passwort des Benutzers für pg_rewind; er wird bei der Initialisierung erstellt.
      • sslmode: (optional) entspricht dem Verbindungsparameter sslmode , der dem Client die Auswahl des Modus für die TLS-Aushandlung mit dem Server erlaubt. Einzelheiten zur Funktionsweise der einzelnen Modi stehen in der PostgreSQL-Dokumentation . Der Standardmodus ist prefer.
      • sslkey: (optional) entspricht dem Verbindungsparameter sslkey , der den Speicherort des geheimen Schlüssels für das Clientzertifikat angibt.
      • sslpassword: (optional) entspricht dem Verbindungsparameter sslpassword , der das Passwort für den in sslkey angegebenen geheimen Schlüssel festlegt.
      • sslcert: (optional) entspricht dem Verbindungsparameter sslcert , der den Speicherort des Clientzertifikats angibt.
      • sslrootcert: (optional) entspricht dem Verbindungsparameter sslrootcert , der den Pfad zu einer Datei mit einem oder mehreren Zertifikaten von Zertifizierungsstellen (CA) angibt, mit denen der Client ein Serverzertifikat prüft.
      • sslcrl: (optional) entspricht dem Verbindungsparameter sslcrl , der den Pfad zu einer Datei mit einer Zertifikatsperrliste angibt. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
      • sslcrldir: (optional) entspricht dem Verbindungsparameter sslcrldir , der den Pfad zu einem Verzeichnis mit Dateien angibt, die eine Zertifikatsperrliste enthalten. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
      • sslnegotiation: (optional) entspricht dem Verbindungsparameter sslnegotiation , der steuert, wie die SSL-Verschlüsselung mit dem Server ausgehandelt wird, falls SSL verwendet wird.
      • gssencmode: (optional) entspricht dem Verbindungsparameter gssencmode , der bestimmt, ob und mit welcher Priorität eine sichere GSS-Verbindung über TCP/IP mit dem Server ausgehandelt wird.
      • channel_binding: (optional) entspricht dem Verbindungsparameter channel_binding , der die Verwendung von Channel Binding durch den Client steuert.

  • callbacks: Callback-Skripte, die bei bestimmten Aktionen ausgeführt werden. Patroni übergibt Aktion, Rolle und Clusternamen. (scripts/aws.py zeigt ein Beispiel für solche Skripte.)

    • on_reload: führt dieses Skript aus, wenn das Neuladen der Konfiguration ausgelöst wird.
    • on_restart: führt dieses Skript aus, wenn Postgres neu startet (ohne Rollenwechsel).
    • on_role_change: führt dieses Skript aus, wenn Postgres hoch- oder herabgestuft wird.
    • on_start: führt dieses Skript aus, wenn Postgres startet.
    • on_stop: führt dieses Skript aus, wenn Postgres stoppt.

  • connect_address: IP-Adresse + Port, über die Postgres für andere Knoten und Anwendungen erreichbar ist.

  • proxy_address: IP-Adresse + Port, über die ein neben Postgres laufender Verbindungspool (z. B. PgBouncer) erreichbar ist. Der Wert wird als proxy_url in den Mitgliedsschlüssel im DCS geschrieben und kann für die Diensterkennung verwendet werden beziehungsweise nützlich sein.

  • create_replica_methods: geordnete Liste der Erstellungsmethoden, mit denen ein Patroni-Knoten zu einem neuen Replikat wird. Die Standardmethode ist “basebackup”; andere Methoden verweisen auf Skripte, die jeweils mit einem eigenen Konfigurationseintrag konfiguriert werden. Weitere Erläuterungen enthält die Dokumentation benutzerdefinierter Methoden zur Replikaterstellung .

  • data_dir: Pfad zum Postgres-Datenverzeichnis, das bereits existiert oder von Patroni initialisiert werden soll.

  • config_dir: Pfad zum Postgres-Konfigurationsverzeichnis; standardmäßig das Datenverzeichnis. Es muss für Patroni beschreibbar sein.

  • bin_dir: (optional) Pfad zu den PostgreSQL-Programmdateien (pg_ctl, initdb, pg_controldata, pg_basebackup, postgres, pg_isready, pg_rewind). Ohne Angabe oder bei einer leeren Zeichenfolge werden die Programme über die Umgebungsvariable PATH gesucht.

  • bin_name: (optional) ermöglicht das Überschreiben der Postgres-Programmnamen bei einer benutzerdefinierten Postgres-Distribution:

    • pg_ctl: (optional) benutzerdefinierter Name für die Programmdatei pg_ctl.
    • initdb: (optional) benutzerdefinierter Name für die Programmdatei initdb.
    • pg_controldata: (optional) benutzerdefinierter Name für die Programmdatei pg_controldata.
    • pg_basebackup: (optional) benutzerdefinierter Name für die Programmdatei pg_basebackup.
    • postgres: (optional) benutzerdefinierter Name für die Programmdatei postgres.
    • pg_isready: (optional) benutzerdefinierter Name für die Programmdatei pg_isready.
    • pg_rewind: (optional) benutzerdefinierter Name für die Programmdatei pg_rewind.

  • listen: IP-Adresse + Port, an denen Postgres auf Verbindungen wartet; bei Streaming-Replikation müssen sie von anderen Clusterknoten aus erreichbar sein. Mehrere durch Kommas getrennte Adressen sind zulässig, sofern der Port nach der letzten Adresse mit einem Doppelpunkt angehängt wird, etwa listen: 127.0.0.1,127.0.0.2:5432. Patroni verwendet die erste Adresse dieser Liste, um lokale Verbindungen zum PostgreSQL-Knoten aufzubauen.

  • use_unix_socket: legt fest, dass Patroni für die Verbindung zum Cluster bevorzugt Unix-Sockets verwenden sollte. Standardwert: false. Ist unix_socket_directories definiert, verwendet Patroni daraus den ersten geeigneten Wert für die Verbindung zum Cluster und greift auf TCP zurück, wenn kein Wert geeignet ist. Ist unix_socket_directories nicht in postgresql.parameters angegeben, nimmt Patroni an, dass der Standardwert verwendet werden sollte, und lässt host in den Verbindungsparametern weg.

  • use_unix_socket_repl: legt fest, dass Patroni für die Clusterverbindung des Replikationsbenutzers bevorzugt Unix-Sockets verwenden sollte. Standardwert: false. Ist unix_socket_directories definiert, verwendet Patroni daraus den ersten geeigneten Wert für die Verbindung zum Cluster und greift auf TCP zurück, wenn kein Wert geeignet ist. Ist unix_socket_directories nicht in postgresql.parameters angegeben, nimmt Patroni an, dass der Standardwert verwendet werden sollte, und lässt host in den Verbindungsparametern weg.

  • pgpass: Pfad zur Passwortdatei .pgpass . Patroni erstellt diese Datei vor dem Ausführen von pg_basebackup, des Skripts post_init und in einigen weiteren Fällen. Der Speicherort muss für Patroni beschreibbar sein.

  • recovery_conf: zusätzliche Konfigurationseinstellungen, die beim Konfigurieren eines Followers in recovery.conf geschrieben werden.

  • custom_conf : Pfad zu einer optionalen benutzerdefinierten Datei postgresql.conf, die anstelle von postgresql.base.conf verwendet wird. Sie muss auf allen Clusterknoten existieren, für PostgreSQL lesbar sein und wird von ihrem Speicherort aus in die tatsächliche postgresql.conf eingebunden. Patroni überwacht diese Datei weder auf Änderungen noch erstellt es ein Backup davon. Ihre Einstellungen können dennoch durch Patronis eigene Konfigurationsmöglichkeiten überschrieben werden; Einzelheiten stehen unter Dynamische Konfiguration .

  • parameters: Konfigurationsparameter (GUCs) für Postgres im Format {ssl: "on", ssl_cert_file: "cert_file"}.

  • parameters_primary: (optional) rollenspezifische Parameterüberschreibungen für primary. Diese Werte werden mit den grundlegenden parameters zusammengeführt und überschreiben sie.

  • parameters_replica: (optional) rollenspezifische Parameterüberschreibungen für replica. Diese Werte werden mit den grundlegenden parameters zusammengeführt und überschreiben sie.

  • parameters_standby_leader: (optional) rollenspezifische Parameterüberschreibungen für standby_leader. Diese Werte werden mit den grundlegenden parameters zusammengeführt und überschreiben sie.

  • pg_hba: Liste der Zeilen, aus denen Patroni pg_hba.conf erzeugt. Patroni ignoriert diesen Parameter, wenn der PostgreSQL-Parameter hba_file auf einen anderen Wert als den Standardwert gesetzt ist. Zusammen mit der dynamischen Konfiguration vereinfacht dieser Parameter die Verwaltung von pg_hba.conf.

    • - host all all 0.0.0.0/0 md5
    • - host replication replicator 127.0.0.1/32 md5: Eine solche Zeile ist für die Replikation erforderlich.

  • pg_hba_primary: (optional) rollenspezifische pg_hba-Einträge für primary. Sie ersetzen pg_hba vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_hba verwendet.

  • pg_hba_replica: (optional) rollenspezifische pg_hba-Einträge für replica. Sie ersetzen pg_hba vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_hba verwendet.

  • pg_hba_standby_leader: (optional) rollenspezifische pg_hba-Einträge für standby_leader. Sie ersetzen pg_hba vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_hba verwendet.

  • pg_ident: Liste der Zeilen, aus denen Patroni pg_ident.conf erzeugt. Patroni ignoriert diesen Parameter, wenn der PostgreSQL-Parameter ident_file auf einen anderen Wert als den Standardwert gesetzt ist. Zusammen mit der dynamischen Konfiguration vereinfacht dieser Parameter die Verwaltung von pg_ident.conf.

    • - mapname1 systemname1 pguser1
    • - mapname1 systemname2 pguser2

  • pg_ident_primary: (optional) rollenspezifische pg_ident-Einträge für primary. Sie ersetzen pg_ident vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_ident verwendet.

  • pg_ident_replica: (optional) rollenspezifische pg_ident-Einträge für replica. Sie ersetzen pg_ident vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_ident verwendet.

  • pg_ident_standby_leader: (optional) rollenspezifische pg_ident-Einträge für standby_leader. Sie ersetzen pg_ident vollständig (keine Zusammenführung). Sind sie nicht definiert, wird pg_ident verwendet.

  • pg_ctl_timeout: Wartezeit für pg_ctl bei start, stop oder restart. Der Standardwert beträgt 60 Sekunden.

  • use_pg_rewind: versucht, pg_rewind auf dem bisherigen Leader zu verwenden, wenn er dem Cluster als Replikat beitritt. Der Cluster muss mit data page checksums (Option --data-checksums für initdb) initialisiert worden sein und/oder wal_log_hints muss auf on gesetzt sein, andernfalls funktioniert pg_rewind nicht.

  • rewind: (optional) benutzerdefinierte Optionen für den Befehl pg_rewind. Sie können als Liste von Zeichenfolgen und/oder Dictionaries mit jeweils einem Schlüssel-Wert-Paar angegeben werden. Zu den nicht zulässigen Optionen gehören: target-pgdata, source-pgdata, source-server, write-recovery-conf, dry-run, restore-target-wal, config-file, no-ensure-shutdown, version und help. Beispiel:

    postgresql:
      rewind:
        - debug
        - progress
        - sync-method: fsync

  • remove_data_directory_on_rewind_failure: ist diese Option aktiviert, entfernt Patroni das PostgreSQL-Datenverzeichnis und erstellt das Replikat neu. Andernfalls versucht es, dem neuen Leader zu folgen. Standardwert: false.

  • remove_data_directory_on_diverged_timelines: Patroni entfernt das PostgreSQL-Datenverzeichnis und erstellt das Replikat neu, wenn es auseinanderlaufende Timelines erkennt und der bisherige Primärserver nicht mit dem Streaming vom neuen Primärserver beginnen kann. Diese Option ist nützlich, wenn pg_rewind nicht verwendet werden kann. Beim Prüfen auf auseinanderlaufende Timelines unter PostgreSQL v10 und älter versucht Patroni, sich mit den Replikationszugangsdaten zur Datenbank “postgres” zu verbinden. Daher sollte dieser Zugriff in pg_hba.conf erlaubt sein. Standardwert: false.

  • replica_method: für jeden Eintrag in create_replica_methods außer basebackup wird ein gleichnamiger Konfigurationsabschnitt hinzugefügt. Er sollte mindestens “command” mit dem vollständigen Pfad zum auszuführenden Skript enthalten. Andere Konfigurationsparameter werden im Format “parameter=value” an das Skript übergeben.

  • pre_promote: Fencing-Skript, das während eines Failovers nach dem Erwerb der Leader-Sperre, aber vor dem Hochstufen des Replikats ausgeführt wird. Endet das Skript mit einem von null verschiedenen Code, stuft Patroni das Replikat nicht hoch und entfernt den Leader-Schlüssel aus dem DCS.

  • before_stop: Skript, das unmittelbar vor dem Stoppen von Postgres ausgeführt wird. Anders als ein Callback läuft dieses Skript synchron und blockiert das Herunterfahren bis zu seinem Abschluss. Sein Rückgabecode beeinflusst nicht, ob das Herunterfahren anschließend fortgesetzt wird.

REST API

• restapi:
  • thread_pool_size: Größe des Threadpools, mit dem Patroni REST-API-Anfragen verarbeitet. Mindestwert: 5, Standardwert: 5.
  • connect_address: IP-Adresse (oder Hostname) und Port für den Zugriff auf die REST API von Patroni. Alle Clustermitglieder müssen diese Adresse erreichen können. Sofern die Patroni-Installation nicht als lokale Demo gedacht ist, darf daher weder “localhost” noch eine Loopback-Adresse (also “localhost” oder “127.0.0.1”) verwendet werden. Die Adresse kann als Endpunkt für HTTP Health Checks (siehe unten den REST-API-Parameter “listen”), für Benutzerabfragen (direkt oder über die REST API) sowie für die Health Checks der Clustermitglieder während der Leader-Wahl dienen (etwa um festzustellen, ob der Leader noch läuft oder ob ein Knoten eine weiter fortgeschrittene WAL-Position hat als der abfragende Knoten). connect_address wird im Mitgliedsschlüssel im DCS gespeichert, sodass sich der Mitgliedsname in die Adresse für den Zugriff auf dessen REST API auflösen lässt.
  • listen: IP-Adresse (oder Hostname) und Port, an denen Patroni für die REST API auf Verbindungen wartet, um die oben beschriebenen Health Checks und die Kommunikation zwischen den beteiligten Clusterknoten bereitzustellen. Dient außerdem zum Bereitstellen von Health-Check-Informationen für HAProxy (oder jeden anderen Load-Balancer, der HTTP-Prüfungen mit “OPTIONS” oder “GET” ausführen kann).
  • authentication: (optional)
    • username: Benutzername für die Basic-Authentifizierung zum Schutz unsicherer REST-API-Endpunkte.
    • password: Passwort für die Basic-Authentifizierung zum Schutz unsicherer REST-API-Endpunkte.
  • certfile: (optional) gibt die Datei mit dem Zertifikat im PEM-Format an. Ist certfile nicht angegeben oder leer, arbeitet der API-Server ohne SSL.
  • keyfile: (optional) gibt die Datei mit dem geheimen Schlüssel im PEM-Format an.
  • keyfile_password: (optional) gibt ein Passwort zum Entschlüsseln der Schlüsseldatei an.
  • cafile: (optional) gibt die Datei mit dem CA_BUNDLE vertrauenswürdiger CA-Zertifikate an, die zum Prüfen der Clientzertifikate verwendet werden.
  • ciphers: (optional) gibt die zulässigen Cipher Suites an (z. B. “ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:!SSLv1:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1”)
  • verify_client: (optional) none (Standard), optional oder required. Bei none prüft die REST API keine Clientzertifikate. Bei required sind Clientzertifikate für alle REST-API-Aufrufe erforderlich. Bei optional sind sie für alle unsicheren REST-API-Endpunkte erforderlich. Bei required ist die Clientauthentifizierung erfolgreich, wenn die Prüfung der Zertifikatssignatur erfolgreich ist. Bei optional wird das Clientzertifikat nur bei Anfragen mit PUT, POST, PATCH und DELETE geprüft.
  • allowlist: (optional): legt die Hosts fest, die unsichere REST-API-Endpunkte aufrufen dürfen. Ein Eintrag kann ein Hostname, eine IP-Adresse oder eine Netzwerkadresse in CIDR-Schreibweise sein. Standardmäßig gilt allow all. Ist allowlist oder allowlist_include_members gesetzt, werden alle nicht enthaltenen Zugriffe abgelehnt.
  • allowlist_include_members: (optional): bei true dürfen andere im DCS registrierte Clustermitglieder auf unsichere REST-API-Endpunkte zugreifen (IP-Adresse oder Hostname werden aus api_url des Mitglieds übernommen). Vorsicht: Das Betriebssystem kann für ausgehende Verbindungen eine andere IP-Adresse verwenden.
  • http_extra_headers: (optional) HTTP-Header ermöglichen es dem REST-API-Server, zusätzliche Informationen mit einer HTTP-Antwort zu übertragen.
  • https_extra_headers: (optional) HTTPS-Header ermöglichen es dem REST-API-Server, bei aktiviertem TLS zusätzliche Informationen mit einer HTTP-Antwort zu übertragen. Die in http_extra_headers festgelegten Zusatzinformationen werden ebenfalls übertragen.
  • request_queue_size: (optional): legt die Größe der Anfragewarteschlange für den TCP-Socket der Patroni REST API fest. Ist die Warteschlange voll, erhalten weitere Anfragen den Fehler “Connection denied”. Der Standardwert ist 5.
  • server_tokens: (optional): konfiguriert den Wert des HTTP-Headers Server.
    • Minimal: Der Header enthält nur die Patroni-Version, etwa Patroni/4.0.0.
    • ProductOnly: Der Header enthält nur den Produktnamen, etwa Patroni.
    • Original (Standard): Der Header behält das ursprüngliche Verhalten bei und zeigt die Versionen von BaseHTTP und Python an, etwa BaseHTTP/0.6 Python/3.12.3.

Hier ein Beispiel für http_extra_headers und https_extra_headers:

restapi:
  listen: <listen>
  connect_address: <connect_address>
  authentication:
    username: <username>
    password: <password>
  http_extra_headers:
    'X-Frame-Options': 'SAMEORIGIN'
    'X-XSS-Protection': '1; mode=block'
    'X-Content-Type-Options': 'nosniff'
  cafile: <ca file>
  certfile: <cert>
  keyfile: <key>
  https_extra_headers:
    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains'

CTL

• ctl: (optional)
  • authentication:
    • username: Benutzername für die Basic-Authentifizierung beim Zugriff auf geschützte REST-API-Endpunkte. Ohne Angabe verwendet patronictl den Wert des REST-API-Parameters “username”.
    • password: Passwort für die Basic-Authentifizierung beim Zugriff auf geschützte REST-API-Endpunkte. Ohne Angabe verwendet patronictl den Wert des REST-API-Parameters “password”.
  • insecure: erlaubt Verbindungen zur REST API ohne Prüfung der SSL-Zertifikate.
  • cacert: gibt die CA_BUNDLE-Datei oder das Verzeichnis mit Zertifikaten vertrauenswürdiger CAs an, die zum Prüfen der SSL-Zertifikate der REST API verwendet werden. Ohne Angabe verwendet patronictl den Wert des REST-API-Parameters “cafile”.
  • certfile: gibt die Datei mit dem Clientzertifikat im PEM-Format an.
  • keyfile: gibt die Datei mit dem geheimen Clientschlüssel im PEM-Format an.
  • keyfile_password: gibt ein Passwort zum Entschlüsseln der Clientschlüsseldatei an.

Watchdog

• mode: off, automatic oder required. Bei off ist der Watchdog deaktiviert. Bei automatic wird er verwendet, falls verfügbar, andernfalls ignoriert. Bei required wird der Knoten nur dann Leader, wenn der Watchdog erfolgreich aktiviert werden kann.
• device: Pfad zum Watchdog-Gerät. Standardwert: /dev/watchdog.
• safety_margin: Sicherheitsabstand in Sekunden zwischen dem Auslösen des Watchdogs und dem Ablauf des Leader-Schlüssels.

Tags

• clonefrom: true oder false. Bei true bevorzugen andere Knoten möglicherweise diesen Knoten zur Initialisierung (als Quelle für pg_basebackup). Haben mehrere Knoten das Tag clonefrom auf true gesetzt, wird die Quelle für die Initialisierung zufällig ausgewählt. Standardwert: false.
• noloadbalance: true oder false. Bei true antwortet der Knoten auf den REST-API-Health-Check GET /replica mit HTTP-Statuscode 503 und wird dadurch von der Lastverteilung ausgeschlossen. Standardwert: false.
• replicatefrom: Name eines anderen Replikats, von dem repliziert werden soll. Dient zur Unterstützung kaskadierender Replikation.
• nosync: true oder false. Bei true wird der Knoten niemals als synchrones Replikat ausgewählt.
• sync_priority: Ganzzahl, die die Priorität dieses Knotens bei der Auswahl synchroner Replikate bestimmt, wenn synchronous_mode auf on gesetzt ist. Knoten mit höherer Priorität werden gegenüber solchen mit niedrigerer Priorität bevorzugt. Ist sync_priority 0 oder negativ, darf dieser Knoten nicht in den PostgreSQL-Parameter synchronous_standby_names aufgenommen werden (wie bei nosync: true). Beachten Sie, dass dieser Parameter die entgegengesetzte Bedeutung zum Wert sync_priority in der Sicht pg_stat_replication hat.
• nofailover: true oder false; steuert, ob dieser Knoten an der Leader-Wahl teilnehmen und Leader werden darf. Standardwert: false, das heißt, dieser Knoten darf_ an Leader-Wahlen teilnehmen.
• failover_priority: Ganzzahl, die die Priorität dieses Knotens bei einem Failover bestimmt. Knoten mit höherer Priorität werden gegenüber solchen mit niedrigerer Priorität bevorzugt, wenn sie dieselbe Menge WAL empfangen beziehungsweise wiedergegeben haben. Knoten mit höherer Empfangs-/Wiedergabe-LSN werden jedoch unabhängig von ihrer Priorität bevorzugt. Ist failover_priority 0 oder negativ, darf dieser Knoten weder an der Leader-Wahl teilnehmen noch Leader werden (wie bei nofailover: true). Bekannte Einschränkung: failover_priority funktioniert derzeit nicht mit Quorum-basierter synchroner Replikation .
• nostream: true oder false. Bei true verwendet der Knoten nicht das Replikationsprotokoll zum Streamen von WAL. Stattdessen nutzt er Archiv-Recovery (falls restore_command konfiguriert ist) und fragt pg_wal/pg_xlog regelmäßig ab. Dies deaktiviert außerdem das Kopieren und Synchronisieren permanenter logischer Replikationsslots auf dem Knoten selbst und allen seinen kaskadierenden Replikaten. Auf einem Primärserver hat dieses Tag keine Wirkung.

Neben diesen vordefinierten Tags können auch eigene hinzugefügt werden:

• key1: true
• key2: false
• key3: 1.4
• key4: "RandomString"

Tags sind in der REST API und in patronictl_list sichtbar. Mit diesen Tags lässt sich auch die Funktionsfähigkeit einer Instanz prüfen. Ist das Tag für eine Instanz nicht definiert oder stimmt sein Wert nicht mit dem abgefragten Wert überein, wird HTTP-Statuscode 503 zurückgegeben.

3.3 - Umgebungskonfiguration

Einige in der Patroni-Konfigurationsdatei definierte Parameter können über Systemumgebungsvariablen überschrieben werden. Dieses Dokument listet alle von Patroni verarbeiteten Umgebungsvariablen auf. Die über diese Variablen gesetzten Werte haben stets Vorrang vor den Werten in der Patroni-Konfigurationsdatei.

Global/Allgemein

• PATRONI_CONFIGURATION: die gesamte Patroni-Konfiguration kann über die Umgebungsvariable PATRONI_CONFIGURATION festgelegt werden. In diesem Fall werden alle anderen Umgebungsvariablen ignoriert!
• PATRONI_THREAD_POOL_SIZE: Größe des Threadpools, mit dem Patroni asynchrone Aufgaben ausführt und während der Leader-Wahl oder bei Failsafe-Prüfungen über die REST API mit anderen Mitgliedern kommuniziert. Mindestwert: 5, Standardwert: 5.
• PATRONI_THREAD_STACK_SIZE: legt die Stackgröße für von Patroni gestartete Threads fest. Der Wert muss an 64kB ausgerichtet sein. Mindestwert: 64kB, Standardwert (von Patroni gesetzt): 512kB.
• PATRONI_NAME: Name des Knotens, auf dem die aktuelle Patroni-Instanz läuft. Er muss im Cluster eindeutig sein.
• PATRONI_NAMESPACE: Pfad im Konfigurationsspeicher, unter dem Patroni Informationen über den Cluster speichert. Standardwert: “/service”
• PATRONI_SCOPE: Clustername
• PG_MALLOC_ARENA_MAX: benutzerdefinierter Wert für die Umgebungsvariable MALLOC_ARENA_MAX des Prozesses postmaster. Ist er nicht gesetzt, erbt postmaster den Wert von MALLOC_ARENA_MAX.

Protokollierung

• PATRONI_LOG_TYPE: legt das Protokollformat fest. Mögliche Werte sind plain und json. Für das Format json muss jsonlogger installiert sein. Der Standardwert ist plain.
• PATRONI_LOG_LEVEL: legt die allgemeine Protokollierungsstufe fest. Standardwert: INFO (siehe Dokumentation der Python-Protokollierung )
• PATRONI_LOG_TRACEBACK_LEVEL: legt die Stufe fest, auf der Tracebacks sichtbar sind. Standardwert: ERROR. Auf DEBUG setzen, wenn Tracebacks nur bei aktiviertem PATRONI_LOG_LEVEL=DEBUG sichtbar sein sollen.
• PATRONI_LOG_FORMAT: legt die Formatzeichenfolge für Protokolle fest. Beim Protokolltyp plain sollte das Format eine Zeichenfolge sein. Verfügbare Attribute stehen unter LogRecord-Attribute . Beim Protokolltyp json kann das Format neben einer Zeichenfolge auch eine Liste sein. Jeder Listeneintrag sollte einem LogRecord-Attribut entsprechen. Dabei wird nur der Feldname benötigt; %( und ) sollten weggelassen werden. Um ein Protokollfeld unter einem anderen Schlüsselnamen auszugeben, ein Dictionary verwenden: Der Schlüssel bezeichnet das Protokollfeld, der Wert den im Protokoll auszugebenden Feldnamen. Standardwert: %(asctime)s %(levelname)s: %(message)s
• PATRONI_LOG_DATEFORMAT: legt die Formatzeichenfolge für Datum und Uhrzeit fest (siehe Dokumentation zu formatTime() ).
• PATRONI_LOG_STATIC_FIELDS: fügt dem Protokoll zusätzliche Felder hinzu. Diese Option ist nur beim Protokolltyp json verfügbar. Beispiel: PATRONI_LOG_STATIC_FIELDS="{app: patroni}"
• PATRONI_LOG_MAX_QUEUE_SIZE: Patroni verwendet eine zweistufige Protokollierung. Protokolleinträge werden in eine Warteschlange im Arbeitsspeicher geschrieben; ein separater Thread entnimmt sie und schreibt sie nach stderr oder in eine Datei. Die interne Warteschlange ist standardmäßig auf 1000 Einträge begrenzt, was für die Protokolle der letzten 1h20m ausreicht.
• PATRONI_LOG_DIR: Verzeichnis für die Anwendungsprotokolle. Es muss existieren und für den Benutzer, der Patroni ausführt, beschreibbar sein. Ist diese Umgebungsvariable gesetzt, bewahrt die Anwendung standardmäßig 4 Protokolldateien mit jeweils 25MB auf. Diese Aufbewahrungswerte lassen sich mit PATRONI_LOG_FILE_NUM und PATRONI_LOG_FILE_SIZE anpassen (siehe unten).
• PATRONI_LOG_MODE: Berechtigungen für Protokolldateien (z. B. 0644). Ohne Angabe werden die Berechtigungen anhand des aktuellen umask-Werts gesetzt.
• PATRONI_LOG_FILE_NUM: Anzahl der aufzubewahrenden Anwendungsprotokolle.
• PATRONI_LOG_FILE_SIZE: Größe der Datei patroni.log (in Bytes), bei der eine Protokollrotation ausgelöst wird.
• PATRONI_LOG_LOGGERS: definiert die Protokollierungsstufe je Python-Modul neu. Beispiel: PATRONI_LOG_LOGGERS="{patroni.postmaster: WARNING, urllib3: DEBUG}"
• PATRONI_LOG_DEDUPLICATE_HEARTBEAT_LOGS: bei true werden aufeinanderfolgende identische Heartbeat-Protokolleinträge nicht ausgegeben. Standardwert: false.

Citus

Aktiviert die Integration von Patroni mit Citus . Ist sie konfiguriert, übernimmt Patroni die Registrierung der Citus-Worker-Knoten beim Coordinator. Weitere Informationen zur Citus-Unterstützung stehen hier .

• PATRONI_CITUS_GROUP: Citus-Gruppen-ID als Ganzzahl. Für den Coordinator 0 verwenden, für Worker 1, 2 usw.
• PATRONI_CITUS_DATABASE: Datenbank, in der die Erweiterung citus erstellt werden sollte. Sie muss auf dem Coordinator und allen Workern identisch sein. Derzeit wird nur eine Datenbank unterstützt.

Consul

• PATRONI_CONSUL_HOST: host:port des lokalen Consul-Agenten.
• PATRONI_CONSUL_URL: URL des lokalen Consul-Agenten im Format: http(s)://host:port
• PATRONI_CONSUL_PORT: (optional) Consul-Port
• PATRONI_CONSUL_SCHEME: (optional) http oder https, Standardwert http
• PATRONI_CONSUL_TOKEN: (optional) ACL-Token
• PATRONI_CONSUL_VERIFY: (optional) bestimmt, ob das SSL-Zertifikat bei HTTPS-Anfragen geprüft wird
• PATRONI_CONSUL_CACERT: (optional) CA-Zertifikat. Falls vorhanden, wird die Validierung aktiviert.
• PATRONI_CONSUL_CERT: (optional) Datei mit dem Clientzertifikat
• PATRONI_CONSUL_KEY: (optional) Datei mit dem Clientschlüssel. Kann leer sein, wenn der Schlüssel Bestandteil des Zertifikats ist.
• PATRONI_CONSUL_DC: (optional) Rechenzentrum, mit dem kommuniziert werden soll. Standardmäßig wird das Rechenzentrum des Hosts verwendet.
• PATRONI_CONSUL_CONSISTENCY: (optional) wählt den Konsistenzmodus von Consul. Mögliche Werte: default, consistent oder stale (Einzelheiten in der Consul-API-Referenz )
• PATRONI_CONSUL_CHECKS: (optional) Liste der für die Sitzung verwendeten Consul Health Checks. Standardmäßig wird eine leere Liste verwendet.
• PATRONI_CONSUL_REGISTER_SERVICE: (optional) bestimmt, ob ein Dienst registriert wird, dessen Name durch den Parameter scope festgelegt ist und der je nach Knotenrolle das Tag master, primary, replica oder standby-leader erhält. Standardwert false
• PATRONI_CONSUL_SERVICE_TAGS: (optional) zusätzliche statische Tags für den Consul-Dienst neben der Rolle (primary/replica/standby-leader). Standardmäßig wird eine leere Liste verwendet.
• PATRONI_CONSUL_SERVICE_CHECK_INTERVAL: (optional) Häufigkeit der Health Checks für die registrierte URL
• PATRONI_CONSUL_SERVICE_CHECK_TLS_SERVER_NAME: (optional) überschreibt den SNI-Host bei TLS-Verbindungen; siehe auch die API-Referenz für Consul-Agent-Prüfungen .

etcd

• PATRONI_ETCD_PROXY: Proxy-URL für etcd. Bei einer Verbindung zu etcd über einen Proxy diesen Parameter anstelle von PATRONI_ETCD_URL verwenden.
• PATRONI_ETCD_URL: URL für etcd im Format: http(s)://(username:password@)host:port
• PATRONI_ETCD_HOSTS: Liste der etcd-Endpunkte im Format ‘host1:port1’,‘host2:port2’,etc…
• PATRONI_ETCD_USE_PROXIES: ist dieser Parameter auf true gesetzt, behandelt Patroni hosts als Liste von Proxys und ermittelt nicht die Topologie des etcd-Clusters, sondern bleibt bei der festen Liste hosts.
• PATRONI_ETCD_PROTOCOL: http oder https; ohne Angabe wird http verwendet. Ist url oder proxy angegeben, wird das Protokoll daraus übernommen.
• PATRONI_ETCD_HOST: host:port des etcd-Endpunkts.
• PATRONI_ETCD_SRV: Domain, in der nach SRV-Einträgen für die automatische Clustererkennung gesucht wird. Patroni fragt für die angegebene Domain diese SRV-Dienstnamen ab (in dieser Reihenfolge bis zum ersten Erfolg): _etcd-client-ssl, _etcd-client, _etcd-ssl, _etcd, _etcd-server-ssl, _etcd-server. Werden SRV-Einträge für _etcd-server-ssl oder _etcd-server gefunden, wird über das ETCD-Peer-Protokoll bei ETCD nach verfügbaren Mitgliedern gefragt. Andernfalls werden die Hosts aus den SRV-Einträgen verwendet.
• PATRONI_ETCD_SRV_SUFFIX: konfiguriert ein Suffix für den bei der Erkennung abgefragten SRV-Namen. Mit diesem Flag lassen sich mehrere etcd-Cluster unter derselben Domain unterscheiden. Es funktioniert nur zusammen mit PATRONI_ETCD_SRV. Sind beispielsweise PATRONI_ETCD_SRV_SUFFIX=foo und PATRONI_ETCD_SRV=example.org gesetzt, wird folgende DNS-SRV-Abfrage ausgeführt: _etcd-client-ssl-foo._tcp.example.org (entsprechend für jeden möglichen ETCD-SRV-Dienstnamen).
• PATRONI_ETCD_USERNAME: Benutzername für die etcd-Authentifizierung.
• PATRONI_ETCD_PASSWORD: Passwort für die etcd-Authentifizierung.
• PATRONI_ETCD_CACERT: CA-Zertifikat. Falls vorhanden, wird die Validierung aktiviert.
• PATRONI_ETCD_CERT: Datei mit dem Clientzertifikat.
• PATRONI_ETCD_KEY: Datei mit dem Clientschlüssel. Kann leer sein, wenn der Schlüssel Bestandteil des Zertifikats ist.

Etcdv3

Die Namen der Umgebungsvariablen für Etcdv3 entsprechen denen für etcd; im Variablennamen muss lediglich ETCD durch ETCD3 ersetzt werden. Beispiele: PATRONI_ETCD3_HOST, PATRONI_ETCD3_CACERT usw.

ZooKeeper

• PATRONI_ZOOKEEPER_HOSTS: durch Kommas getrennte Liste der ZooKeeper-Clustermitglieder: “‘host1:port1’,‘host2:port2’,’etc…’”. Jeder einzelne Eintrag muss in Anführungszeichen stehen!
• PATRONI_ZOOKEEPER_USE_SSL: (optional) bestimmt, ob SSL verwendet wird. Standardwert: false. Bei false werden alle SSL-spezifischen Parameter ignoriert.
• PATRONI_ZOOKEEPER_CACERT: (optional) CA-Zertifikat. Falls vorhanden, wird die Validierung aktiviert.
• PATRONI_ZOOKEEPER_CERT: (optional) Datei mit dem Clientzertifikat.
• PATRONI_ZOOKEEPER_KEY: (optional) Datei mit dem Clientschlüssel.
• PATRONI_ZOOKEEPER_KEY_PASSWORD: (optional) Passwort für den Clientschlüssel.
• PATRONI_ZOOKEEPER_VERIFY: (optional) bestimmt, ob das Zertifikat geprüft wird. Standardwert: true.
• PATRONI_ZOOKEEPER_SET_ACLS: (optional) falls gesetzt, wird Kazoo so konfiguriert, dass es auf jeden neu erstellten ZNode eine Standard-ACL anwendet. ACLs können das Schema x509 (Standard) oder andere unterstützte ZooKeeper-Schemata wie digest verwenden. Sie sollten als Dictionary angegeben werden, dessen Schlüssel der vollständige Principal (optional mit vorangestelltem Schema) und dessen Wert eine Liste von Berechtigungen ist. Als Berechtigungen sind eine oder mehrere aus CREATE, READ, WRITE, DELETE, ADMIN oder ALL möglich. Beispiel: set_acls: {CN=principal1: [CREATE, READ], digest:principal2:+pjROuBuuwNNSujKyH8dGcEnFPQ=: [ALL]}.
• PATRONI_ZOOKEEPER_AUTH_DATA: (optional) Zugangsdaten für die Verbindung. Sollte ein Dictionary mit scheme als Schlüssel und credential als Wert sein. Standardwert ist ein leeres Dictionary.

Exhibitor

• PATRONI_EXHIBITOR_HOSTS: anfängliche Liste der Exhibitor-Knoten (ZooKeeper) im Format: ‘host1,host2,etc…’. Diese Liste wird bei jeder Änderung der Topologie des Exhibitor-Clusters (ZooKeeper) automatisch aktualisiert.
• PATRONI_EXHIBITOR_PORT: Exhibitor-Port.

Kubernetes

• PATRONI_KUBERNETES_BYPASS_API_SERVICE: (optional) bei der Kommunikation mit der Kubernetes API verwendet Patroni normalerweise den Dienst kubernetes , dessen Adresse den Pods über die Umgebungsvariable KUBERNETES_SERVICE_HOST bereitgestellt wird. Ist PATRONI_KUBERNETES_BYPASS_API_SERVICE auf true gesetzt, ermittelt Patroni die Liste der API-Knoten hinter dem Dienst und verbindet sich direkt mit ihnen.
• PATRONI_KUBERNETES_NAMESPACE: (optional) Kubernetes-Namespace, in dem der Patroni-Pod läuft. Standardwert: default.
• PATRONI_KUBERNETES_LABELS: Labels im Format {label1: value1, label2: value2}. Mit diesen Labels werden vorhandene Objekte (Pods sowie Endpoints oder ConfigMaps) gesucht, die zum aktuellen Cluster gehören. Außerdem setzt Patroni sie auf jedem von ihm erstellten Objekt (Endpoint oder ConfigMap).
• PATRONI_KUBERNETES_SCOPE_LABEL: (optional) Name des Labels mit dem Clusternamen. Standardwert: cluster-name.
• PATRONI_KUBERNETES_BOOTSTRAP_LABELS: (optional) Labels im Format {label1: value1, label2: value2}. Sie werden einem Patroni-Pod zugewiesen, wenn sein Zustand initializing new cluster, running custom bootstrap script, starting after custom bootstrap oder creating replica ist.
• PATRONI_KUBERNETES_ROLE_LABEL: (optional) Name des Labels mit der Rolle (primary, replica oder ein anderer benutzerdefinierter Wert). Patroni setzt dieses Label auf dem Pod, in dem es läuft. Standardwert: role.
• PATRONI_KUBERNETES_LEADER_LABEL_VALUE: (optional) Wert des Pod-Labels, wenn die Postgres-Rolle primary ist. Standardwert: primary.
• PATRONI_KUBERNETES_FOLLOWER_LABEL_VALUE: (optional) Wert des Pod-Labels, wenn die Postgres-Rolle replica ist. Standardwert: replica.
• PATRONI_KUBERNETES_STANDBY_LEADER_LABEL_VALUE: (optional) Wert des Pod-Labels, wenn die Postgres-Rolle standby_leader ist. Standardwert: primary.
• PATRONI_KUBERNETES_TMP_ROLE_LABEL: (optional) Name des temporären Labels mit der Rolle (primary oder replica). Der Wert dieses Labels entspricht immer dem Standardwert der jeweiligen Rolle. Nur bei Bedarf setzen.
• PATRONI_KUBERNETES_USE_ENDPOINTS: (optional) bei true verwendet Patroni Endpoints anstelle von ConfigMaps für die Leader-Wahl und zum Speichern des Clusterzustands.
• PATRONI_KUBERNETES_POD_IP: (optional) IP-Adresse des Pods, in dem Patroni läuft. Dieser Wert ist erforderlich, wenn PATRONI_KUBERNETES_USE_ENDPOINTS aktiviert ist, und wird beim Hochstufen von PostgreSQL im Pod zum Befüllen der Subsets des Leader-Endpoints verwendet.
• PATRONI_KUBERNETES_PORTS: (optional) enthält das Service-Objekt einen Namen für den Port, muss derselbe Name im Endpoint-Objekt erscheinen; andernfalls funktioniert der Dienst nicht. Ist der Dienst beispielsweise als {Kind: Service, spec: {ports: [{name: postgresql, port: 5432, targetPort: 5432}]}} definiert, muss PATRONI_KUBERNETES_PORTS='[{"name": "postgresql", "port": 5432}]' gesetzt werden. Patroni verwendet dies zum Aktualisieren der Subsets des Leader-Endpoints. Dieser Parameter wird nur verwendet, wenn PATRONI_KUBERNETES_USE_ENDPOINTS gesetzt ist.
• PATRONI_KUBERNETES_CACERT: (optional) gibt die CA_BUNDLE-Datei mit den Zertifikaten vertrauenswürdiger CAs an, die zum Prüfen der SSL-Zertifikate der Kubernetes API verwendet werden. Ohne Angabe verwendet Patroni den Wert aus dem ServiceAccount-Secret.
• PATRONI_RETRIABLE_HTTP_CODES: (optional) Liste der HTTP-Statuscodes der K8s API, bei denen ein erneuter Versuch erfolgt. Standardmäßig wiederholt Patroni die Anfrage bei 500, 503 und 504 oder wenn die Antwort der K8s API den HTTP-Header retry-after enthält.

Raft (veraltet)

• PATRONI_RAFT_SELF_ADDR: ip:port, an dem auf Raft-Verbindungen gewartet wird. self_addr muss von anderen Clusterknoten aus erreichbar sein. Ohne Angabe nimmt der Knoten nicht am Konsens teil.
• PATRONI_RAFT_BIND_ADDR: (optional) ip:port, an dem auf Raft-Verbindungen gewartet wird. Ohne Angabe wird self_addr verwendet.
• PATRONI_RAFT_PARTNER_ADDRS: Liste der anderen Patroni-Knoten im Cluster im Format "'ip1:port1','ip2:port2'". Jeder einzelne Eintrag muss in Anführungszeichen stehen!
• PATRONI_RAFT_DATA_DIR: Verzeichnis zum Speichern des Raft-Logs und des Snapshots. Ohne Angabe wird das aktuelle Arbeitsverzeichnis verwendet.
• PATRONI_RAFT_PASSWORD: (optional) verschlüsselt den Raft-Datenverkehr mit dem angegebenen Passwort; erfordert das Python-Modul cryptography.
• PATRONI_RAFT_MIN_TIMEOUT: (optional) minimale Zeitüberschreitung für Wahlen in der zugrunde liegenden Raft-Implementierung pysyncobj, in Sekunden. Muss größer als 3 * PATRONI_RAFT_APPEND_ENTRIES_PERIOD sein. Standardwert: 0.4.
• PATRONI_RAFT_MAX_TIMEOUT: (optional) maximale Zeitüberschreitung für Wahlen in der zugrunde liegenden Raft-Implementierung pysyncobj, in Sekunden. Muss größer als PATRONI_RAFT_MIN_TIMEOUT sein. Standardwert: 1.4.
• PATRONI_RAFT_CONNECTION_TIMEOUT: (optional) Zeit in Sekunden, nach der eine Verbindung ohne Datenempfang als unterbrochen gilt. Muss größer oder gleich PATRONI_RAFT_MAX_TIMEOUT sein. Standardwert: 3.5.
• PATRONI_RAFT_APPEND_ENTRIES_PERIOD: (optional) Intervall in Sekunden zum Senden von Heartbeat-Befehlen. Muss kleiner als ein Drittel von PATRONI_RAFT_MIN_TIMEOUT sein. Standardwert: 0.1.
• PATRONI_RAFT_CONNECTION_RETRY_TIME: (optional) Intervall in Sekunden zwischen erneuten Verbindungsversuchen zu nicht erreichbaren Knoten. Standardwert: 5.0.
• PATRONI_RAFT_LEADER_FALLBACK_TIMEOUT: (optional) Zeit in Sekunden, nach der ein Leader ohne Antwort von der Mehrheit in den Follower-Zustand zurückkehrt. Muss größer als PATRONI_RAFT_APPEND_ENTRIES_PERIOD sein. Standardwert: 30.0.

PostgreSQL

• PATRONI_POSTGRESQL_LISTEN: IP-Adresse + Port, an denen Postgres auf Verbindungen wartet. Mehrere durch Kommas getrennte Adressen sind zulässig, sofern der Port nach der letzten Adresse mit einem Doppelpunkt angehängt wird, etwa listen: 127.0.0.1,127.0.0.2:5432. Patroni verwendet die erste Adresse dieser Liste, um lokale Verbindungen zum PostgreSQL-Knoten aufzubauen.
• PATRONI_POSTGRESQL_CONNECT_ADDRESS: IP-Adresse + Port, über die Postgres für andere Knoten und Anwendungen erreichbar ist.
• PATRONI_POSTGRESQL_PROXY_ADDRESS: IP-Adresse + Port, über die ein neben Postgres laufender Verbindungspool (z. B. PgBouncer) erreichbar ist. Der Wert wird als proxy_url in den Mitgliedsschlüssel im DCS geschrieben und kann für die Diensterkennung verwendet werden beziehungsweise nützlich sein.
• PATRONI_POSTGRESQL_DATA_DIR: Pfad zum Postgres-Datenverzeichnis, das bereits existiert oder von Patroni initialisiert werden soll.
• PATRONI_POSTGRESQL_CONFIG_DIR: Pfad zum Postgres-Konfigurationsverzeichnis; standardmäßig das Datenverzeichnis. Es muss für Patroni beschreibbar sein.
• PATRONI_POSTGRESQL_BIN_DIR: Pfad zu den PostgreSQL-Programmdateien (pg_ctl, initdb, pg_controldata, pg_basebackup, postgres, pg_isready, pg_rewind). Der Standardwert ist eine leere Zeichenfolge; dann werden die Programme über die Umgebungsvariable PATH gesucht.
• PATRONI_POSTGRESQL_BIN_PG_CTL: (optional) benutzerdefinierter Name für die Programmdatei pg_ctl.
• PATRONI_POSTGRESQL_BIN_INITDB: (optional) benutzerdefinierter Name für die Programmdatei initdb.
• PATRONI_POSTGRESQL_BIN_PG_CONTROLDATA: (optional) benutzerdefinierter Name für die Programmdatei pg_controldata.
• PATRONI_POSTGRESQL_BIN_PG_BASEBACKUP: (optional) benutzerdefinierter Name für die Programmdatei pg_basebackup.
• PATRONI_POSTGRESQL_BIN_POSTGRES: (optional) benutzerdefinierter Name für die Programmdatei postgres.
• PATRONI_POSTGRESQL_BIN_IS_READY: (optional) benutzerdefinierter Name für die Programmdatei pg_isready.
• PATRONI_POSTGRESQL_BIN_PG_REWIND: (optional) benutzerdefinierter Name für die Programmdatei pg_rewind.
• PATRONI_POSTGRESQL_PGPASS: Pfad zur Passwortdatei .pgpass . Patroni erstellt diese Datei vor dem Ausführen von pg_basebackup und in einigen weiteren Fällen. Der Speicherort muss für Patroni beschreibbar sein.
• PATRONI_REPLICATION_USERNAME: Benutzername für die Replikation; der Benutzer wird bei der Initialisierung erstellt. Replikate verwenden ihn, um per Streaming-Replikation auf die Replikationsquelle zuzugreifen.
• PATRONI_REPLICATION_PASSWORD: Passwort für die Replikation; der Benutzer wird bei der Initialisierung erstellt.
• PATRONI_REPLICATION_SSLMODE: (optional) entspricht dem Verbindungsparameter sslmode , der dem Client die Auswahl des Modus für die TLS-Aushandlung mit dem Server erlaubt. Einzelheiten zur Funktionsweise der einzelnen Modi stehen in der PostgreSQL-Dokumentation . Der Standardmodus ist prefer.
• PATRONI_REPLICATION_SSLKEY: (optional) entspricht dem Verbindungsparameter sslkey , der den Speicherort des geheimen Schlüssels für das Clientzertifikat angibt.
• PATRONI_REPLICATION_SSLPASSWORD: (optional) entspricht dem Verbindungsparameter sslpassword , der das Passwort für den in PATRONI_REPLICATION_SSLKEY angegebenen geheimen Schlüssel festlegt.
• PATRONI_REPLICATION_SSLCERT: (optional) entspricht dem Verbindungsparameter sslcert , der den Speicherort des Clientzertifikats angibt.
• PATRONI_REPLICATION_SSLROOTCERT: (optional) entspricht dem Verbindungsparameter sslrootcert , der den Pfad zu einer Datei mit einem oder mehreren Zertifikaten von Zertifizierungsstellen (CA) angibt, mit denen der Client ein Serverzertifikat prüft.
• PATRONI_REPLICATION_SSLCRL: (optional) entspricht dem Verbindungsparameter sslcrl , der den Pfad zu einer Datei mit einer Zertifikatsperrliste angibt. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
• PATRONI_REPLICATION_SSLCRLDIR: (optional) entspricht dem Verbindungsparameter sslcrldir , der den Pfad zu einem Verzeichnis mit Dateien angibt, die eine Zertifikatsperrliste enthalten. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
• PATRONI_REPLICATION_SSLNEGOTIATION: (optional) entspricht dem Verbindungsparameter sslnegotiation , der steuert, wie die SSL-Verschlüsselung mit dem Server ausgehandelt wird, falls SSL verwendet wird.
• PATRONI_REPLICATION_GSSENCMODE: (optional) entspricht dem Verbindungsparameter gssencmode , der bestimmt, ob und mit welcher Priorität eine sichere GSS-Verbindung über TCP/IP mit dem Server ausgehandelt wird.
• PATRONI_REPLICATION_CHANNEL_BINDING: (optional) entspricht dem Verbindungsparameter channel_binding , der die Verwendung von Channel Binding durch den Client steuert.
• PATRONI_SUPERUSER_USERNAME: Name des Superusers, der bei der Initialisierung (initdb) festgelegt und später von Patroni für Verbindungen zu Postgres verwendet wird. Auch pg_rewind verwendet diesen Benutzer.
• PATRONI_SUPERUSER_PASSWORD: Passwort des Superusers, das bei der Initialisierung (initdb) festgelegt wird.
• PATRONI_SUPERUSER_SSLMODE: (optional) entspricht dem Verbindungsparameter sslmode , der dem Client die Auswahl des Modus für die TLS-Aushandlung mit dem Server erlaubt. Einzelheiten zur Funktionsweise der einzelnen Modi stehen in der PostgreSQL-Dokumentation . Der Standardmodus ist prefer.
• PATRONI_SUPERUSER_SSLKEY: (optional) entspricht dem Verbindungsparameter sslkey , der den Speicherort des geheimen Schlüssels für das Clientzertifikat angibt.
• PATRONI_SUPERUSER_SSLPASSWORD: (optional) entspricht dem Verbindungsparameter sslpassword , der das Passwort für den in PATRONI_SUPERUSER_SSLKEY angegebenen geheimen Schlüssel festlegt.
• PATRONI_SUPERUSER_SSLCERT: (optional) entspricht dem Verbindungsparameter sslcert , der den Speicherort des Clientzertifikats angibt.
• PATRONI_SUPERUSER_SSLROOTCERT: (optional) entspricht dem Verbindungsparameter sslrootcert , der den Pfad zu einer Datei mit einem oder mehreren Zertifikaten von Zertifizierungsstellen (CA) angibt, mit denen der Client ein Serverzertifikat prüft.
• PATRONI_SUPERUSER_SSLCRL: (optional) entspricht dem Verbindungsparameter sslcrl , der den Pfad zu einer Datei mit einer Zertifikatsperrliste angibt. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
• PATRONI_SUPERUSER_SSLCRLDIR: (optional) entspricht dem Verbindungsparameter sslcrldir , der den Pfad zu einem Verzeichnis mit Dateien angibt, die eine Zertifikatsperrliste enthalten. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
• PATRONI_SUPERUSER_SSLNEGOTIATION: (optional) entspricht dem Verbindungsparameter sslnegotiation , der steuert, wie die SSL-Verschlüsselung mit dem Server ausgehandelt wird, falls SSL verwendet wird.
• PATRONI_SUPERUSER_GSSENCMODE: (optional) entspricht dem Verbindungsparameter gssencmode , der bestimmt, ob und mit welcher Priorität eine sichere GSS-Verbindung über TCP/IP mit dem Server ausgehandelt wird.
• PATRONI_SUPERUSER_CHANNEL_BINDING: (optional) entspricht dem Verbindungsparameter channel_binding , der die Verwendung von Channel Binding durch den Client steuert.
• PATRONI_REWIND_USERNAME: (optional) Name des Benutzers für pg_rewind; er wird bei der Initialisierung von Postgres 11+ erstellt und erhält alle erforderlichen Berechtigungen .
• PATRONI_REWIND_PASSWORD: (optional) Passwort des Benutzers für pg_rewind; er wird bei der Initialisierung erstellt.
• PATRONI_REWIND_SSLMODE: (optional) entspricht dem Verbindungsparameter sslmode , der dem Client die Auswahl des Modus für die TLS-Aushandlung mit dem Server erlaubt. Einzelheiten zur Funktionsweise der einzelnen Modi stehen in der PostgreSQL-Dokumentation . Der Standardmodus ist prefer.
• PATRONI_REWIND_SSLKEY: (optional) entspricht dem Verbindungsparameter sslkey , der den Speicherort des geheimen Schlüssels für das Clientzertifikat angibt.
• PATRONI_REWIND_SSLPASSWORD: (optional) entspricht dem Verbindungsparameter sslpassword , der das Passwort für den in PATRONI_REWIND_SSLKEY angegebenen geheimen Schlüssel festlegt.
• PATRONI_REWIND_SSLCERT: (optional) entspricht dem Verbindungsparameter sslcert , der den Speicherort des Clientzertifikats angibt.
• PATRONI_REWIND_SSLROOTCERT: (optional) entspricht dem Verbindungsparameter sslrootcert , der den Pfad zu einer Datei mit einem oder mehreren Zertifikaten von Zertifizierungsstellen (CA) angibt, mit denen der Client ein Serverzertifikat prüft.
• PATRONI_REWIND_SSLCRL: (optional) entspricht dem Verbindungsparameter sslcrl , der den Pfad zu einer Datei mit einer Zertifikatsperrliste angibt. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
• PATRONI_REWIND_SSLCRLDIR: (optional) entspricht dem Verbindungsparameter sslcrldir , der den Pfad zu einem Verzeichnis mit Dateien angibt, die eine Zertifikatsperrliste enthalten. Ein Client lehnt Verbindungen zu Servern ab, deren Zertifikat in dieser Liste enthalten ist.
• PATRONI_REWIND_SSLNEGOTIATION: (optional) entspricht dem Verbindungsparameter sslnegotiation , der steuert, wie die SSL-Verschlüsselung mit dem Server ausgehandelt wird, falls SSL verwendet wird.
• PATRONI_REWIND_GSSENCMODE: (optional) entspricht dem Verbindungsparameter gssencmode , der bestimmt, ob und mit welcher Priorität eine sichere GSS-Verbindung über TCP/IP mit dem Server ausgehandelt wird.
• PATRONI_REWIND_CHANNEL_BINDING: (optional) entspricht dem Verbindungsparameter channel_binding , der die Verwendung von Channel Binding durch den Client steuert.

REST API

• PATRONI_RESTAPI_THREAD_POOL_SIZE: Größe des Threadpools, mit dem Patroni REST-API-Anfragen verarbeitet. Mindestwert: 5, Standardwert: 5.
• PATRONI_RESTAPI_CONNECT_ADDRESS: IP-Adresse und Port für den Zugriff auf die REST API.
• PATRONI_RESTAPI_LISTEN: IP-Adresse und Port, an denen Patroni auf Verbindungen wartet, um Health-Check-Informationen für HAProxy bereitzustellen.
• PATRONI_RESTAPI_USERNAME: Benutzername für die Basic-Authentifizierung zum Schutz unsicherer REST-API-Endpunkte.
• PATRONI_RESTAPI_PASSWORD: Passwort für die Basic-Authentifizierung zum Schutz unsicherer REST-API-Endpunkte.
• PATRONI_RESTAPI_CERTFILE: gibt die Datei mit dem Zertifikat im PEM-Format an. Ist certfile nicht angegeben oder leer, arbeitet der API-Server ohne SSL.
• PATRONI_RESTAPI_KEYFILE: gibt die Datei mit dem geheimen Schlüssel im PEM-Format an.
• PATRONI_RESTAPI_KEYFILE_PASSWORD: gibt ein Passwort zum Entschlüsseln der Schlüsseldatei an.
• PATRONI_RESTAPI_CAFILE: gibt die Datei mit dem CA_BUNDLE vertrauenswürdiger CA-Zertifikate an, die zum Prüfen der Clientzertifikate verwendet werden.
• PATRONI_RESTAPI_CIPHERS: (optional) gibt die zulässigen Cipher Suites an (z. B. “ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:!SSLv1:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1”)
• PATRONI_RESTAPI_VERIFY_CLIENT: none (Standard), optional oder required. Bei none prüft die REST API keine Clientzertifikate. Bei required sind Clientzertifikate für alle REST-API-Aufrufe erforderlich. Bei optional sind sie für alle unsicheren REST-API-Endpunkte erforderlich. Bei required ist die Clientauthentifizierung erfolgreich, wenn die Prüfung der Zertifikatssignatur erfolgreich ist. Bei optional wird das Clientzertifikat nur bei Anfragen mit PUT, POST, PATCH und DELETE geprüft.
• PATRONI_RESTAPI_ALLOWLIST: (optional): legt die Hosts fest, die unsichere REST-API-Endpunkte aufrufen dürfen. Ein Eintrag kann ein Hostname, eine IP-Adresse oder eine Netzwerkadresse in CIDR-Schreibweise sein. Standardmäßig gilt allow all. Ist allowlist oder allowlist_include_members gesetzt, werden alle nicht enthaltenen Zugriffe abgelehnt.
• PATRONI_RESTAPI_ALLOWLIST_INCLUDE_MEMBERS: (optional): bei true dürfen andere im DCS registrierte Clustermitglieder auf unsichere REST-API-Endpunkte zugreifen (IP-Adresse oder Hostname werden aus api_url des Mitglieds übernommen). Vorsicht: Das Betriebssystem kann für ausgehende Verbindungen eine andere IP-Adresse verwenden.
• PATRONI_RESTAPI_HTTP_EXTRA_HEADERS: (optional) HTTP-Header ermöglichen es dem REST-API-Server, zusätzliche Informationen mit einer HTTP-Antwort zu übertragen.
• PATRONI_RESTAPI_HTTPS_EXTRA_HEADERS: (optional) HTTPS-Header ermöglichen es dem REST-API-Server, bei aktiviertem TLS zusätzliche Informationen mit einer HTTP-Antwort zu übertragen. Die in http_extra_headers festgelegten Zusatzinformationen werden ebenfalls übertragen.
• PATRONI_RESTAPI_REQUEST_QUEUE_SIZE: (optional): legt die Größe der Anfragewarteschlange für den TCP-Socket der Patroni REST API fest. Ist die Warteschlange voll, erhalten weitere Anfragen den Fehler “Connection denied”. Der Standardwert ist 5.
• PATRONI_RESTAPI_SERVER_TOKENS: (optional) konfiguriert den Wert des HTTP-Headers Server. Original (Standard) behält das ursprüngliche Verhalten bei und zeigt die Versionen von BaseHTTP und Python an, etwa BaseHTTP/0.6 Python/3.12.3. Minimal: Der Header enthält nur die Patroni-Version, etwa Patroni/4.0.0. ProductOnly: Der Header enthält nur den Produktnamen, etwa Patroni.

CTL

• PATRONICTL_CONFIG_FILE: (optional) Pfad zur Konfigurationsdatei.
• PATRONI_CTL_USERNAME: (optional) Benutzername für die Basic-Authentifizierung beim Zugriff auf geschützte REST-API-Endpunkte. Ohne Angabe verwendet patronictl den Wert des REST-API-Parameters “username”.
• PATRONI_CTL_PASSWORD: (optional) Passwort für die Basic-Authentifizierung beim Zugriff auf geschützte REST-API-Endpunkte. Ohne Angabe verwendet patronictl den Wert des REST-API-Parameters “password”.
• PATRONI_CTL_INSECURE: (optional) erlaubt Verbindungen zur REST API ohne Prüfung der SSL-Zertifikate.
• PATRONI_CTL_CACERT: (optional) gibt die CA_BUNDLE-Datei oder das Verzeichnis mit Zertifikaten vertrauenswürdiger CAs an, die zum Prüfen der SSL-Zertifikate der REST API verwendet werden. Ohne Angabe verwendet patronictl den Wert des REST-API-Parameters “cafile”.
• PATRONI_CTL_CERTFILE: (optional) gibt die Datei mit dem Clientzertifikat im PEM-Format an.
• PATRONI_CTL_KEYFILE: (optional) gibt die Datei mit dem geheimen Clientschlüssel im PEM-Format an.
• PATRONI_CTL_KEYFILE_PASSWORD: (optional) gibt ein Passwort zum Entschlüsseln der Clientschlüsseldatei an.

4 - Patroni REST API

Patroni bietet eine umfangreiche REST API. Patroni selbst nutzt sie bei der Leader-Wahl, das Werkzeug patronictl für Failover, Switchover, Neuinitialisierung, Neustart und Neuladen sowie HAProxy und andere Load-Balancer für HTTP Health Checks. Sie kann auch zur Überwachung verwendet werden. Nachfolgend sind die REST-API-Endpunkte von Patroni aufgeführt.

Endpunkte für Health Checks

Bei allen GET-Anfragen für Health Checks gibt Patroni neben dem HTTP-Statuscode ein JSON-Dokument mit dem Zustand des Knotens zurück. Wenn das JSON-Dokument nicht gewünscht oder benötigt wird, kann anstelle von GET die Methode HEAD oder OPTIONS verwendet werden.

• Die folgenden Anfragen an die REST API von Patroni liefern den HTTP-Statuscode 200 nur dann, wenn der Patroni-Knoten als Primärserver mit Leader-Lock läuft:

  • GET /
  • GET /primary
  • GET /read-write

• GET /standby-leader: Liefert den HTTP-Statuscode 200 nur dann, wenn der Patroni-Knoten als Leader in einem Standby-Cluster läuft.

• GET /leader: Liefert den HTTP-Statuscode 200, wenn der Patroni-Knoten den Leader-Lock hält. Anders als bei GET /primary und GET /standby-leader hängt diese Prüfung nicht davon ab, ob PostgreSQL als primary oder als standby_leader läuft.

• GET /replica: Endpunkt für den Health Check eines Replikats. Liefert den HTTP-Statuscode 200 nur dann, wenn der Patroni-Knoten den Zustand running und die Rolle replica hat und das Tag noloadbalance nicht gesetzt ist.

• GET /replica?replication_state=<required state>: Endpunkt zur Prüfung eines Replikats. Prüft zusätzlich zu den Prüfungen von replica, ob der Replikationszustand dem geforderten Zustand entspricht. Vor allem mit replication_state=streaming nützlich, um Replikate auszuschließen, die noch mittels Archiv-Recovery aufholen.

• GET /replica?lag=<max-lag>: Endpunkt zur Prüfung eines Replikats. Prüft zusätzlich zu den Prüfungen von replica den Replikationsrückstand und liefert den Statuscode 200 nur dann, wenn er unter dem angegebenen Wert liegt. Aus Leistungsgründen wird der Schlüssel cluster.last_leader_operation aus dem DCS für die WAL-Position des Leaders und zur Berechnung des Rückstands des Replikats verwendet. max-lag kann in Bytes (als Ganzzahl) oder in lesbarer Form angegeben werden, z. B. 16kB, 64MB, 1GB.

  • GET /replica?lag=1048576
  • GET /replica?lag=1024kB
  • GET /replica?lag=10MB
  • GET /replica?lag=1GB

• GET /replica?tag_key1=value1&tag_key2=value2: Endpunkt zur Prüfung eines Replikats. Prüft zusätzlich die benutzerdefinierten Tags key1 und key2 und ihre jeweiligen Werte im Abschnitt tags der YAML-Konfiguration. Wenn das Tag für eine Instanz nicht definiert ist oder der Wert in der YAML-Konfiguration nicht mit dem abgefragten Wert übereinstimmt, wird der HTTP-Statuscode 503 zurückgegeben.

  Bei den folgenden Anfragen wird der Status als Leader oder Standby-Leader geprüft. Daher berücksichtigt Patroni keine benutzerdefinierten Tags und ignoriert sie.

  • GET /?tag_key1=value1&tag_key2=value2
  • GET /leader?tag_key1=value1&tag_key2=value2
  • GET /primary?tag_key1=value1&tag_key2=value2
  • GET /read-write?tag_key1=value1&tag_key2=value2
  • GET /standby_leader?tag_key1=value1&tag_key2=value2
  • GET /standby-leader?tag_key1=value1&tag_key2=value2

• GET /read-only: Wie der obige Endpunkt, schließt aber auch den Primärserver ein.

• GET /synchronous oder GET /sync: Liefert den HTTP-Statuscode 200 nur dann, wenn der Patroni-Knoten als synchroner Standby läuft.

• GET /read-only-sync: Wie der obige Endpunkt, schließt aber auch den Primärserver ein.

• GET /quorum: Liefert den HTTP-Statuscode 200 nur dann, wenn dieser Patroni-Knoten auf dem Primärserver in synchronous_standby_names als Quorum-Knoten aufgeführt ist.

• GET /read-only-quorum: Wie der obige Endpunkt, schließt aber auch den Primärserver ein.

• GET /asynchronous oder GET /async: Liefert den HTTP-Statuscode 200 nur dann, wenn der Patroni-Knoten als asynchroner Standby läuft.

• GET /asynchronous?lag=<max-lag> oder GET /async?lag=<max-lag>: Endpunkt zur Prüfung eines asynchronen Standbys. Prüft zusätzlich zu den Prüfungen von asynchronous oder async den Replikationsrückstand und liefert den Statuscode 200 nur dann, wenn er unter dem angegebenen Wert liegt. Aus Leistungsgründen wird der Schlüssel cluster.last_leader_operation aus dem DCS für die WAL-Position des Leaders und zur Berechnung des Rückstands des Replikats verwendet. max-lag kann in Bytes (als Ganzzahl) oder in lesbarer Form angegeben werden, z. B. 16kB, 64MB, 1GB.

  • GET /async?lag=1048576
  • GET /async?lag=1024kB
  • GET /async?lag=10MB
  • GET /async?lag=1GB

• GET /health: Liefert den HTTP-Statuscode 200 nur dann, wenn PostgreSQL läuft.

• GET /liveness: Liefert den HTTP-Statuscode 200, wenn die Heartbeat-Schleife von Patroni ordnungsgemäß läuft, und 503, wenn der letzte Durchlauf auf dem Primärserver mehr als ttl Sekunden oder auf dem Replikat mehr als 2*ttl Sekunden zurückliegt. Kann für livenessProbe verwendet werden.

• GET /readiness?lag=<max-lag>&mode=apply|write: Liefert den HTTP-Statuscode 200, wenn der Patroni-Knoten als Leader läuft oder wenn PostgreSQL läuft, repliziert und nicht zu weit hinter dem Leader zurückliegt. Der Parameter lag legt den zulässigen Rückstand eines Standbys fest; sein Standardwert ist maximum_lag_on_failover. Der Rückstand kann in Bytes oder in lesbarer Form angegeben werden, beispielsweise 16kB, 64MB oder 1GB. Der Parameter mode legt fest, ob das WAL wiedergegeben (apply) oder lediglich empfangen (write) werden muss. Der Standardwert ist apply.

  Bei Verwendung als Kubernetes-readinessProbe stellt der Endpunkt sicher, dass frisch gestartete Pods erst dann bereit sind, wenn sie zum Leader aufgeholt haben. Zusammen mit einem PodDisruptionBudget verhindert dies, dass der Leader bei einem schrittweisen Neustart der Knoten zu früh beendet wird. Außerdem wird sichergestellt, dass Replikate, die mit der Replikation nicht Schritt halten können, keinen schreibgeschützten Datenverkehr bedienen. Der Endpunkt kann für readinessProbe verwendet werden, wenn Kubernetes-Endpunkte nicht für die Leader-Wahl genutzt werden können (OpenShift).

Der Endpunkt liveness benötigt nur sehr wenige Ressourcen und führt kein SQL aus. Die Prüfungen sollten so konfiguriert werden, dass sie etwa zu dem Zeitpunkt fehlschlagen, zu dem der Leader-Schlüssel abläuft. Beim Standardwert 30s für ttl könnten die Prüfungen beispielsweise wie folgt aussehen:

readinessProbe:
  httpGet:
    scheme: HTTP
    path: /readiness
    port: 8008
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3
livenessProbe:
  httpGet:
    scheme: HTTP
    path: /liveness
    port: 8008
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3

Endpunkt zur Überwachung

Patroni verwendet GET /patroni bei der Leader-Wahl. Der Endpunkt kann auch vom Überwachungssystem genutzt werden. Das von diesem Endpunkt erzeugte JSON-Dokument hat dieselbe Struktur wie die JSON-Dokumente der Endpunkte für Health Checks.

Beispiel: Ein funktionsfähiger Cluster

$ curl -s http://localhost:8008/patroni | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "primary",
  "server_version": 160004,
  "xlog": {
    "location": 67395656
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "dcs_last_seen": 1692356718,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

Beispiel: Ein Cluster ohne Leader-Lock

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "received_location": 67419744,
    "replayed_location": 67419744,
    "replayed_timestamp": null,
    "paused": false
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "cluster_unlocked": true,
  "dcs_last_seen": 1692356928,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

Beispiel: Ein Cluster ohne Leader-Lock mit aktiviertem DCS-Failsafe-Modus

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "location": 67420024
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "cluster_unlocked": true,
  "failsafe_mode_is_active": true,
  "dcs_last_seen": 1692356928,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

Beispiel: Ein Cluster mit aktiviertem Pausenmodus

$ curl -s http://localhost:8008/patroni  | jq .
{
  "state": "running",
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "role": "replica",
  "server_version": 160004,
  "xlog": {
    "location": 67420024
  },
  "timeline": 1,
  "replication": [
    {
      "usename": "replicator",
      "application_name": "patroni2",
      "client_addr": "10.89.0.6",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    },
    {
      "usename": "replicator",
      "application_name": "patroni3",
      "client_addr": "10.89.0.2",
      "state": "streaming",
      "sync_state": "async",
      "sync_priority": 0
    }
  ],
  "pause": true,
  "dcs_last_seen": 1724874295,
  "tags": {
    "clonefrom": true
  },
  "database_system_identifier": "7268616322854375442",
  "patroni": {
    "version": "4.0.0",
    "scope": "demo",
    "name": "patroni1"
  }
}

Die Patroni-Metriken lassen sich über den Endpunkt GET /metrics im Prometheus-Format abrufen.

$ curl http://localhost:8008/metrics

# HELP patroni_version Patroni semver without periods. \
# TYPE patroni_version gauge
patroni_version{scope="batman",name="patroni1"} 040000
# HELP patroni_postgres_running Value is 1 if Postgres is running, 0 otherwise.
# TYPE patroni_postgres_running gauge
patroni_postgres_running{scope="batman",name="patroni1"} 1
# HELP patroni_postmaster_start_time Epoch seconds since Postgres started.
# TYPE patroni_postmaster_start_time gauge
patroni_postmaster_start_time{scope="batman",name="patroni1"} 1724873966.352526
# HELP patroni_primary Value is 1 if this node is the leader, 0 otherwise.
# TYPE patroni_primary gauge
patroni_primary{scope="batman",name="patroni1"} 1
# HELP patroni_xlog_location Current location of the Postgres transaction log, 0 if this node is not the leader.
# TYPE patroni_xlog_location counter
patroni_xlog_location{scope="batman",name="patroni1"} 22320573386952
# HELP patroni_standby_leader Value is 1 if this node is the standby_leader, 0 otherwise.
# TYPE patroni_standby_leader gauge
patroni_standby_leader{scope="batman",name="patroni1"} 0
# HELP patroni_replica Value is 1 if this node is a replica, 0 otherwise.
# TYPE patroni_replica gauge
patroni_replica{scope="batman",name="patroni1"} 0
# HELP patroni_sync_standby Value is 1 if this node is a sync standby replica, 0 otherwise.
# TYPE patroni_sync_standby gauge
patroni_sync_standby{scope="batman",name="patroni1"} 0
# HELP patroni_quorum_standby Value is 1 if this node is a quorum standby replica, 0 otherwise.
# TYPE patroni_quorum_standby gauge
patroni_quorum_standby{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_received_location Current location of the received Postgres transaction log, 0 if this node is not a replica.
# TYPE patroni_xlog_received_location counter
patroni_xlog_received_location{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_replayed_location Current location of the replayed Postgres transaction log, 0 if this node is not a replica.
# TYPE patroni_xlog_replayed_location counter
patroni_xlog_replayed_location{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_replayed_timestamp Current timestamp of the replayed Postgres transaction log, 0 if null.
# TYPE patroni_xlog_replayed_timestamp gauge
patroni_xlog_replayed_timestamp{scope="batman",name="patroni1"} 0
# HELP patroni_xlog_paused Value is 1 if the Postgres xlog is paused, 0 otherwise.
# TYPE patroni_xlog_paused gauge
patroni_xlog_paused{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_streaming Value is 1 if Postgres is streaming, 0 otherwise.
# TYPE patroni_postgres_streaming gauge
patroni_postgres_streaming{scope="batman",name="patroni1"} 1
# HELP patroni_postgres_in_archive_recovery Value is 1 if Postgres is replicating from archive, 0 otherwise.
# TYPE patroni_postgres_in_archive_recovery gauge
patroni_postgres_in_archive_recovery{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_server_version Version of Postgres (if running), 0 otherwise.
# TYPE patroni_postgres_server_version gauge
patroni_postgres_server_version{scope="batman",name="patroni1"} 160004
# HELP patroni_cluster_unlocked Value is 1 if the cluster is unlocked, 0 if locked.
# TYPE patroni_cluster_unlocked gauge
patroni_cluster_unlocked{scope="batman",name="patroni1"} 0
# HELP patroni_failsafe_mode_is_active Value is 1 if failsafe mode is active, 0 otherwise.
# TYPE patroni_failsafe_mode_is_active gauge
patroni_failsafe_mode_is_active{scope="batman",name="patroni1"} 0
# HELP patroni_failsafe_mode_enabled Value is 1 if failsafe_mode is enabled, 0 otherwise.
# TYPE patroni_failsafe_mode_enabled gauge
patroni_failsafe_mode_enabled{scope="batman",name="patroni1"} 0
# HELP patroni_failsafe_member Value is 1 if this node is a member of failsafe, 0 otherwise.
# TYPE patroni_failsafe_member gauge
patroni_failsafe_member{scope="batman",name="patroni1"} 0
# HELP patroni_postgres_timeline Postgres timeline of this node (if running), 0 otherwise.
# TYPE patroni_postgres_timeline gauge
patroni_postgres_timeline{scope="batman",name="patroni1"} 24
# HELP patroni_dcs_last_seen Epoch timestamp when DCS was last contacted successfully by Patroni.
# TYPE patroni_dcs_last_seen gauge
patroni_dcs_last_seen{scope="batman",name="patroni1"} 1724874235
# HELP patroni_pending_restart Value is 1 if the node needs a restart, 0 otherwise.
# TYPE patroni_pending_restart gauge
patroni_pending_restart{scope="batman",name="patroni1"} 1
# HELP patroni_is_paused Value is 1 if auto failover is disabled, 0 otherwise.
# TYPE patroni_is_paused gauge
patroni_is_paused{scope="batman",name="patroni1"} 1
# HELP patroni_postgres_state Numeric representation of Postgres state.
# Values: 0=initdb, 1=initdb_failed, 2=custom_bootstrap, 3=custom_bootstrap_failed, 4=creating_replica, 5=running, 6=starting, 7=bootstrap_starting, 8=start_failed, 9=restarting, 10=restart_failed, 11=stopping, 12=stopped, 13=stop_failed, 14=crashed
# TYPE patroni_postgres_state gauge
patroni_postgres_state{scope="batman",name="patroni1"} 5
# HELP patroni_failover_priority Failover priority of this node.
# TYPE patroni_failover_priority gauge
patroni_failover_priority{scope="batman",name="patroni1"} 1

PostgreSQL-Zustandswerte

Die Metrik patroni_postgres_state bildet den aktuellen Zustand der PostgreSQL-Instanz als Zahl ab. Das ist für Überwachungs- und Alarmierungssysteme nützlich, die Zustandsänderungen im Zeitverlauf verfolgen müssen. Die Zahlenwerte werden mit der statischen Methode PostgresqlState.get_metrics_description() erzeugt.

PostgreSQL-Zustandswerte

Endpunkte für den Cluster-Status

• Der Endpunkt GET /cluster erzeugt ein JSON-Dokument, das die aktuelle Topologie und den Zustand des Clusters beschreibt:

$ curl -s http://localhost:8008/cluster | jq .
{
  "members": [
    {
      "name": "patroni1",
      "role": "leader",
      "state": "running",
      "api_url": "http://10.89.0.4:8008/patroni",
      "host": "10.89.0.4",
      "port": 5432,
      "timeline": 5,
      "tags": {
        "clonefrom": true
      }
    },
    {
      "name": "patroni2",
      "role": "replica",
      "state": "streaming",
      "api_url": "http://10.89.0.6:8008/patroni",
      "host": "10.89.0.6",
      "port": 5433,
      "timeline": 5,
      "tags": {
        "clonefrom": true
      },
      "receive_lag": 0,
      "receive_lsn": "0/4000060",
      "replay_lag": 0,
      "replay_lsn": "0/4000060",
      "lag": 0,
      "lsn": "0/4000060"
    }
  ],
  "scope": "demo",
  "scheduled_switchover": {
    "at": "2023-09-24T10:36:00+02:00",
    "from": "patroni1",
    "to": "patroni3"
  }
}

• Der Endpunkt GET /history bietet einen Überblick über die Switchover- und Failover-Historie des Clusters. Das Format ähnelt stark dem Inhalt der History-Dateien im Verzeichnis pg_wal. Der einzige Unterschied ist das Zeitstempelfeld, das angibt, wann die neue Timeline erstellt wurde.

$ curl -s http://localhost:8008/history | jq .
[
  [
    1,
    25623960,
    "no recovery target specified",
    "2019-09-23T16:57:57+02:00"
  ],
  [
    2,
    25624344,
    "no recovery target specified",
    "2019-09-24T09:22:33+02:00"
  ],
  [
    3,
    25624752,
    "no recovery target specified",
    "2019-09-24T09:26:15+02:00"
  ],
  [
    4,
    50331856,
    "no recovery target specified",
    "2019-09-24T09:35:52+02:00"
  ]
]

Endpunkt für die Konfiguration

GET /config: Aktuelle Version der dynamischen Konfiguration abrufen:

$ curl -s http://localhost:8008/config | jq .
{
  "ttl": 30,
  "loop_wait": 10,
  "retry_timeout": 10,
  "maximum_lag_on_failover": 1048576,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5,
      "max_connections": "100"
    }
  }
}

PATCH /config: Bestehende Konfiguration ändern.

$ curl -s -XPATCH -d \
    '{"loop_wait":5,"ttl":20,"postgresql":{"parameters":{"max_connections":"101"}}}' \
    http://localhost:8008/config | jq .
{
  "ttl": 20,
  "loop_wait": 5,
  "maximum_lag_on_failover": 1048576,
  "retry_timeout": 10,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5,
      "max_connections": "101"
    }
  }
}

Der obige REST-API-Aufruf ändert die bestehende Konfiguration und gibt die neue Konfiguration zurück.

Nun prüfen, ob der Knoten diese Konfiguration verarbeitet hat. Zunächst sollte er alle 5 Sekunden Protokollzeilen ausgeben (loop_wait=5). Die Änderung von „max_connections“ erfordert einen Neustart, daher sollte das Flag „pending_restart“ angezeigt werden:

$ curl -s http://localhost:8008/patroni | jq .
{
  "postmaster_start_time": "2024-08-28 19:39:26.352526+00:00",
  "xlog": {
    "location": 2197818976
  },
  "timeline": 1,
  "dcs_last_seen": 1724874545,
  "database_system_identifier": "7408277255830290455",
  "pending_restart": true,
  "pending_restart_reason": {
    "max_connections": {
      "old_value": "100",
      "new_value": "101"
    }
  },
  "patroni": {
    "version": "4.0.0",
    "scope": "batman",
    "name": "patroni1"
  },
  "state": "running",
  "role": "primary",
  "server_version": 160004
}

Parameter entfernen:

Um eine Einstellung zu entfernen (zurückzusetzen), genügt es, sie per Patch auf null zu setzen:

$ curl -s -XPATCH -d \
    '{"postgresql":{"parameters":{"max_connections":null}}}' \
    http://localhost:8008/config | jq .
{
  "ttl": 20,
  "loop_wait": 5,
  "retry_timeout": 10,
  "maximum_lag_on_failover": 1048576,
  "postgresql": {
    "use_slots": true,
    "use_pg_rewind": true,
    "parameters": {
      "hot_standby": "on",
      "unix_socket_directories": ".",
      "wal_level": "hot_standby",
      "max_wal_senders": 5,
      "max_replication_slots": 5
    }
  }
}

Der obige Aufruf entfernt postgresql.parameters.max_connections aus der dynamischen Konfiguration.

PUT /config: Eine bestehende dynamische Konfiguration kann auch bedingungslos vollständig überschrieben werden:

$ curl -s -XPUT -d \
    '{"maximum_lag_on_failover":1048576,"retry_timeout":10,"postgresql":{"use_slots":true,"use_pg_rewind":true,"parameters":{"hot_standby":"on","wal_level":"hot_standby","unix_socket_directories":".","max_wal_senders":5}},"loop_wait":3,"ttl":20}' \
    http://localhost:8008/config | jq .
{
  "ttl": 20,
  "maximum_lag_on_failover": 1048576,
  "retry_timeout": 10,
  "postgresql": {
    "use_slots": true,
    "parameters": {
      "hot_standby": "on",
      "unix_socket_directories": ".",
      "wal_level": "hot_standby",
      "max_wal_senders": 5
    },
    "use_pg_rewind": true
  },
  "loop_wait": 3
}

Endpunkte für Switchover und Failover

Switchover

Der Endpunkt /switchover funktioniert nur, wenn der Cluster funktionsfähig ist (ein Leader vorhanden ist). Er ermöglicht auch, einen Switchover zu einem bestimmten Zeitpunkt zu planen.

Beim Aufruf des Endpunkts /switchover kann ein Kandidat angegeben werden; anders als beim Endpunkt /failover ist dies jedoch nicht erforderlich. Wird kein Kandidat angegeben, nehmen alle geeigneten Knoten des Clusters an der Leader-Wahl teil, nachdem der Leader seine Rolle abgegeben hat.

Im JSON-Inhalt der POST-Anfrage muss das Feld leader angegeben werden. Die Felder candidate und scheduled_at sind optional und können verwendet werden, um einen Switchover zu einem bestimmten Zeitpunkt zu planen.

Je nach Situation können Anfragen unterschiedliche HTTP-Statuscodes und Antwortinhalte liefern. Der Statuscode 200 wird zurückgegeben, wenn der Switchover oder das Failover erfolgreich abgeschlossen wurde. Wurde der Switchover erfolgreich geplant, liefert Patroni den HTTP-Statuscode 202. Ist ein Fehler aufgetreten, wird ein Fehlerstatuscode (400, 412 oder 503) mit Einzelheiten im Antwortinhalt zurückgegeben.

Mit DELETE /switchover kann der aktuell geplante Switchover gelöscht werden.

Beispiel: Switchover zu einem beliebigen funktionsfähigen Standby durchführen

$ curl -s http://localhost:8008/switchover -XPOST -d '{"leader":"postgresql1"}'
Successfully switched over to "postgresql2"

Beispiel: Switchover zu einem bestimmten Knoten durchführen

$ curl -s http://localhost:8008/switchover -XPOST -d \
    '{"leader":"postgresql1","candidate":"postgresql2"}'
Successfully switched over to "postgresql2"

Beispiel: Switchover vom Leader zu einem beliebigen anderen funktionsfähigen Standby im Cluster zu einem bestimmten Zeitpunkt planen.

$ curl -s http://localhost:8008/switchover -XPOST -d \
    '{"leader":"postgresql0","scheduled_at":"2019-09-24T12:00+00"}'
Switchover scheduled

Failover

Der Endpunkt /failover kann für ein manuelles Failover verwendet werden, wenn keine funktionsfähigen Knoten vorhanden sind (z. B. zu einem asynchronen Standby, wenn alle synchronen Standbys für eine Hochstufung nicht funktionsfähig genug sind). Ein fehlender Leader ist jedoch keine Voraussetzung: Ein Failover kann auch in einem funktionsfähigen Cluster ausgeführt werden.

Im JSON-Inhalt der POST-Anfrage muss das Feld candidate angegeben werden. Wird das Feld leader angegeben, wird stattdessen ein Switchover ausgelöst.

Beispiel:

$ curl -s http://localhost:8008/failover -XPOST -d '{"candidate":"postgresql1"}'
Successfully failed over to "postgresql1"

Die Endpunkte POST /switchover und POST /failover werden von patronictl_switchover bzw. patronictl_failover verwendet.

DELETE /switchover wird von patronictl flush cluster-name switchover verwendet.

Vergleich von Failover und Switchover

Funktionsfähiger Standby

Ein Cluster-Mitglied sollte einige Prüfungen bestehen, um bei einem Switchover an der Leader-Wahl teilnehmen oder als Failover-/Switchover-Kandidat zum Leader werden zu können:

• über die Patroni API erreichbar sein;
• das Tag nofailover darf nicht auf true gesetzt sein;
• über einen voll funktionsfähigen Watchdog verfügen (falls die Konfiguration dies erfordert);
• bei einem Switchover in einem funktionsfähigen Cluster oder einem automatischen Failover den maximalen Replikationsrückstand nicht überschreiten (Konfigurationsparameter maximum_lag_on_failover);
• bei einem Switchover in einem funktionsfähigen Cluster oder einem automatischen Failover keine kleinere Timeline-Nummer als die Cluster-Timeline haben, wenn der Konfigurationsparameter check_timeline auf true gesetzt ist;
• im synchronen Modus :
  • Bei einem Switchover (mit oder ohne Kandidaten): unter den Mitgliedern des Schlüssels /sync aufgeführt sein;
  • Bei einem Failover sowohl in funktionsfähigen als auch in nicht funktionsfähigen Clustern entfällt diese Prüfung.

Endpunkt für Neustarts

• POST /restart: Mit dem Aufruf POST /restart kann Postgres auf dem jeweiligen Knoten neu gestartet werden. Im JSON-Inhalt der POST-Anfrage können optional Bedingungen für den Neustart angegeben werden:
  • restart_pending: Boolescher Wert. Bei true startet Patroni PostgreSQL nur dann neu, wenn ein Neustart aussteht, um Änderungen an der PostgreSQL-Konfiguration anzuwenden.
  • role: Neustart nur durchführen, wenn die aktuelle Rolle des Knotens mit der Rolle aus der POST-Anfrage übereinstimmt.
  • postgres_version: Neustart nur durchführen, wenn die aktuelle Postgres-Version kleiner als die in der POST-Anfrage angegebene ist.
  • timeout: Wartezeit, bis PostgreSQL Verbindungen annimmt. Überschreibt primary_start_timeout.
  • schedule: Zeitstempel mit Zeitzone; plant den Neustart für einen zukünftigen Zeitpunkt.
• DELETE /restart: Geplanten Neustart löschen

Die Endpunkte POST /restart und DELETE /restart werden von patronictl_restart bzw. patronictl flush cluster-name restart verwendet.

Endpunkt zum Neuladen

Der Aufruf POST /reload weist Patroni an, die Konfigurationsdatei erneut einzulesen und anzuwenden. Dies entspricht dem Senden des Signals SIGHUP an den Patroni-Prozess. Wenn Postgres-Parameter geändert wurden, die einen Neustart erfordern (z. B. shared_buffers), muss Postgres weiterhin ausdrücklich neu gestartet werden, entweder über den Endpunkt POST /restart oder mithilfe von patronictl_restart .

Der Endpunkt zum Neuladen wird von patronictl_reload verwendet.

Endpunkt zur Neuinitialisierung

POST /reinitialize: Initialisiert das PostgreSQL-Datenverzeichnis auf dem angegebenen Knoten neu. Der Aufruf darf nur auf Replikaten ausgeführt werden. Er entfernt das Datenverzeichnis und startet pg_basebackup oder eine alternative Methode zur Replikaterstellung .

Der Aufruf kann fehlschlagen, wenn Patroni in einer Schleife versucht, ein ausgefallenes Postgres wiederherzustellen (neu zu starten). Um dieses Problem zu umgehen, kann im Anfrageinhalt {"force":true} angegeben werden.

Im Anfrageinhalt kann {“from-leader”:true} angegeben werden, um das Basis-Backup direkt vom Leader-Knoten zu beziehen. Dies ist nützlich, wenn die Neuinitialisierung bei einem Ausfall aller Replikatknoten ausgeführt wird.

Der Endpunkt zur Neuinitialisierung wird von patronictl_reinit verwendet.

5 - patronictl

Patroni bietet eine Befehlszeilenschnittstelle namens patronictl , die hauptsächlich mit der REST API von Patroni und dem DCS interagiert. Sie erleichtert die Durchführung von Vorgängen im Cluster und lässt sich sowohl manuell als auch in Skripten einfach verwenden.

Konfiguration

patronictl verwendet 3 Abschnitte der Konfiguration:

• ctl: Authentifizierung gegenüber der REST API von Patroni und Prüfung der Serveridentität. Weitere Einzelheiten finden sich unter ctl-Einstellungen ;
• restapi: Authentifizierung gegenüber der REST API von Patroni und Prüfung der Serveridentität. Wird nur verwendet, wenn die ctl-Konfiguration nicht ausreicht. patronictl verwendet hauptsächlich den Abschnitt restapi.authentication (wenn ctl.authentication fehlt) und die Einstellung restapi.cafile (wenn ctl.cacert fehlt). Weitere Einzelheiten finden sich unter REST-API-Einstellungen ;
• DCS (z. B. etcd): Verbindung und Authentifizierung gegenüber dem von Patroni verwendeten DCS.

Diese Konfigurationsoptionen können entweder aus Umgebungsvariablen oder aus einer Konfigurationsdatei stammen. Die obigen Abschnitte unter Konfiguration über Umgebungsvariablen bzw. YAML-Konfiguration erläutern, wie die Optionen über Umgebungsvariablen oder eine Konfigurationsdatei gesetzt werden können.

Die Verwendung von Umgebungsvariablen ist unkompliziert. Patronictl liest die Umgebungsvariablen und verwendet ihre Werte.

Bei Verwendung einer Konfigurationsdatei gibt es verschiedene Möglichkeiten, patronictl die gewünschte Datei mitzuteilen. Standardmäßig versucht patronictl , eine Konfigurationsdatei namens patronictl.yaml zu laden. Je nach System wird sie unter einem der folgenden Pfade erwartet:

• Mac OS X: ~/Library/Application Support/patroni
• Mac OS X (POSIX): ~/.patroni
• Unix: ~/.config/patroni
• Unix (POSIX): ~/.patroni
• Windows (mit Roaming): C:\Users\<user>\AppData\Roaming\patroni
• Windows (ohne Roaming): C:\Users\<user>\AppData\Local\patroni

Dieses Verhalten lässt sich auf folgende Weise überschreiben:

• Die Umgebungsvariable PATRONICTL_CONFIG_FILE auf den Pfad einer eigenen Konfigurationsdatei setzen;
• Dem Befehlszeilenargument -c / --config-file von patronictl den Pfad einer eigenen Konfigurationsdatei übergeben.

Verwendung

patronictl bietet mehrere praktische Operationen. Dieser Abschnitt beschreibt sie im Einzelnen.

Vor der Beschreibung der einzelnen Unterbefehle von patronictl folgt eine Übersicht der Befehlszeilenargumente von patronictl selbst:

-c / --config-file
Wie bereits erläutert, wird damit der Pfad zu einer Konfigurationsdatei für patronictl angegeben.

-d / --dcs-url / --dcs
Eine Verbindungszeichenfolge für den von Patroni verwendeten DCS angeben.

Dieses Argument kann die DCS- und namespace-Einstellungen aus der Konfiguration von patronictl überschreiben oder sie festlegen, falls sie dort fehlen.

Der Wert sollte das Format DCS://HOST:PORT/NAMESPACE haben, z. B. etcd3://localhost:2379/service, um eine Verbindung zu etcd v3 auf localhost herzustellen, wobei der Patroni-Cluster im Namensraum service gespeichert ist. Jeder im Argument fehlende Teil wird durch den Wert aus der Konfiguration oder den Standardwert ersetzt.

-k / --insecure
Flag zum Überspringen der Prüfung des SSL-Zertifikats des REST-API-Servers.

Dies ist das Aufrufschema für einen Befehl von patronictl :

patronictl [ { -c | --config-file } CONFIG_FILE ]
  [ { -d | --dcs-url | --dcs } DCS_URL ] 
  [ { -k | --insecure } ]
  SUBCOMMAND

Die folgenden Unterabschnitte beschreiben alle von patronictl implementierten Befehle. Für die Beispiele werden die Konfigurationsdateien aus dem GitHub-Repository von Patroni verwendet (postgres0.yml, postgres1.yml und postgres2.yml).

patronictl demote-cluster

Aufrufschema

demote-cluster
  [ CLUSTER_NAME ]
  [ --host HOST ]
  [ --port PORT ]
  [ --restore-command RESTORE_COMMAND ]
  [ --primary-slot-name PRIMARY_SLOT_NAME ]
  [ --force ]

Beschreibung

patronictl demote-cluster wandelt einen regulären Patroni-Cluster in einen Standby-Cluster um.

Der Befehl ergänzt die dynamische Konfiguration um einen Abschnitt standby_cluster, der aus den angegebenen Verbindungsoptionen für den entfernten Primärserver erstellt wird. Anschließend wartet er, bis der Leader als Standby-Leader läuft. Vor der Konfigurationsänderung gibt er die aktuelle Cluster-Topologie aus. Eine Bestätigung fordert er an, sofern --force nicht verwendet wird.

Mindestens eine der Optionen --host, --port oder --restore-command muss angegeben werden.

Parameter

CLUSTER_NAME: Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--host: Adresse des entfernten Knotens.

--port: Port des entfernten Knotens.

--restore-command: Befehl zur Wiederherstellung von WAL-Einträgen vom entfernten Primärserver.

--primary-slot-name: Name des Replikationsslots auf dem entfernten Knoten, der für die Replikation verwendet werden soll.

--force: Flag zum Überspringen der Bestätigungsabfragen beim Herabstufen des Clusters.

Nützlich für Skripte.

Beispiele

Den Cluster zu einem Standby-Cluster herabstufen, der einem entfernten Primärserver-Endpunkt folgt:

$ patronictl -c postgres0.yml demote-cluster batman --host 192.0.2.10 --port 5432 --primary-slot-name batman --force

patronictl dsn

Aufrufschema

dsn
  [ CLUSTER_NAME ]
  [ { { -r | --role } { leader | primary | standby-leader | replica | standby | any } | { -m | --member } MEMBER_NAME } ]
  [ --group CITUS_GROUP ]

Beschreibung

patronictl dsn ermittelt die Verbindungszeichenfolge für ein Mitglied des Patroni-Clusters.

Wenn mehrere Mitglieder den Parametern dieses Befehls entsprechen, wird eines davon ausgewählt, wobei der Primärserver Vorrang hat.

Parameter

CLUSTER_NAME: Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

-r / --role
Ein Mitglied mit der angegebenen Rolle auswählen.

Die Rolle kann einen der folgenden Werte haben:

• leader: der Leader eines regulären Patroni-Clusters oder eines Patroni-Standby-Clusters; oder
• primary: der Leader eines regulären Patroni-Clusters; oder
• standby-leader: der Leader eines Patroni-Standby-Clusters; oder
• replica: ein Replikat eines Patroni-Clusters; oder
• standby: entspricht replica; oder
• any: beliebige Rolle. Entspricht dem Weglassen dieses Parameters; oder

-m / --member
Ein Mitglied des Clusters mit dem angegebenen Namen auswählen.

MEMBER_NAME ist der Name des Mitglieds.

--group
Ein Mitglied auswählen, das zur angegebenen Citus-Gruppe gehört.

CITUS_GROUP ist die ID der Citus-Gruppe.

Beispiele

DSN des Primärservers abrufen:

$ patronictl -c postgres0.yml dsn batman -r primary
host=127.0.0.1 port=5432

DSN des Knotens namens postgresql1 abrufen:

$ patronictl -c postgres0.yml dsn batman --member postgresql1
host=127.0.0.1 port=5433

patronictl edit-config

Aufrufschema

edit-config
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ { -q | --quiet } ]
  [ { -s | --set } CONFIG="VALUE" [, ... ] ]
  [ { -p | --pg } PG_CONFIG="PG_VALUE" [, ... ] ]
  [ { --apply | --replace } CONFIG_FILE ]
  [ --force ]

Beschreibung

patronictl edit-config ändert die dynamische Konfiguration des Clusters und aktualisiert damit den DCS.

Parameter

CLUSTER_NAME: Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--group
Die dynamische Konfiguration der angegebenen Citus-Gruppe ändern.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration citus.group zu lesen, sofern sie vorhanden ist.

CITUS_GROUP ist die ID der Citus-Gruppe.

-q / --quiet
Flag zum Überspringen der Anzeige des Konfigurations-Diffs.

-s / --set
Eine bestimmte dynamische Konfigurationsoption auf den angegebenen Wert setzen.

CONFIG ist der Pfad der dynamischen Konfiguration im YAML-Baum, dessen Ebenen durch . verbunden sind.

VALUE ist der Wert für CONFIG. Bei null wird CONFIG aus der dynamischen Konfiguration entfernt.

-p / --pg
Eine bestimmte dynamische Postgres-Konfigurationsoption auf den angegebenen Wert setzen.

Dies ist im Wesentlichen eine Kurzform für -s / --set, bei der CONFIG das Präfix postgresql.parameters. erhält.

PG_CONFIG ist der Name der zu setzenden Postgres-Konfigurationsoption.

PG_VALUE ist der Wert für PG_CONFIG. Bei null wird PG_CONFIG aus der dynamischen Konfiguration entfernt.

--apply
Die dynamische Konfiguration aus der angegebenen Datei anwenden.

Dies entspricht der Angabe mehrerer Optionen -s / --set, einer für jede Konfigurationsoption aus CONFIG_FILE.

CONFIG_FILE ist der Pfad zu einer Datei mit der anzuwendenden dynamischen Konfiguration im YAML-Format. Zum Lesen aus stdin den Wert - verwenden.

--replace
Die dynamische Konfiguration im DCS durch die dynamische Konfiguration aus der angegebenen Datei ersetzen.

CONFIG_FILE ist der Pfad zu einer Datei mit der neuen dynamischen Konfiguration im YAML-Format, die wirksam werden soll. Zum Lesen aus stdin den Wert - verwenden.

--force
Flag zum Überspringen der Bestätigungsabfragen beim Ändern der dynamischen Konfiguration.

Nützlich für Skripte.

Beispiele

Den Postgres-GUC max_connections ändern:

patronictl -c postgres0.yml edit-config batman --pg max_connections="150" --force
---
+++
@@ -1,6 +1,8 @@
loop_wait: 10
maximum_lag_on_failover: 1048576
postgresql:
+  parameters:
+    max_connections: 150
  pg_hba:
  - host replication replicator 127.0.0.1/32 md5
  - host all all 0.0.0.0/0 md5

Configuration changed

Die Einstellungen loop_wait und ttl ändern:

patronictl -c postgres0.yml edit-config batman --set loop_wait="15" --set ttl="45" --force
---
+++
@@ -1,4 +1,4 @@
-loop_wait: 10
+loop_wait: 15
maximum_lag_on_failover: 1048576
postgresql:
  pg_hba:
@@ -6,4 +6,4 @@
  - host all all 0.0.0.0/0 md5
  use_pg_rewind: true
retry_timeout: 10
-ttl: 30
+ttl: 45

Configuration changed

Die Einstellung maximum_lag_on_failover aus der dynamischen Konfiguration entfernen:

patronictl -c postgres0.yml edit-config batman --set maximum_lag_on_failover="null" --force
---
+++
@@ -1,5 +1,4 @@
loop_wait: 10
-maximum_lag_on_failover: 1048576
postgresql:
  pg_hba:
  - host replication replicator 127.0.0.1/32 md5

Configuration changed

patronictl failover

Aufrufschema

failover
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  --candidate CANDIDATE_NAME
  [ --force ]

Beschreibung

patronictl failover führt ein manuelles Failover im Cluster durch.

Der Befehl ist für nicht funktionsfähige Cluster vorgesehen, z. B. wenn:

• kein Leader vorhanden ist; oder
• in einem synchronen Cluster kein synchroner Standby verfügbar ist.

Er ermöglicht bei aktiviertem synchronem Modus auch ein Failover zu einem asynchronen Knoten.

Parameter

CLUSTER_NAME: Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--group
Ein Failover in der angegebenen Citus-Gruppe durchführen.

CITUS_GROUP ist die ID der Citus-Gruppe.

--candidate
Der Knoten, der beim Failover hochgestuft werden soll.

CANDIDATE_NAME ist der Name des hochzustufenden Knotens.

--force
Flag zum Überspringen der Bestätigungsabfragen bei der Durchführung des Failovers.

Nützlich für Skripte.

Beispiele

Ein Failover zum Knoten postgresql2 durchführen:

$ patronictl -c postgres0.yml failover batman --candidate postgresql2 --force
Current cluster topology
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  3 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  3 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  3 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
2023-09-12 11:52:27.50978 Successfully failed over to "postgresql2"
+ Cluster: batman (7277694203142172922) -+---------+----+-------------+---------+------------+---------+
| Member      | Host           | Role    | State   | TL | Receive LSN |     Lag | Replay LSN |     Lag |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+
| postgresql0 | 127.0.0.1:5432 | Replica | stopped |    |     unknown | unknown |    unknown | unknown |
| postgresql1 | 127.0.0.1:5433 | Replica | running |  3 |   0/4000188 |       0 |  0/4000188 |       0 |
| postgresql2 | 127.0.0.1:5434 | Leader  | running |  3 |             |         |            |         |
+-------------+----------------+---------+---------+----+-------------+---------+------------+---------+

patronictl flush

Aufrufschema

flush
  CLUSTER_NAME
  [ MEMBER_NAME [, ... ] ]
  { restart | switchover }
  [ --group CITUS_GROUP ]
  [ { -r | --role } { leader | primary | standby-leader | replica | standby | any } ]
  [ --force ]

Beschreibung

patronictl flush verwirft geplante Ereignisse, sofern vorhanden.

Parameter

CLUSTER_NAME
Name des Patroni-Clusters.

MEMBER_NAME
Geplante Ereignisse für die angegebenen Patroni-Mitglieder verwerfen.

Es können mehrere Mitglieder angegeben werden. Ohne Angabe von Mitgliedern werden alle berücksichtigt.

restart
Geplante Neustarts verwerfen.

switchover
Geplanten Switchover verwerfen.

--group
Geplante Ereignisse der angegebenen Citus-Gruppe verwerfen.

CITUS_GROUP ist die ID der Citus-Gruppe.

-r / --role
Geplante Ereignisse für Mitglieder mit der angegebenen Rolle verwerfen.

Die Rolle kann einen der folgenden Werte haben:

• leader: der Leader eines regulären Patroni-Clusters oder eines Patroni-Standby-Clusters; oder
• primary: der Leader eines regulären Patroni-Clusters; oder
• standby-leader: der Leader eines Patroni-Standby-Clusters; oder
• replica: ein Replikat eines Patroni-Clusters; oder
• standby: entspricht replica; oder
• any: beliebige Rolle. Entspricht dem Weglassen dieses Parameters.

--force
Flag zum Überspringen der Bestätigungsabfragen beim Verwerfen geplanter Ereignisse.

Nützlich für Skripte.

Beispiele

Einen geplanten Switchover verwerfen:

$ patronictl -c postgres0.yml flush batman switchover --force
Success: scheduled switchover deleted

Den geplanten Neustart aller Standby-Knoten verwerfen:

$ patronictl -c postgres0.yml flush batman restart -r replica --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+---------------------------+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag | Scheduled restart         |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     | 2025-03-23T18:00:00-03:00 |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
Success: flush scheduled restart for member postgresql1
Success: flush scheduled restart for member postgresql2

Den geplanten Neustart der Knoten postgresql0 und postgresql1 verwerfen:

$ patronictl -c postgres0.yml flush batman postgresql0 postgresql1 restart --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+---------------------------+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag | Scheduled restart         |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     | 2025-03-23T18:00:00-03:00 |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/4000400 |   0 |  0/4000400 |   0 | 2025-03-23T18:00:00-03:00 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+---------------------------+
Success: flush scheduled restart for member postgresql0
Success: flush scheduled restart for member postgresql1

patronictl history

Aufrufschema

history
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ { -f | --format } { pretty | tsv | json | yaml } ]

Beschreibung

patronictl history zeigt die Historie der Failover- und Switchover-Ereignisse des Clusters, sofern vorhanden.

Die Ausgabe enthält folgende Informationen:

TL
Postgres-Timeline, auf der das Ereignis auftrat.

LSN
Postgres-LSN, an der das Ereignis auftrat.

Reason
Grund aus der Postgres-Datei .history.

Timestamp
Zeitpunkt des Ereignisses.

New Leader
Patroni-Mitglied, das bei diesem Ereignis hochgestuft wurde.

Parameter

CLUSTER_NAME
Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--group
Die Ereignishistorie der angegebenen Citus-Gruppe anzeigen.

CITUS_GROUP ist die ID der Citus-Gruppe.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration citus.group zu lesen, sofern sie vorhanden ist.

-f / --format
Formatierung der Ereignisliste in der Ausgabe.

Das Format kann einen der folgenden Werte haben:

• pretty: gibt die Historie als formatierte Tabelle aus; oder
• tsv: gibt die Historie tabellarisch aus, mit durch \t getrennten Spalten; oder
• json: gibt die Historie im JSON-Format aus; oder
• yaml: gibt die Historie im YAML-Format aus.

Der Standardwert ist pretty.

Beispiele

Die Ereignishistorie anzeigen:

$ patronictl -c postgres0.yml history batman
+----+----------+------------------------------+----------------------------------+-------------+
| TL |      LSN | Reason                       | Timestamp                        | New Leader  |
+----+----------+------------------------------+----------------------------------+-------------+
|  1 | 24392648 | no recovery target specified | 2023-09-11T22:11:27.125527+00:00 | postgresql0 |
|  2 | 50331864 | no recovery target specified | 2023-09-12T11:34:03.148097+00:00 | postgresql0 |
|  3 | 83886704 | no recovery target specified | 2023-09-12T11:52:26.948134+00:00 | postgresql2 |
|  4 | 83887280 | no recovery target specified | 2023-09-12T11:53:09.620136+00:00 | postgresql0 |
+----+----------+------------------------------+----------------------------------+-------------+

Die Ereignishistorie im YAML-Format anzeigen:

$ patronictl -c postgres0.yml history batman -f yaml
- LSN: 24392648
  New Leader: postgresql0
  Reason: no recovery target specified
  TL: 1
  Timestamp: '2023-09-11T22:11:27.125527+00:00'
- LSN: 50331864
  New Leader: postgresql0
  Reason: no recovery target specified
  TL: 2
  Timestamp: '2023-09-12T11:34:03.148097+00:00'
- LSN: 83886704
  New Leader: postgresql2
  Reason: no recovery target specified
  TL: 3
  Timestamp: '2023-09-12T11:52:26.948134+00:00'
- LSN: 83887280
  New Leader: postgresql0
  Reason: no recovery target specified
  TL: 4
  Timestamp: '2023-09-12T11:53:09.620136+00:00'

patronictl list

Aufrufschema

list
  [ CLUSTER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]
  [ { -e | --extended } ]
  [ { -t | --timestamp } ]
  [ { -f | --format } { pretty | tsv | json | yaml } ]
  [ { -W | { -w | --watch } TIME } ]

Beschreibung

patronictl list zeigt Informationen zum Patroni-Cluster und seinen Mitgliedern.

Die Ausgabe enthält folgende Informationen:

Cluster
Name des Patroni-Clusters.

Member
Name des Patroni-Mitglieds.

Host
Host, auf dem sich das Mitglied befindet.

Role
Aktuelle Rolle des Mitglieds.

Mögliche Werte sind:

• Leader: der aktuelle Leader eines regulären Patroni-Clusters; oder
• Standby Leader: der aktuelle Leader eines Patroni-Standby-Clusters; oder
• Sync Standby: ein synchroner Standby eines Patroni-Clusters mit aktiviertem synchronem Modus; oder
• Replica: ein regulärer Standby eines Patroni-Clusters.

State
Aktueller Zustand von Postgres im Patroni-Mitglied.

Einige Beispiele für mögliche Zustände:

• running: wenn Postgres derzeit läuft;
• streaming: bei einem Replikat, wenn Postgres derzeit WAL per Streaming vom Primärserver empfängt;
• in archive recovery: bei einem Replikat, wenn Postgres derzeit WAL aus dem Archiv abruft;
• stopped: wenn Postgres heruntergefahren wurde;
• crashed: wenn Postgres abgestürzt ist.

TL
Aktuelle Postgres-Timeline im Patroni-Mitglied.

Receive LSN
Die letzte Write-Ahead-Log-Position, die das Mitglied per Streaming-Replikation empfangen und auf den Datenträger synchronisiert hat (pg_catalog.pg_last_(xlog|wal)_receive_(location|lsn)()).

Receive Lag
Replikationsrückstand zwischen der Position Receive LSN des Mitglieds und seiner Replikationsquelle in MB.

Replay LSN
Die letzte Write-Ahead-Log-Position, die bei der Recovery des Mitglieds wiedergegeben wurde (pg_catalog.pg_last_(xlog|wal)_replay_(location|lsn)()).

Replay Lag
Replikationsrückstand zwischen der Position Replay LSN des Mitglieds und seiner Replikationsquelle in MB.

Darüber hinaus kann die Ausgabe folgende Informationen enthalten:

System identifier
Postgres-Systemkennung.

Group
ID der Citus-Gruppe.

Pending restart
* zeigt an, dass der Knoten einen Neustart benötigt, damit bestimmte Postgres-Konfigurationseinstellungen wirksam werden. Ein leerer Wert zeigt an, dass der Knoten keinen Neustart benötigt.

Scheduled restart
Zeitstempel des geplanten Neustarts der vom Patroni-Mitglied verwalteten Postgres-Instanz. Ein leerer Wert zeigt an, dass für das Mitglied kein Neustart geplant ist.

Tags
Enthält die für das Patroni-Mitglied gesetzten Tags. Ein leerer Wert zeigt an, dass entweder keine Tags konfiguriert wurden oder diese auf die Standardwerte gesetzt sind.

Scheduled switchover
Zeitstempel des geplanten Switchovers für den Patroni-Cluster, sofern vorhanden.

Maintenance mode

Ob die Cluster-Überwachung derzeit pausiert ist.

Hinweis

Wird am Tabellenende angezeigt.

Wird nur angezeigt, wenn der Cluster pausiert ist und das Ausgabeformat pretty verwendet wird.

Parameter

CLUSTER_NAME
Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--group
Informationen zu Mitgliedern der angegebenen Citus-Gruppe anzeigen.

CITUS_GROUP ist die ID der Citus-Gruppe.

-e / --extended
Erweiterte Informationen anzeigen.

Die Attribute Pending restart, Scheduled restart und Tags auch dann anzeigen, wenn ihr Wert leer ist.

-t / --timestamp
Vor den Informationen zum Cluster und seinen Mitgliedern einen Zeitstempel ausgeben.

-f / --format
Formatierung der Liste der Clustermitglieder in der Ausgabe.

Das Format kann einen der folgenden Werte haben:

• pretty: gibt die Clustermitglieder als formatierte Tabelle aus; oder
• tsv: gibt die Clustermitglieder tabellarisch aus, mit durch \t getrennten Spalten; oder
• json: gibt die Clustermitglieder im JSON-Format aus; oder
• yaml: gibt die Clustermitglieder im YAML-Format aus.

Der Standardwert ist pretty.

-W
Informationen automatisch alle 2 Sekunden aktualisieren.

-w / --watch
Informationen automatisch im angegebenen Intervall aktualisieren.

TIME ist das Aktualisierungsintervall in Sekunden.

Beispiele

Informationen zum Cluster als formatierte Tabelle anzeigen:

$ patronictl -c postgres0.yml list batman
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+

Informationen zum Cluster als formatierte Tabelle mit erweiterten Spalten anzeigen:

$ patronictl -c postgres0.yml list batman -e
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+-----------------+------------------------+-------------------+------+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag | Pending restart | Pending restart reason | Scheduled restart | Tags |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+-----------------+------------------------+-------------------+------+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |                 |                        |                   |      |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |                 |                        |                   |      |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |                 |                        |                   |      |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+-----------------+------------------------+-------------------+------+

Informationen zum Cluster im YAML-Format mit Ausführungszeitstempel anzeigen:

$ patronictl -c postgres0.yml list batman -f yaml -t
2023-09-12 13:30:48
- Cluster: batman
  Host: 127.0.0.1:5432
  Member: postgresql0
  Role: Leader
  State: running
  TL: 5
- Cluster: batman
  Host: 127.0.0.1:5433
  Receive LSN: 0/40004E8
  Receive Lag: 0
  Replay LSN: 0/40004E8
  Replay Lag: 0
  Member: postgresql1
  Role: Replica
  State: streaming
  TL: 5
- Cluster: batman
  Host: 127.0.0.1:5434
  Receive LSN: 0/40004E8
  Receive Lag: 0
  Replay LSN: 0/40004E8
  Replay Lag: 0
  Member: postgresql2
  Role: Replica
  State: streaming
  TL: 5

patronictl pause

Aufrufschema

pause
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ --wait ]

Beschreibung

patronictl pause versetzt den Patroni-Cluster vorübergehend in den Wartungsmodus und deaktiviert automatisches Failover.

Parameter

CLUSTER_NAME
Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--group
Die angegebene Citus-Gruppe pausieren.

CITUS_GROUP ist die ID der Citus-Gruppe.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration citus.group zu lesen, sofern sie vorhanden ist.

--wait
Warten, bis alle Patroni-Mitglieder pausiert sind, bevor die Kontrolle an den Aufrufer zurückgegeben wird.

Beispiele

Den Cluster in den Wartungsmodus versetzen und warten, bis alle Knoten pausiert sind:

$ patronictl -c postgres0.yml pause batman --wait
'pause' request sent, waiting until it is recognized by all nodes
Success: cluster management is paused

patronictl promote-cluster

Aufrufschema

promote-cluster
  [ CLUSTER_NAME ]
  [ --force ]

Beschreibung

patronictl promote-cluster wandelt einen Standby-Cluster in einen regulären Patroni-Cluster um.

Der Befehl entfernt den Abschnitt standby_cluster aus der dynamischen Konfiguration und wartet, bis der Leader als Primärserver läuft. Vor der Konfigurationsänderung gibt er die aktuelle Cluster-Topologie aus. Eine Bestätigung fordert er an, sofern --force nicht verwendet wird.

Parameter

CLUSTER_NAME: Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--force: Flag zum Überspringen der Bestätigungsabfragen beim Hochstufen des Clusters.

Nützlich für Skripte.

Beispiele

Den Standby-Cluster hochstufen, sodass er als regulärer Patroni-Cluster läuft:

$ patronictl -c postgres0.yml promote-cluster batman --force

patronictl query

Aufrufschema

query
  [ CLUSTER_NAME ]
  [ --group CITUS_GROUP ]
  [ { { -r | --role } { leader | primary | standby-leader | replica | standby | any } | { -m | --member } MEMBER_NAME } ]
  [ { -d | --dbname } DBNAME ]
  [ { -U | --username } USERNAME ]
  [ --password ]
  [ --format { pretty | tsv | json | yaml } ]
  [ { { -f | --file } FILE_NAME | { -c | --command } SQL_COMMAND } ]
  [ --delimiter ]
  [ { -W | { -w | --watch } TIME } ]

Beschreibung

patronictl query führt einen SQL-Befehl oder ein Skript auf einem Mitglied des Patroni-Clusters aus.

Parameter

CLUSTER_NAME
Name des Patroni-Clusters.

Falls nicht angegeben, versucht patronictl , den Wert aus der Konfiguration scope zu lesen, sofern sie vorhanden ist.

--group
Die angegebene Citus-Gruppe abfragen.

CITUS_GROUP ist die ID der Citus-Gruppe.

-r / --role
Ein Mitglied mit der angegebenen Rolle auswählen.

Die Rolle kann einen der folgenden Werte haben:

• leader: der Leader eines regulären Patroni-Clusters oder eines Patroni-Standby-Clusters; oder
• primary: der Leader eines regulären Patroni-Clusters; oder
• standby-leader: der Leader eines Patroni-Standby-Clusters; oder
• replica: ein Replikat eines Patroni-Clusters; oder
• standby: entspricht replica; oder
• any: beliebige Rolle. Entspricht dem Weglassen dieses Parameters.

-m / --member
Ein Mitglied mit dem angegebenen Namen auswählen.

MEMBER_NAME ist der Name des auszuwählenden Mitglieds.

-d / --dbname
Datenbank, zu der eine Verbindung hergestellt und auf der die Abfrage ausgeführt wird.

DBNAME ist der Name der Datenbank. Ohne Angabe wird USERNAME verwendet.

-U / --username
Benutzer für die Verbindung zur Datenbank.

USERNAME ist der Name des Benutzers. Ohne Angabe wird der Betriebssystembenutzer verwendet, der patronictl query ausführt.

--password
Das Passwort des Benutzers abfragen, der die Verbindung herstellt.

Da Patroni libpq verwendet, kann alternativ eine Datei ~/.pgpass erstellt oder die Umgebungsvariable PGPASSWORD gesetzt werden.

--format
Formatierung der Abfrageausgabe.

Das Format kann einen der folgenden Werte haben:

• pretty: gibt das Abfrageergebnis als formatierte Tabelle aus; oder
• tsv: gibt das Abfrageergebnis tabellarisch aus, mit durch \t getrennten Spalten; oder
• json: gibt das Abfrageergebnis im JSON-Format aus; oder
• yaml: gibt das Abfrageergebnis im YAML-Format aus.

Der Standardwert ist tsv.

-f / --file
Eine Datei als Quelle der auszuführenden Abfragebefehle verwenden.

FILE_NAME ist der Pfad zur Quelldatei.

-c / --command
Den angegebenen SQL-Befehl als Abfrage ausführen.

SQL_COMMAND ist der auszuführende SQL-Befehl.

--delimiter
Das Trennzeichen für die Ausgabe im Format tsv; ohne Angabe wird \t verwendet.

-W
Die Abfrage automatisch alle 2 Sekunden erneut ausführen.

-w / --watch
Die Abfrage automatisch im angegebenen Intervall erneut ausführen.

TIME ist das Intervall zwischen den Ausführungen in Sekunden.

Beispiele

Einen SQL-Befehl als Benutzer postgres ausführen und dessen Passwort abfragen:

$ patronictl -c postgres0.yml query batman -U postgres --password -c "SELECT now()"
Password:
now
2023-09-12 18:10:53.228084+00:00

Einen SQL-Befehl als Benutzer postgres ausführen und das Passwort aus der Umgebungsvariable von libpq beziehen:

$ PGPASSWORD=patroni patronictl -c postgres0.yml query batman -U postgres -c "SELECT now()"
now
2023-09-12 18:11:37.639500+00:00

Einen SQL-Befehl alle 2 Sekunden ausführen und das Ergebnis im Format pretty ausgeben:

$ patronictl -c postgres0.yml query batman -c "SELECT now()" --format pretty -W
+----------------------------------+
| now                              |
+----------------------------------+
| 2023-09-12 18:12:16.716235+00:00 |
+----------------------------------+
+----------------------------------+
| now                              |
+----------------------------------+
| 2023-09-12 18:12:18.732645+00:00 |
+----------------------------------+
+----------------------------------+
| now                              |
+----------------------------------+
| 2023-09-12 18:12:20.750573+00:00 |
+----------------------------------+

Einen SQL-Befehl auf der Datenbank test ausführen und das Ergebnis im YAML-Format ausgeben:

$ patronictl -c postgres0.yml query batman -d test -c "SELECT now() AS column_1, 'test' AS column_2" --format yaml
- column_1: 2023-09-12 18:14:22.052060+00:00
  column_2: test

Einen SQL-Befehl auf dem Mitglied postgresql2 ausführen:

$ patronictl -c postgres0.yml query batman -m postgresql2 -c "SHOW port"
port
5434

Einen SQL-Befehl auf einem beliebigen Standby ausführen:

$ patronictl -c postgres0.yml query batman -r replica -c "SHOW port"
port
5433

patronictl reinit

Aufrufschema

reinit
  CLUSTER_NAME
  [ MEMBER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]
  [ --wait ]
  [ --force ]
  [ --from-leader ]

Beschreibung

patronictl reinit erstellt eine Postgres-Standby-Instanz neu, die von einem Replikatmitglied des Patroni-Clusters verwaltet wird.

Parameter

CLUSTER_NAME
Name des Patroni-Clusters.

MEMBER_NAME
Name des Replikatmitglieds, dessen Postgres-Instanz neu erstellt werden soll.

Es können mehrere Replikatmitglieder angegeben werden. Ohne Angabe von Mitgliedern führt der Befehl keine Aktion aus.

--group
Ein Replikatmitglied der angegebenen Citus-Gruppe neu erstellen.

CITUS_GROUP ist die ID der Citus-Gruppe.

--wait
Warten, bis die Neuinitialisierung der Postgres-Standby-Knoten abgeschlossen ist.

--force
Flag zum Überspringen der Bestätigungsabfragen beim Neuerstellen von Postgres-Standby-Instanzen.

Nützlich für Skripte.

--from-leader
Flag zum direkten Beziehen des Basis-Backups vom Leader.

Beispiele

Das Neuerstellen aller Replikatmitglieder des Patroni-Clusters anfordern und die Kontrolle sofort an den Aufrufer zurückgeben:

$ patronictl -c postgres0.yml reinit batman postgresql1 postgresql2 --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reinitialize for member postgresql1
Success: reinitialize for member postgresql2

Das Neuerstellen von postgresql2 anfordern und auf den Abschluss warten:

$ patronictl -c postgres0.yml reinit batman postgresql2 --wait --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reinitialize for member postgresql2
Waiting for reinitialize to complete on: postgresql2
Reinitialize is completed on: postgresql2

Das Neuerstellen von postgresql2 anfordern und das Basis-Backup direkt vom Leader beziehen:

$ patronictl -c postgres0.yml reinit batman postgresql2 --from-leader
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Success: reinitialize for member postgresql2

patronictl reload

Aufrufschema

reload
  CLUSTER_NAME
  [ MEMBER_NAME [, ... ] ]
  [ --group CITUS_GROUP ]
  [ { -r | --role } { leader | primary | standby-leader | replica | standby | any } ]
  [ --force ]

Beschreibung

patronictl reload fordert ein Neuladen der lokalen Konfiguration für ein oder mehrere Patroni-Mitglieder an.

Dabei wird auf der verwalteten Postgres-Instanz auch pg_ctl reload ausgelöst, selbst wenn sich nichts geändert hat.

Parameter

CLUSTER_NAME
Name des Patroni-Clusters.

MEMBER_NAME
Das Neuladen der lokalen Konfiguration für die angegebenen Patroni-Mitglieder anfordern.

Es können mehrere Mitglieder angegeben werden. Ohne Angabe von Mitgliedern werden alle berücksichtigt.

--group
Ein Neuladen der Mitglieder der angegebenen Citus-Gruppe anfordern.

CITUS_GROUP ist die ID der Citus-Gruppe.

-r / --role
Mitglieder mit der angegebenen Rolle auswählen.

Die Rolle kann einen der folgenden Werte haben:

• leader: der Leader eines regulären Patroni-Clusters oder eines Patroni-Standby-Clusters; oder
• primary: der Leader eines regulären Patroni-Clusters; oder
• standby-leader: der Leader eines Patroni-Standby-Clusters; oder
• replica: ein Replikat eines Patroni-Clusters; oder
• standby: entspricht replica; oder
• any: beliebige Rolle. Entspricht dem Weglassen dieses Parameters.

--force
Flag zum Überspringen der Bestätigungsabfragen beim Anfordern eines Neuladens der lokalen Konfiguration.

Nützlich für Skripte.

Beispiele

Das Neuladen der lokalen Konfiguration aller Mitglieder des Patroni-Clusters anfordern:

$ patronictl -c postgres0.yml reload batman --force
+ Cluster: batman (7277694203142172922) -+-----------+----+-------------+-----+------------+-----+
| Member      | Host           | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
| postgresql0 | 127.0.0.1:5432 | Leader  | running   |  5 |             |     |            |     |
| postgresql1 | 127.0.0.1:5433 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
| postgresql2 | 127.0.0.1:5434 | Replica | streaming |  5 |   0/40004E8 |   0 |  0/40004E8 |   0 |
+-------------+----------------+---------+-----------+----+-------------+-----+------------+-----+
Reload request received for member postgresql0 and will be processed within 10 seconds
Reload request received for member postgresql1 and will be processed within 10 seconds
Reload request received for member postgresql2 and will be processed within 10 seconds