pg_auto_failover: automated PostgreSQL failover with a monitor

What pg_auto_failover manages in a PostgreSQL cluster

pg_auto_failover addresses a specific control-plane problem: deciding when a PostgreSQL deployment may promote a standby and how the cluster should react when nodes fail. It is intended for operators who need automated failover rather than a process that merely restarts PostgreSQL after a crash.

The project has three connected parts. The `pgautofailover` extension belongs inside PostgreSQL. The monitor is a PostgreSQL service that implements the cluster state machine and decides whether transitions are permitted. A keeper process, operated through `pg_autoctl`, manages each PostgreSQL instance. The README states that the project supports PostgreSQL 13 through 18 and can operate with only two data nodes, assigned primary and secondary roles by the monitor.

The architecture is opinionated about safety. By default, it uses synchronous replication, and every healthy node in the secondary state is added to `synchronous_standby_names` on the primary. This ties node transitions to PostgreSQL replication behavior instead of treating PostgreSQL as an opaque process behind an external health check. That makes the project relevant to teams seeking an explicit HA state machine, but it also means adopting the monitor's rules is part of adopting the design.

The monitor state machine and failover safety boundary

According to the README, the monitor implements a state machine and relies on facilities already present in PostgreSQL. Its central safety mechanism is health and lag eligibility. When the monitor detects that a secondary is unavailable or has excessive lag, it removes that node from `synchronous_standby_names` on the primary. Operations that could expose the cluster to unsafe data loss are blocked until the secondary is monitored as healthy again.

This design affects both planned and unplanned transitions. A failed or lagging standby is excluded from the replication quorum, allowing the cluster to avoid depending on that particular node. However, the README also says that failover and switchover operations are not allowed while the secondary is not back in a monitored healthy state. In other words, removing an unsafe standby does not mean promoting it. The monitor separates current quorum membership from permission to perform a transition.

Multiple standbys are supported. Healthy secondary nodes enter the default synchronous quorum, while a node may also be deliberately removed from that quorum. This gives operators a way to trade replication safety and availability across a larger topology. It is more involved than a binary primary and backup arrangement, and the README does not document a simple policy language for deciding exactly when lag becomes unacceptable, so that threshold must be checked in the project documentation and deployment configuration.

Installing pg_auto_failover on Debian and Ubuntu

The README directs Debian-family users to the PGDG package repository. It separates the monitor extension package from the CLI package. The monitor package is tied to the PostgreSQL major version, while `pg-auto-failover-cli` contains `pg_autoctl` for the managed PostgreSQL nodes.

Before installing, the README asks administrators to prevent Debian from creating a default cluster with `postgresql-common`. The following sequence configures the repository and installs PostgreSQL 17 without creating that initial cluster. The repository key URL, source line, and setting are copied from the README.

$ curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
$ echo "deb http://apt.postgresql.org/pub/repos/apt bookworm-pgdg main" > /etc/apt/sources.list.d/pgdg.list
$ echo 'create_main_cluster = false' | sudo tee -a /etc/postgresql-common/createcluster.conf
$ apt-get update
$ apt-get install -y --no-install-recommends postgresql-17

After this sequence, the reader should have PostgreSQL 17 packages configured without the automatic `main` cluster. Install the two pg_auto_failover packages shown by the README:

$ sudo apt-get install pg-auto-failover-cli
$ sudo apt-get install postgresql-17-auto-failover

The package names are version-specific in one important place: the README uses `postgresql-17-auto-failover` when targeting PostgreSQL 17. A deployment targeting another supported major version must use the corresponding package documented by the installation chapter rather than substituting an unconfirmed name. Source builds are also possible through the Makefile, but the README's extended documentation, not the top-level package example, is the stated place for other installation methods.

A first local deployment from the repository compose topology

The repository includes a concrete multi-node demonstration in `docker-compose.yml`. It defines a monitor service, three managed PostgreSQL nodes, and a demo application. The monitor exposes PostgreSQL port 5432 internally through the compose configuration, while each node connects through `PG_AUTOCTL_MONITOR` to the monitor's `pg_auto_failover` database.

The monitor's compose service runs this command:

pg_autoctl create monitor --ssl-self-signed --auth trust --run

The self-signed certificate and `trust` authentication options are appropriate to the repository's demonstration setup, not evidence of a production authentication design. Each PostgreSQL node starts with the following command inside its service:

