pg_failover_readiness — Kann ich jetzt sicher ein Failover machen? — Blog

Was macht dieses Tool?

pg_failover_readiness bewertet die sofortige Failover-Fähigkeit eines PostgreSQL-Clusters mit einem gewichteten Score von 0 bis 100. Das Tool fragt den Replikationsstatus sowohl auf dem Primary als auch auf den Replicas ab und liefert eine klare can_failover-Antwort: Ja oder Nein.

Die gewichtete Formel berücksichtigt fünf Faktoren:

Replication Lag < 1 MB (30 Punkte) — Der kritischste Faktor: Wie aktuell ist die Replica?
Sync State = streaming (25 Punkte) — Ist die Replikation aktiv und im Streaming-Modus?
Slot Active = true (20 Punkte) — Ist der Replication Slot aktiv und hält WAL-Segmente zurück?
WAL Receiver Status = streaming (15 Punkte) — Empfängt die Replica aktiv WAL-Daten?
Replica Count ≥ 1 (10 Punkte) — Existiert mindestens eine Replica?

Wie wird es aufgerufen?

Konfiguration

DR-Tools arbeiten konfigurationsbasiert. Statt einer direkten Datenbankverbindung werden System und Umgebung aus der DR-Konfiguration gelesen — so können mehrere Cluster-Paare verwaltet werden:

● ● ● Claude CLI — DR-Konfiguration

claude> Zeig mir den DR-Status für hubport

▶ Calling tools...
→ pg_cnpg_dr_readiness { "system": "hubport", "environment": "lab" }

// Liest primary + replica aus ~/.config/mcp-postgres-enterprise/dr/cnpg-dr.json
// Primary: k8s-primary/mcp-test/mcp-test-cnpg (2 Instanzen)
// Replica: k8s-replica/mcp-test/mcp-test-cnpg-replica (1 Instanz)

Claude CLI (natürliche Sprache)

● ● ● Claude CLI — Failover-Analyse

claude> Kann ich jetzt sicher ein Failover machen?

▶ Calling tools...
→ pg_failover_readiness {}

Failover-Score: 92/100 — Status: READY
✓ can_failover: true

Primary: db-primary-1

Replicas:
db-primary-2
Lag: 524 KB (0.2s) | Sync: streaming | Eligible: ✓

MCP Protocol (programmatisch)

● ● ● MCP Protocol — Failover-Analyse

// Programmatic invocation via MCP SDK
const result = await client.callTool("pg_failover_readiness", {});

// Response:
{
"score": 92,
"status": "READY",
"primary": "db-primary-1",
"replicas": [
    {
      "name": "db-primary-2",
      "lag_bytes": 524288,
      "lag_seconds": 0.2,
      "sync_state": "streaming",
      "eligible": true
    }
],
"can_failover": true
}

Was passiert unter der Haube?

Das Tool führt drei SQL-Queries aus — eine auf dem Primary und zwei auf der Replica:

1. Replikationsstatus (Primary)

-- Replikationsstatus aller Replicas vom Primary
SELECT client_addr, application_name, state, sync_state, sent_lsn, write_lsn, flush_lsn, replay_lsn, sent_lsn - replay_lsn AS lag_bytes FROM pg_stat_replication;

2. WAL Receiver Status (Replica)

-- WAL-Empfangsstatus auf der Replica
SELECT status, received_lsn, latest_end_lsn, last_msg_send_time, last_msg_receipt_time, conninfo FROM pg_stat_wal_receiver;

3. Replication Slots (Primary)

-- Physische Replication Slots und ihr Status
SELECT slot_name, active, restart_lsn, confirmed_flush_lsn FROM pg_replication_slots WHERE slot_type = 'physical';

Das Tool kombiniert die Ergebnisse aller drei Queries, um den gewichteten Score zu berechnen. Der can_failover-Boolean wird auf true gesetzt, wenn mindestens eine Replica mit eligible: true existiert und der Gesamtscore ≥ 70 ist.

Praxis-Tipp: Ein sync_state von async statt streaming ist kein Fehler — es bedeutet nur, dass die Replikation asynchron konfiguriert ist. Bei einem Failover kann es in diesem Fall zu minimalem Datenverlust kommen (typisch: letzte Transaktion).

Ausgabe im Detail

score — Gewichteter Gesamtscore von 0 bis 100
status — READY (≥ 80), AT-RISK (50–79) oder NOT-READY (< 50)
primary — Name der aktuellen Primary-Instanz
replicas — Array der Replicas mit:
- name — Instanzname
- lag_bytes — Replikations-Lag in Bytes
- lag_seconds — Geschätzter Lag in Sekunden
- sync_state — streaming, async, catchup oder disconnected
- eligible — Boolean, ob diese Replica als Failover-Ziel geeignet ist
can_failover — Boolean: Ist ein sicheres Failover jetzt möglich?

Was testet die Testsuite?

Die Testsuite validiert pg_failover_readiness gegen einen CNPG-Cluster mit 2 Instanzen (1 Primary + 1 Replica) im Streaming-Replikationsmodus:

● ● ● vitest run — Testsuite

✓ pg_failover_readiness > returns score and status
✓ pg_failover_readiness > includes replica details
✓ pg_failover_readiness > can_failover boolean present

Test Files 1 passed (1)
Tests 3 passed (3)
Duration 687ms

Testdaten-Szenario

Die Testumgebung besteht aus:

CNPG-Cluster — 2 Instanzen (db-primary-1 als Primary, db-primary-2 als Replica)
Streaming Replication — Asynchrone physische Replikation über WAL
Replication Slot — Physischer Slot für WAL-Retention
Seed-Daten — Testdatenbank mit aktivem Schreibverkehr für messbaren Lag

Die Tests validieren, dass:

Das Ergebnis einen score und status enthält
Die Replica-Details (Name, Lag, Sync-State) im replicas-Array vorhanden sind
Das can_failover-Feld als Boolean zurückgegeben wird

Zusammenfassung

3 Queries

Datenquelle

Gewichtete Faktoren

Tests

read-only

Typ

pg_failover_readiness beantwortet die wichtigste Frage in einer HA-Umgebung: Kann ich jetzt sicher ein Failover durchführen? Es ersetzt das manuelle Prüfen von pg_stat_replication, pg_stat_wal_receiver und pg_replication_slots durch einen einzigen gewichteten Score mit klarer Ja/Nein-Antwort.

In Kombination mit pg_cnpg_dr_readiness (→ Cross-Cluster-DR) und pg_cnpg_switchover (→ tatsächliches Failover) bildet es den Kern des /pg-dr Workflow-Skills.

pg_failover_readiness — Kann ich jetzt sicher ein Failover machen?