pgAgroal Enterprise · How-to

Back up & restore the control plane

The control plane holds operational state in a PostgreSQL schema. These tools back it up to a checksum-verified dump, restore it, and walk a disaster-recovery runbook that confirms the audit log survived intact.

No secret values are exported. Credentials are resolved from cloud secrets managers at runtime and never stored in the control-plane database, so a dump contains configuration and audit state only. This keeps backups portable and aligned with our audit-readiness goals.

What is in the control plane

The control-plane schema holds fleet inventory and group metadata, the declared config and policy, the drift baseline, entitlement and authorization mappings, the hash-chained audit log with its checkpoints, and the lease, membership, and budget tables. The backup captures this state; it does not capture data-plane traffic or client connections.

Back up

Run backup.sh with the control-plane DSN and schema. It produces a pg_dump custom-format dump and a matching .sha256 checksum in the output directory.

PGAGROAL_CP_DSN=postgres://user@host:5432/cp \
PGAGROAL_CP_DB_SCHEMA=pgagroal_cp \
deploy/backup/backup.sh /secure/offsite
# -> /secure/offsite/pgagroal-cp-pgagroal_cp-<ts>.dump (+ .sha256)

Schedule it as a CronJob or cron entry and store the dumps off-site. The backup interval is your RPO, so tune the schedule to your tolerance for lost fleet-operation state.

Restore

Run restore.sh against a target database, passing the dump path. The script verifies the checksum before restoring, so a corrupted or truncated dump is rejected rather than partially applied.

PGAGROAL_CP_DSN=postgres://user@host:5432/cp-restore \
deploy/backup/restore.sh /secure/offsite/pgagroal-cp-...dump

Rehearse restores against a non-production target first. A restore rehearsal is the only way to know your RTO before you need it.

Disaster-recovery runbook

The recovery sequence is provision, restore, audit-verify, start, leadership, reconcile.

Provision a PostgreSQL for the control plane — a managed instance or your own.
Restore the latest dump with restore.sh; the checksum is verified as part of the restore.
Verify integrity by running audit-verify against the restored database. It confirms the hash-chained audit log is unbroken, so the tamper-evidence survives the recovery.
Start the control plane against the restored database and check /healthz, /fleet, and /metrics.
Leadership re-establishes automatically — a new lease and fencing token is expected and correct, and old tokens are fenced out.
Reconcile — the control plane re-probes health and re-evaluates drift against the restored declared config; apply corrections as usual.

RPO and RTO

RPO is the backup interval — schedule dumps as often as your tolerance requires. RTO is the restore plus control-plane start, which is on the order of minutes. The pgagroal data plane keeps serving throughout: the control plane is a management layer, so its outage does not drop client connections. Only fleet operations pause until it is back.

What is in the control plane

Back up

Restore

Disaster-recovery runbook

RPO and RTO

Related reading