Patroni PostgreSQL High Availability Services
In short: Patroni is an open-source PostgreSQL high-availability template that coordinates members through a distributed configuration store. A DBRE design combines its leader lock, PostgreSQL replication modes, watchdog options, REST health endpoints, connection routing, backups, and failure tests. DBA responsibilities remain essential for data integrity, upgrades, recovery, and production change control.
JusDB database SREs design, implement, test, and document Patroni around the workload's actual recovery objectives, platform, failure domains, and operating model.
What is Patroni?
Patroni manages PostgreSQL members through a control loop. A supported DCS stores the leader lock and dynamic configuration; a member that can safely hold the lock operates as primary, while eligible replicas can be promoted after a failure. REST endpoints expose role and health information for management and routing.
Patroni is one layer in an HA system. PostgreSQL replication, durable backups, restore testing, client routing, observability, capacity, security, watchdog or fencing controls, and human escalation remain separate design responsibilities.
How Patroni works in production
Production behavior emerges from the combined PostgreSQL, Patroni, DCS, network, storage, proxy, and application configuration. Each layer needs explicit ownership and failure evidence.
DCS and Leader Lock
Select and harden a supported DCS, define failure domains, and validate leader-lock behavior during loss and partitions.
Failover and Switchover
Set candidate eligibility, lag limits, timing, synchronous behavior, and client-routing gates from recovery objectives.
REST API and patronictl
Use documented health and control interfaces with authentication, TLS, authorization, audit, and runbook boundaries.
Watchdog and Fencing
Evaluate Patroni watchdog modes with infrastructure fencing and prove safety through network and host-failure tests.
Dynamic Configuration
Manage cluster-wide Patroni and PostgreSQL settings through controlled changes, validation, and rollback records.
Hosts or Kubernetes
Design Patroni for the actual compute platform, storage, network, disruption, scheduling, and ownership model.
Patroni vs repmgr
Both can support PostgreSQL replication operations, but their coordination and control models differ. The choice should follow recovery objectives, failure testing, dependency ownership, platform constraints, and team operating practices. Review the dedicated repmgr service page for its current behavior and risks.
| Criterion | Patroni | repmgr |
|---|---|---|
| Coordination model | Leader lock and dynamic configuration in a supported DCS | Cluster metadata in PostgreSQL; no external consensus DCS |
| Automation | Continuous member control loop and optional automatic failover | CLI operations plus optional repmgrd monitoring and failover |
| Management interface | REST API and patronictl | repmgr CLI, repmgrd, and PostgreSQL metadata |
| Fencing model | DCS lock with optional Linux watchdog; infrastructure controls still matter | External fencing and topology controls remain the operator's responsibility |
| Deployment fit | Hosts, VMs, containers, and Kubernetes with a supported coordination design | Commonly used on hosts or VMs with PostgreSQL streaming replication |
| Decision basis | DCS ownership, automation, routing, and failure behavior | Dependency footprint, operational control, and acceptable failover model |
Patroni architecture decision criteria
Patroni may fit when
- • The team can own a supported DCS or Kubernetes coordination design.
- • REST health endpoints and a continuous HA control loop fit the routing model.
- • Automatic failover is required and its safety can be tested across network partitions.
- • PostgreSQL replication, backups, fencing, monitoring, and application retries have named owners.
Reassess the design when
- • DCS deployment, upgrades, quorum behavior, and incident response have no clear owner.
- • Recovery objectives are assumed but have not been measured with realistic failures.
- • The application cannot reconnect, retry, or tolerate the tested role-transition behavior.
- • A platform operator already owns HA and exposes a different supported control plane.
Patroni on Kubernetes
Patroni can use Kubernetes API objects for coordination, so a separate Patroni-managed etcd deployment is not inherently required for that mode. The complete HA result still depends on the chosen operator or manifests, storage and volume topology, scheduling and disruption controls, service routing, permissions, backups, and upgrade procedures. We review the supported control plane instead of assuming all PostgreSQL operators use Patroni.
Patroni REST API: operational endpoints
Patroni's REST API supports health checks, cluster inspection, and controlled operations. Exact responses and payloads follow the installed Patroni version. Configure authentication and TLS where the interface crosses a trust boundary, and restrict change endpoints to approved operators.
| Endpoint | Use | Operational note |
|---|---|---|
| GET /cluster | Inspect cluster members and state | Useful for diagnosis; validate fields against the deployed version |
| GET /primary | Primary-role health check | Suitable for routing only after failure and draining tests |
| GET /replica | Replica-role health check | Optional query parameters can constrain acceptable replica state |
| GET /metrics | Prometheus-format Patroni metrics | Combine with PostgreSQL, DCS, host, proxy, and backup telemetry |
| POST /switchover | Request a controlled role change | Requires candidate, routing, rollback, and client-impact gates |
| PATCH /config | Change dynamic configuration | Use review, audit, validation, and rollback controls |
JusDB Patroni consulting and implementation
The scope is built around recovery objectives and measured failure behavior—not a preselected node count, DCS product, routing layer, or failover duration.
Requirements and architecture
Map availability and data-loss objectives, topology, failure domains, workloads, backups, routing, dependencies, and ownership.
DCS deployment and hardening
Configure supported coordination, authentication, TLS, access, observability, backup where applicable, and quorum-loss tests.
PostgreSQL replication and safety
Define asynchronous or synchronous behavior, candidate rules, lag controls, rewind or reinitialization paths, and fencing.
Connection routing
Validate primary and replica health endpoints, proxy behavior, draining, retries, pools, DNS, and application reconnection.
Failure testing and runbooks
Exercise process, host, network, DCS, storage, replica, and routing failures with explicit recovery and escalation steps.
DBA handoff
Deliver configuration records, dashboards, alerts, change controls, recovery procedures, evidence, and named ownership.
Patroni PostgreSQL HA questions
What is Patroni?
Patroni is an open-source template for managing PostgreSQL high availability. Each member runs Patroni, while a supported distributed configuration store holds the leader lock and dynamic cluster configuration. Patroni manages PostgreSQL role changes and exposes REST and patronictl interfaces; it does not replace backups, connection routing, monitoring, or infrastructure fencing.
What happens if Patroni cannot reach the DCS?
The current leader must continue to refresh its leader lock. If Patroni cannot safely update the DCS, it normally demotes PostgreSQL when the lock can no longer be maintained; DCS failsafe mode can change behavior when its documented conditions are satisfied. We test DCS loss, partial partitions, and recovery for the exact configuration.
How long does Patroni failover take?
There is no universal failover time. Detection and promotion depend on loop_wait, ttl, retry_timeout, DCS and network behavior, replica eligibility and WAL position, PostgreSQL recovery, watchdog settings, and client routing. We measure recovery and data-loss behavior with representative failures instead of promising a fixed duration.
Can Patroni run without Kubernetes?
Yes. Patroni can run on physical hosts, virtual machines, or containers and use a supported DCS such as etcd or Consul. It can also use Kubernetes objects when deployed there. The DCS topology, network failure domains, authentication, transport security, backups, and operating ownership must be designed with PostgreSQL.
How do applications find the current Patroni primary?
Patroni REST health endpoints can help a load balancer distinguish primary and replica roles. The routing layer may be HAProxy, a service, proxy, or another supported component. Endpoint semantics, authentication, TLS, lag filters, connection draining, DNS behavior, and retry handling are validated before production use.
Does Patroni prevent every split-brain scenario?
No HA tool should be treated as an unconditional guarantee. Patroni uses a DCS leader lock and can integrate with the Linux watchdog, but safety still depends on DCS behavior, timing configuration, network partitions, fencing, PostgreSQL state, and operational procedures. A failure matrix and destructive tests establish the system's actual behavior.
Related PostgreSQL DBRE services
repmgr PostgreSQL replication
Compare the repmgr CLI and repmgrd model with Patroni's DCS-backed control loop.
PostgreSQL high availability
Design replication, failover, routing, backup, recovery, and failure-testing controls.
PostgreSQL support
DBRE-led incident, reliability, upgrade, performance, and operational support.
PostgreSQL services
Review consulting, migration, performance, cloud, security, and reliability services.
Patroni guidance checked against current project documentation
Review scope: DCS leader locks, failover eligibility, replication modes, watchdog fencing, REST health endpoints, switchovers, configuration, load-balancer integration, and operational testing. Behavior and recovery objectives depend on PostgreSQL, topology, DCS, network, settings, and tested runbooks.
Technically reviewed by the JusDB Database Reliability Engineering team. Last reviewed: . See the team and roles.
- Patroni dynamic configuration
Official leader-lock timing, failover eligibility, lag, synchronous-mode, and DCS configuration semantics.
- Patroni REST API
Primary health-check, switchover, failover, restart, reload, configuration, and monitoring interface reference.
- Patroni watchdog support
Official split-brain risk model, Linux watchdog behavior, safety margin, and leader-eligibility controls.
Review your Patroni failure model
Bring the PostgreSQL topology, Patroni and DCS configuration, recovery objectives, routing path, and recent incident evidence. We will scope the safest useful review or implementation.
Contact a database SRE