pg_autoctl create postgres --ssl-self-signed --auth trust --pg-hba-lan --run

The connection information supplied to each node is visible in the environment:

PG_AUTOCTL_MONITOR: "postgresql://autoctl_node@monitor/pg_auto_failover"

The repository states that the main tutorial uses Docker Compose to start several PostgreSQL nodes and create a first failover. The concrete first-use behavior documented here is that `pg_autoctl create monitor` provisions and runs the monitor, `pg_autoctl create postgres` provisions and runs a node, and the demo client is configured through `PG_AUTOCTL_DEMO_CLIENTS`, `PG_AUTOCTL_DEMO_DURATION`, and failover-related environment variables.

Citus support and operational boundaries

Version 2.0 added a documented High Availability architecture for Citus. The repository includes a dedicated Citus compose quick start that describes a worker failover followed by a coordinator failover. This extends the project's stated scope beyond a standalone PostgreSQL cluster, but the README does not reduce that addition to a simple feature flag. Citus support has its own quick-start tutorial, and operators need to account for coordinator and worker topology rather than assume the standalone two-node model applies unchanged.

The most visible operational boundary is the monitor's refusal to permit failover or switchover while a secondary is unhealthy. That is a deliberate data-safety choice, yet it is also a trade-off: a cluster can be left without an allowed transition while the operator has not restored a monitored healthy secondary. The two-node starting topology makes this especially consequential because there is only one alternate data node. A project that can tolerate operator-directed recovery or use a different HA policy should compare this behavior before deployment.

The README does not document rollback for database changes, production Docker Compose instructions, or a complete set of monitor settings. It also does not describe automatic schema or application migration during failover. Those are material adoption questions, not incidental omissions. The scope documented by the project is PostgreSQL service continuity and topology management, with Citus support added for that architecture.

Native synchronous replication as the alternative approach

The clearest alternative is PostgreSQL synchronous replication without pg_auto_failover. PostgreSQL already exposes the setting at the center of pg_auto_failover's model: `synchronous_standby_names`. A team can configure primary and standby replication directly, then place its own scripts, operator procedures, or infrastructure controller around health checks and promotion.

The difference is control and responsibility. pg_auto_failover supplies a persistent monitor state machine, managed node roles, and transition rules that coordinate synchronous quorum membership with failover eligibility. Native synchronous replication leaves the team responsible for constructing those rules and checking state before promotion. The pg_auto_failover approach can reduce bespoke operational code, but it adds a project-specific extension, monitor service, keeper process, state model, and upgrade path.

The project is therefore the wrong choice if the requirement is only replication between known hosts with no desire to run an HA controller. It may fit where automated role transitions and explicit safety gates are central to the service. The decision should be based on the desired behavior when the standby is unavailable, because that is where pg_auto_failover makes a consequential choice rather than merely wrapping PostgreSQL.

Licensing, releases, and maintenance exposure

The repository identifies the PostgreSQL License for the project and includes Microsoft copyright information. It also states that bundled third-party dependencies are covered by the `NOTICE` file. GitHub's classification is listed as a custom license that it could not classify, so the authoritative files to inspect are `LICENSE` and `NOTICE`. This is a licensing boundary to verify before redistribution or embedding, not a claim about legal interpretation.

Recent releases include v2.2 on 2025-04-03, v2.1 on 2023-11-24, and v2.0 on 2022-10-07. The repository is not archived, and its last push was on 2026-10-14. The available release history is not continuous, so operators should not assume every minor update follows the same schedule.

The upgrade cost includes more than replacing the extension. PostgreSQL major-version packages are version-specific, and the monitor, keeper, extension, configuration, and Citus topology must all remain compatible with the intended release. The README supports PostgreSQL 13 through 18, but it does not provide a blanket upgrade procedure. The documented installation chapter, release notes, and configuration details should be checked against the selected major version before changing a running cluster.

Editorial conclusion

Adopt pg_auto_failover when an operator can manage its monitor, keeper processes, extension, and PostgreSQL nodes, and when preventing unsafe promotion is more important than keeping a degraded primary writable. Do not choose it merely to obtain another generic load balancer, or without checking how an unhealthy secondary affects write availability. Before deployment, verify the PostgreSQL major version, package compatibility, replication quorum, network access, and the behavior of the LICENSE and NOTICE files.

Frequently asked questions

Official sources

1. hapostgres/pg_auto_failover on GitHub
2. Issues
3. README
4. Releases