Backup & Restore

How to protect and recover the data SOAP-2-REST by Specaria depends on. Since v1.0.

How to protect and recover the data SOAP-2-REST by Specaria depends on. Since v1.0.

What to back up

PostgreSQL is the single source of truth for all configuration and state — onboarded services, mapping versions, generated contracts, RBAC bindings, settings, aggregation tables, and the audit trail. All of it lives in the s2r_* tables.

This has a useful operational consequence: the application services are stateless and disposable. If you have a current PostgreSQL backup, you can rebuild the entire platform onto fresh infrastructure by deploying the services and pointing them at a restored database. The other artefact classes are:

| Artefact | Where it lives | Backup approach | | --- | --- | --- | | Configuration & state (services, mappings, RBAC, settings, audit, aggregations) | PostgreSQL s2r_* tables | Primary backup target — see below. | | Raw traffic archive | Object store (Cloud Storage on GCP; an S3-/Blob-compatible store or volume elsewhere) | Use the object store's own versioning/lifecycle. Default retention 60 days, configurable. | | Structured logs | Your cloud logging backend / container stdout | Retained per your logging platform's policy. |

Mapping versions are immutable and preserved across product upgrades, so a database backup captures a self-consistent, replayable picture of every published contract.

Backing up PostgreSQL

The platform itself does not initiate database backups — that is owned by your PostgreSQL service or operator. Configure it according to your topology.

GCP-native (Cloud SQL)

Cloud SQL automated daily backups are enabled by default. Verify the retention window on the instance and increase it to 30+ days for production.
Enable point-in-time recovery (PITR) for the ability to restore to an arbitrary moment, not just the last daily snapshot.
Periodically validate that backups are actually being taken (a backup you have never restored is a hope, not a backup).

Kubernetes / Helm and external managed PostgreSQL

Configure backups on your Postgres operator (e.g. scheduled pg_dump / base-backup jobs) or your managed instance (RDS automated snapshots, Azure Database for PostgreSQL backups, etc.).
Keep the backups outside the cluster/instance that hosts the database.

Docker Compose (bundled or external Postgres)

For the bundled postgres container or any external instance, a logical dump is straightforward:

# Logical backup of the application database:
pg_dump -h <db-host> -U <db-user> -d soap_to_rest -Fc -f s2r-backup.dump

# Restore into a freshly created, empty database:
pg_restore -h <db-host> -U <db-user> -d soap_to_rest --clean --if-exists s2r-backup.dump

Use the S2R_DB_* connection values from your .env (defaults s2r_app / soap_to_rest). For production, prefer a managed PostgreSQL with its own backup tooling over the bundled container.

The credential key is part of your recovery plan

Backend credentials are stored encrypted in the database with an AES key supplied via S2R_CREDENTIAL_KEY. A database backup is not independently usable without that key — restoring the data onto an install configured with a different key leaves every encrypted credential row undecryptable.

Store S2R_CREDENTIAL_KEY in your secret manager, treated with the same care as the database backups themselves.
When restoring to new infrastructure, set the same S2R_CREDENTIAL_KEY value the data was encrypted with.
Never rotate the key as a routine operation — rotating it invalidates every previously-encrypted credential row.

See Backend credential encryption and the Configuration reference.

Restoring

The flow is the same regardless of topology:

Restore the database at the PostgreSQL level — point-in-time recovery or a snapshot/dump restore. This is a database operation, not a platform operation.
Deploy (or redeploy) the services against the restored database, with the same S2R_CREDENTIAL_KEY the data was encrypted with and the standard secret bindings.
Flyway resumes from the restored schema state. admin-api inspects the schema on startup and continues from where the backup left off — you do not run migrations by hand.
Verify per the deployment runbook post-deploy checklist: provenance, healthy services, a golden-path call, fresh ingest rows, and a loading dashboard.

Before an upgrade

Always take a PostgreSQL backup before upgrading the product. Migrations are forward-only; if a release introduces a schema change that a rollback cannot tolerate, the pre-upgrade backup is your recovery path. See the upgrade guide.

Retention vs backup

Retention (default 60 days for the raw traffic archive, configurable under Settings) controls how long operational traffic artefacts are kept for observability — it is not a backup of your configuration. Treat the two separately: retention is for observability windows; PostgreSQL backups are for disaster recovery. See Data retention.

All Specaria SOAP to REST docs

Loading…