Stage 7 · Master
Advanced PostgreSQL
Backups and Point-in-Time Recovery
Meridian does not persist data yet, but the multi-tenant design already constrains the recovery model: backups must restore complete tenant-scoped datasets across identity, community, and billing domains, and recovery procedures must be rehearsed before the first production write path ships.
Why PITR Is the Target
Nightly logical dumps are too coarse for a system that will eventually manage residents, memberships, invoices, and payments. Losing half a day of financial or access-control state would be unacceptable for an HOA platform. The recovery target therefore needs write-ahead-log-based point-in-time recovery once Postgres is introduced. Snapshot-style backups still have value for bootstrapping restores, but they are not sufficient by themselves when the platform holds tenant-scoped operational data.
No database, WAL archive, or backup automation exists in the current repo. The lesson defines the recovery standard before data-bearing services are implemented so the first production schema is not created without a restore plan.
Shared-Schema Recovery Implications
Meridian's shared-schema tenancy model affects how restores are validated. A successful restore is not merely 'Postgres started'. The recovered data has to preserve tenant boundaries and cross-service referential expectations: the tenant resolved from the public slug must still map to the same UUID; memberships must still belong to that tenant; resident, unit, invoice, and payment rows must still agree on tenant ownership. Shared schema simplifies operations compared with schema-per-tenant, but it raises the cost of accidental cross-tenant corruption during restore validation.
| Recovery strategy | Strength | Limitation |
|---|---|---|
| Nightly dump only | Simple to understand | Recovery point objective is too coarse for operational tenant data |
| Base backup + WAL archive (PITR) | Can restore to a precise incident window | Requires rehearsal, storage discipline, and explicit runbooks |
Restore Drills
deploy/k8s/postgres/backup-cronjob.yamlcreateResponsibility: Schedule base backups and WAL archival for the PostgreSQL deployment.
Why now: PITR requires continuous archival, not ad hoc operator action after an incident starts.
Connects to: Will sit beside the future Kubernetes manifests introduced in the deployment phase.
docs/architecture/recovery.mdcreateResponsibility: Document the restore sequence, target timestamp selection, and validation checklist.
Why now: A recovery plan is only operational if it is written, reviewed, and rehearsed.
Connects to: Extends the existing architecture documentation with data recovery procedures.
Restore drills should run against non-production infrastructure on a schedule and should be measured by time to usable service, not by backup job success alone. A credible drill restores the database, boots the affected services, verifies tenant lookup through gateway, and checks domain-specific invariants such as invoice totals or membership counts for a sampled tenant.
Tenant Integrity Checks
- Resolve a known tenant slug to its expected tenant UUID through the gateway path.
- Verify that memberships, residents, units, invoices, and payments for that tenant remain internally consistent.
- Confirm that no sampled query returns rows from a different tenant when filtered by the restored tenant_id.
- Record restore duration, restore point timestamp, and any manual steps required during the drill.
The Decision
Meridian targets point-in-time recovery from the moment PostgreSQL becomes real. The shared-schema tenancy model means recovery validation must prove tenant integrity, not just process startup. Backups are therefore incomplete until restore drills demonstrate that a tenant-scoped workflow can be brought back intact.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.