ManagedDatabase whose spec names the source and the time. Managed Postgres explains the backups behind it.
Before you begin
- A Forge app on Reliant hosting with a managed database, such as the one from Deploy a Go API with managed Postgres.
- The database belongs to an environment in your organization. A claimable deploy has no backups.
- The moment you want back is less than 7 days old, and after the database’s first base backup.
- The organization’s
db:querygrant, to check the restored rows withforge db query.
1
Pick the moment to restore to
Find the last moment the data was good, in UTC. The The table had three rows at
db query audit records, your app’s logs and the release history (reliant forge env status prod --history) help you date the incident. Confirm what the damage looks like:terminal
Output
2026-11-20T15:02:09Z and none at 15:06, so this guide restores to 2026-11-20T15:02:00Z. Pick a time a little before the incident: recovery stops at the timestamp, and a change committed after it is not replayed.2
Declare the restored database
Add a second
ManagedDatabase to the environment’s KCL, beside the one it restores, and list both in the bundle:deploy/kcl/prod/main.k
sourceDatabaseis required and must name a database in the same environment.pointInTimeis an RFC 3339 timestamp. Leave it out to replay every archived change.- The name follows the usual rule: a lowercase DNS label of at most 40 characters.
restore to a database that already exists does nothing, which is why you restore into a new one.3
Check the render
terminal
Output
4
Deploy it
Commit, cut a release and deploy it:The platform creates
terminal
Output (trimmed)
shop-restored from the source’s newest base backup before your timestamp, then replays the archive up to it. The app still reads shop.5
Check the restored rows
Query the restored database by name:You should see the rows as they were at
terminal
pointInTime. Rows written after it are not there, by design.6
Point the app at the restored database
The API and the migrate job read Cut a release and deploy it. The migrate job brings the restored database’s schema to head, then the API rolls onto it.
DATABASE_URL from the database the env passes to its hosted binder. Point it at the restored one:deploy/kcl/prod/main.k
7
Verify the app serves the restored data
readyz checks the API’s database connection, and any RPC that reads the table shows the data. Here, an RPC that lists order ids:terminal
Output
8
Clean up
Keep
_db declared until you no longer need it: hosted databases default to deletionPolicy = retain, so removing a declaration does not drop its data. To keep data when you delete a whole environment, use forge env delete <env> --keep-data (keeping data).What this does not do
- There is no restore command or button. The declaration is the whole procedure, so it is reviewed, versioned and repeatable like any other change.
- It never restores over the source. The original keeps running, unchanged, and you decide when to stop using it.
- It can’t cross environments. You can’t restore prod’s backups into staging.
- It can’t reach back more than 7 days, or before the database’s first base backup.
- It needs the platform’s backup storage to be ready for the database. Until it is, the database has no backups and nothing to restore from. No forge command prints a database’s backup status yet. Reliant’s own monitoring pages the platform’s on-call when a database’s backups are on and failing.
Troubleshooting
restore.pointInTime "…" must be an RFC3339 timestamp (2026-01-02T15:04:05Z)
restore.pointInTime "…" must be an RFC3339 timestamp (2026-01-02T15:04:05Z)
Write the time in full UTC with a
Z, or with an explicit offset: 2026-11-20T15:02:00Z.spec.restore needs an object store, and this environment declares none
spec.restore needs an object store, and this environment declares none
The environment has no backup storage, so there are no backups to read. Only databases in an account’s environments are backed up.
attribute 'DatabaseRestore' not found in 'module 'forge''
attribute 'DatabaseRestore' not found in 'module 'forge''
Write
restore as a plain block inside spec, as in this guide, not as forge.DatabaseRestore { … }.the database is unreachable: connect to … failed
the database is unreachable: connect to … failed
forge db query could not connect to the restored database. The exit code is 2: forge could not look, which says nothing about the rows. Check that the deploy reported the database ready, then retry, or check the data through your app once it reads the restored database.Next steps
Managed Postgres
Backups, the read-only query path and keeping data when you delete an environment.
Zero-downtime migrations
Catch a destructive migration before it ships.
Let agents query production data
Audited, read-only queries for people and agents.
Safe migrations
How forge keeps a migration from wedging or breaking a deploy.