Stereo mode

Stereo mode is a two-node high-availability topology for Charmed PostgreSQL. It runs the database on two postgresql units and adds a separate, lightweight postgresql-watcher application that contributes a third vote to the cluster’s Raft quorum. The watcher runs no PostgreSQL of its own — its only job is to make the cluster’s vote count odd, so that high availability works with only two database copies.

A stereo-mode deployment: two postgresql units plus a postgresql-watcher that contributes the third Raft vote on port 2222.

Why a third vote is needed

Charmed PostgreSQL uses Patroni for high availability, and Patroni elects a primary through Raft consensus. Raft requires a majority of voters to agree before it can elect a primary.

With an even number of voters, a single failure splits the cluster in half and neither half holds a majority:

• 2 voters, 1 lost → 1 remaining. One vote is not a majority of two, so the survivor cannot safely promote itself. Automatic failover stalls.

Adding a third voter restores a safe majority:

• 3 voters, 1 lost → 2 remaining. Two votes are a majority of three, so the cluster keeps operating and can fail over automatically.

Running a third full PostgreSQL unit is the most robust option, but it adds a third full copy of the data — 50% more storage and compute — for a workload that only needs two copies. Stereo mode is the middle ground: two real database units plus one tiny watcher.

How the watcher participates

The postgresql-watcher charm is deployed as a separate Juju application and integrated with postgresql over the watcher-offer endpoint (provided by postgresql) and the watcher endpoint (required by the watcher).

Once integrated, the watcher:

• Runs only Patroni’s patroni-raft-controller from the charmed-postgresql snap, started as a systemd service and listening on port 2222. It does not run PostgreSQL.

• Joins the cluster’s Raft quorum as a voting member, so two postgresql units plus the watcher make three voters.

Note

The watcher participates in leader election only. It stores no table data and never becomes a PostgreSQL primary or replica.

For the watcher’s security posture — trust boundaries, hardening, inherent risks, and decommissioning — see Watcher security.

When the watcher votes (and when it doesn’t)

The watcher runs and votes only when the postgresql units would otherwise form an even voter count. When they al