Loading…
Loading…
Learn how to back up and restore platform configuration and state. The PostgreSQL database is the single source of truth for disaster recovery.
This document describes the procedures for backing up and restoring the platform's data. These procedures have been supported since version 1.0.
The platform's operational strategy treats the PostgreSQL database as the single source of truth for all configuration and state. This includes onboarded services, mapping versions, generated contracts, RBAC bindings, settings, aggregation tables, and the audit trail. All of this data is stored in tables prefixed with s2r_*.
This design makes the application services stateless and disposable. With a current PostgreSQL backup and the corresponding credential encryption key, you can rebuild the entire platform on new infrastructure by deploying the services and connecting them to a restored database.
The platform relies on three classes of artifacts, each with a distinct backup and retention strategy:
| Artifact | Storage Location | Backup and Retention Strategy |
|---|---|---|
| Configuration & State | PostgreSQL s2r_* tables | This is the primary backup target. Backups are managed by the PostgreSQL service operator, not the application. |
| Raw Traffic Archive | Object store (e.g., Google Cloud Storage, S3-compatible) | Managed by the object store's native versioning and lifecycle policies. The default retention period is 60 days and is configurable. |
| Structured Logs | Cloud logging backend or container stdout | Managed by the retention policy of your organization's logging platform. |
NOTE
Mapping versions are immutable. A database backup captures a complete and consistent snapshot of every published contract, which can be replayed.
The platform application does not initiate or manage database backups. This responsibility lies with your database operator or managed database service.
For deployments using Google Cloud SQL for PostgreSQL:
For deployments on Kubernetes using a Postgres operator or using an external managed database (e.g., Amazon RDS, Azure Database for PostgreSQL):
pg_dump jobs, base backups, or automated snapshots.For development or test environments using the bundled postgres container, or for any externally managed instance, you can perform a logical backup using pg_dump.
The following example shows how to create a backup and restore it. The connection details (<db-host>, <db-user>) should match the S2R_DB_* environment variables from your configuration. The default database name is soap_to_rest and the default user is s2r_app.
# Create a logical backup in custom-format archive
pg_dump -h <db-host> -U <db-user> -d soap_to_rest -Fc -f s2r-backup.dump
# Restore the backup into a fresh, empty database
pg_restore -h <db-host> -U <db-user> -d soap_to_rest --clean --if-exists s2r-backup.dump
IMPORTANT
For production environments, it is strongly recommended to use a managed PostgreSQL service with its own robust backup tooling rather than relying on the bundled container and manual pg_dump commands.
Backend credentials are encrypted at rest in the database using an AES key. This key is provided to the application via the S2R_CREDENTIAL_KEY environment variable.
A database backup is not sufficient on its own for a full recovery. The S2R_CREDENTIAL_KEY used to encrypt the data is also required. If you restore a database backup to a new environment configured with a different key, all encrypted credentials will be undecryptable.
S2R_CREDENTIAL_KEY must be stored securely in a secret manager and treated with the same level of care as the database backups themselves.S2R_CREDENTIAL_KEY value that was used when the backup was created.WARNING
Do not rotate the S2R_CREDENTIAL_KEY as a routine operational task. Rotating the key will permanently invalidate all previously encrypted credentials stored in the database.
The restoration process is a sequence of infrastructure-level operations, not application-level commands.
flowchart TD
subgraph "Step 1: Database Layer"
A[Restore PostgreSQL database from backup or PITR]
end
subgraph "Step 2: Application Layer"
B[Deploy platform services]
end
subgraph "Step 3: Verification"
E[Services start and connect to restored DB] --> F[Flyway automatically applies pending migrations]
F --> G[Platform is operational] --> H[Perform post-deploy checks]
end
A --> B
B -- "Provide same S2R_CREDENTIAL_KEY" --> EThe step-by-step procedure is as follows:
S2R_CREDENTIAL_KEY that was used to encrypt the data in the backup.admin-api service inspects the database schema. The Flyway migration tool automatically detects the schema version from the restored database and applies any necessary migrations if you are also upgrading. You do not need to run migrations manually.Always take a complete PostgreSQL backup before upgrading the platform. Database migrations are designed to be forward-only. If an issue occurs during an upgrade that requires a rollback, the pre-upgrade backup is your primary path to recovery.
It is important to distinguish between data retention policies and disaster recovery backups.
Treat these as two separate, complementary strategies.