[WIP] Stereo mode PoC

metadata.yaml

@@ -44,6 +44,10 @@ provides:
   cos-agent:
     interface: cos_agent
     limit: 1
+  watcher:
+    interface: postgresql_watcher
+    limit: 1
+    optional: true
 
 requires:
   replication:

postgresql-watcher/actions.yaml

@@ -0,0 +1,12 @@
+# Copyright 2026 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+show-topology:
+  description: |
+    Display the cluster topology as perceived by the watcher.
+    Shows all PostgreSQL units, their health status, and Raft cluster state.
+
+trigger-health-check:
+  description: |
+    Manually trigger a health check and return results.
+    Tests connectivity to all PostgreSQL endpoints and returns their status.

postgresql-watcher/charmcraft.yaml

@@ -0,0 +1,32 @@
+# Copyright 2024 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+type: charm
+platforms:
+  ubuntu@24.04:amd64:
+  ubuntu@24.04:arm64:
+
+parts:
+  charm:
+    plugin: charm
+    source: .
+    build-packages:
+      - libpq-dev
+    charm-requirements:
+      - requirements.txt
+  # Custom dispatch script to set LD_LIBRARY_PATH for libpq
+  dispatch-override:
+    plugin: dump
+    source: .
+    stage:
+      - dispatch
+  libpq:
+    build-packages:
+      - libpq-dev
+    plugin: dump
+    source: /usr/lib/
+    source-type: local
+    stage:
+      - lib/
+    organize:
+      "*-linux-gnu/libpq.so*": lib/

postgresql-watcher/config.yaml

@@ -0,0 +1,35 @@
+# Copyright 2026 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+options:
+  health-check-interval:
+    description: |
+      Interval in seconds between health checks of PostgreSQL endpoints.
+      The watcher periodically tests connectivity to all PostgreSQL units.
+    type: int
+    default: 10
+  health-check-timeout:
+    description: |
+      Timeout in seconds for each health check query (SELECT 1).
+      If the query doesn't complete within this time, it's considered failed.
+    type: int
+    default: 5
+  health-check-retries:
+    description: |
+      Number of retries before marking an endpoint as unhealthy.
+      The watcher will attempt this many times before considering the endpoint down.
+    type: int
+    default: 3
+  retry-interval:
+    description: |
+      Wait time in seconds between health check retries.
+      This helps accommodate transient network issues.
+    type: int
+    default: 7
+  profile:
+    description: |
+      Deployment profile that affects validation strictness.
+      - testing: Warnings for AZ misconfigurations
+      - production: Errors for AZ misconfigurations
+    type: string
+    default: production

postgresql-watcher/dispatch

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+# Set LD_LIBRARY_PATH to include libpq from the charm's lib directory
+JUJU_DISPATCH_PATH="${JUJU_DISPATCH_PATH:-$0}" PYTHONPATH=lib:venv \
+  LD_LIBRARY_PATH=lib:${LD_LIBRARY_PATH:-} exec python3 ./src/charm.py

postgresql-watcher/metadata.yaml

@@ -0,0 +1,46 @@
+# Copyright 2026 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+name: postgresql-watcher
+display-name: Charmed PostgreSQL Watcher
+summary: Watcher/Witness node for PostgreSQL stereo mode
+description: |
+  PostgreSQL Watcher provides a lightweight witness/voter node for PostgreSQL
+  clusters running in stereo mode (2-node configuration). It participates in
+  Raft consensus to ensure quorum without storing any PostgreSQL data.
+
+  The watcher enables automatic failover in 2-node PostgreSQL clusters by
+  providing the necessary third vote for Raft consensus. When one PostgreSQL
+  node becomes unavailable, the remaining PostgreSQL node and the watcher
+  can still form a quorum, allowing the cluster to continue operating.
+
+  Key features:
+  - Participates in Raft voting without running PostgreSQL
+  - Monitors PostgreSQL health via direct database connections
+  - Provides cluster topology visibility via actions
+  - Should be deployed in a different availability zone than PostgreSQL nodes
+
+docs: https://canonical-charmed-postgresql.readthedocs-hosted.com/16/
+source: https://github.com/canonical/postgresql-operator
+issues: https://github.com/canonical/postgresql-operator/issues
+website:
+  - https://canonical.com/data/postgresql
+  - https://github.com/canonical/postgresql-operator
+maintainers:
+  - Canonical Data Platform <data-platform@lists.launchpad.net>
+contact: https://matrix.to/#/#charmhub-data-platform:ubuntu.com
+
+requires:
+  watcher:
+    interface: postgresql_watcher
+    limit: 1
+
+assumes:
+  - juju
+  - any-of:
+      - all-of:
+          - juju >= 3.4.3
+          - juju < 3.5
+      - all-of:
+          - juju >= 3.5.1
+          - juju < 4

postgresql-watcher/requirements.txt

@@ -0,0 +1,4 @@
+ops>=2.0.0
+psycopg2-binary>=2.9.0
+pysyncobj>=0.3.0
+PyYAML>=6.0

postgresql-watcher/src/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2026 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+"""PostgreSQL Watcher charm package."""