Skip to content

PostgreSQL Managed DR Contract

Purpose: Define the target-state contract for HybridOps managed PostgreSQL disaster recovery so that managed standby and promotion workflows remain separate from the current self-managed Patroni restore lane.
Maintainer: HybridOps

Scope

This contract defines:

  • the boundary between self-managed DR and managed DR,
  • the required module families for managed DR,
  • the blueprint families for standby, promotion, and failback,
  • the minimum safety and evidence requirements for managed DR execution.

This contract does not define provider-specific implementation details for Cloud SQL, AlloyDB, Azure Database for PostgreSQL, or any other managed service.

Managed DR lane boundary

Managed DR is a separate product and execution lane.

Norms:

  • Managed DR MUST NOT be implemented as a hidden variant of platform/onprem/postgresql-ha.
  • Managed DR MUST NOT overload dr/postgresql-ha-failover-gcp@v1 or equivalent self-managed restore blueprints.
  • Managed DR MUST use separate module and blueprint identifiers.
  • Managed DR MUST preserve the self-managed baseline DR lane as the default packaged path.

Required module families

Managed DR SHOULD be composed from at least these module families:

  1. Managed database provisioning
  2. On-prem PostgreSQL DR source preparation
  3. Managed external replication / standby wiring

Target-state examples:

  • org/gcp/cloudsql-postgresql
  • platform/onprem/postgresql-dr-source
  • org/gcp/cloudsql-external-replica

Equivalent provider-specific modules MAY exist for Azure or other supported targets.

Required blueprint families

Managed DR SHOULD expose separate blueprints for:

  1. Standby creation
  2. Promotion
  3. Failback

Target-state examples:

  • dr/postgresql-cloudsql-standby-gcp@v1
  • dr/postgresql-cloudsql-promote-gcp@v1
  • dr/postgresql-cloudsql-failback-onprem@v1

Norms:

  • Standby blueprints MUST NOT cut application traffic.
  • Promotion blueprints MUST require explicit fencing of the old write primary.
  • Failback blueprints MUST require explicit operator confirmation and MUST treat on-prem re-entry as a reseed/new-lineage event unless reverse replication is an explicitly shipped feature.

State and contract model

Managed DR modules and blueprints MUST consume and publish state-driven contracts.

At minimum:

  • repository location MUST be consumed from repo_state_ref or an equivalent normalized repository contract
  • upstream project/network/database identifiers MUST be consumed from module state where available
  • runtime secrets MUST be consumed from the HyOps vault or environment, never from Terraform state

Managed DR contracts MUST NOT duplicate:

  • object repository names
  • VM IPs
  • provider endpoint coordinates

when those are already available from upstream HyOps state.

Promotion safety

Managed DR promotion MUST be guarded by explicit checks.

At minimum, promotion workflows MUST verify:

  • operator-confirmed fencing of the previous write primary
  • replication health or last known replication state
  • target readiness
  • evidence capture for the promotion decision

Managed DR promotion MUST NOT assume autonomous cutover by default.

Failback safety

Managed DR failback MUST default to a controlled reseed model.

Norms:

  • Failback SHOULD use a maintenance window.
  • Failback MUST rebuild or reseed an on-prem target deliberately.
  • Failback MUST NOT attempt to resume an ambiguous old Patroni timeline.
  • Reverse replication MAY be supported later, but only as a separately documented and tested contract.

Evidence requirements

Managed DR runs MUST capture, at minimum:

  • run metadata and resolved inputs (redacted)
  • source and target identifiers
  • replication state or backup/export provenance
  • promotion/failback guard confirmations
  • resulting service endpoint outputs

Destructive operations

Managed DR MUST keep destructive operations explicit.

Norms:

  • standby destroy MUST be separate from promotion
  • repository purge MUST NOT be part of normal rerun flows
  • data-destructive actions MUST require explicit opt-in confirmation

References