Back up and restore a database
Backups let you undo a bad migration, bring back a dropped table, or recover a deleted database. Orchard backs up managed databases to S3-compatible object storage. Each database continuously archives its write-ahead log (WAL) and takes a daily base backup. A base backup is a full copy of the database, and WAL is the stream of changes that Orchard replays onto a base backup, which is why you can restore to any moment rather than only to the last backup.
You can restore from a backup, from a checkpoint, or to any moment in the recovery window. Orchard keeps backups and WAL for 30 days.
Prerequisites
Section titled “Prerequisites”A database needs one of these storage locations. The organization’s bucket takes priority.
- An organization bucket, set under Organization settings > Backups.
- The instance bucket, which an operator sets up as described in Backup storage for operators.
Without storage, the Backups tab shows Backups need storage. Checkpoints, the drop guard, and restore tests are not available.
Take a backup
Section titled “Take a backup”- Open the database.
- Go to Backups.
- Select Save a point > Backup.
The backup appears in Restore points with its status.
orchard db backup create <id> --waitSet the schedule
Section titled “Set the schedule”Orchard gives each new database a daily schedule. To change it:
- Open the database.
- Go to Backups.
- In Schedule, select a preset. For another schedule, select Custom cron…, enter a five-field cron expression in UTC, and select Apply.
orchard db backup-schedule set <id> --cron "0 3 * * *"Take a checkpoint
Section titled “Take a checkpoint”A checkpoint is a named restore point: a marker in the WAL. It does not copy data, and it needs at least one completed backup.
- Open the database.
- Go to Backups.
- Select Save a point > Checkpoint.
- (Optional) In Label, enter a name.
- Select Take checkpoint.
To checkpoint every database in a project, open the project’s Overview, select More actions, then Checkpoint all databases.
orchard db checkpoint create <id> --label "Before the users migration"Without a database ID, the command takes a checkpoint of every database in the project or environment.
A checkpoint shows as pending until its WAL reaches object storage. You can restore it after that. Checkpoints expire after 30 days.
Orchard also takes checkpoints automatically:
| Type | When Orchard takes it |
|---|---|
| Before a drop | Before any DROP TABLE, DROP SCHEMA, or DROP COLUMN runs, when Checkpoint before drops is on. The checkpoint records what was dropped and by whom. This check does not cover TRUNCATE. |
| Before a deploy | Before an app that references the database deploys, so that a rollback can also restore the app’s databases. |
| Before a change | Before an operation that changes the database, such as an in-place restore or a major upgrade. |
Restore a database
Section titled “Restore a database”You can restore in two ways.
| Option | Result |
|---|---|
| Replace this database | Orchard takes a checkpoint, then swaps in the restored copy. It keeps the previous copy stopped for 24 hours, so you can undo the restore. Apps reconnect automatically. |
| Copy into a new database | The original keeps running. The copy keeps the source’s database name, so an app that connects to it finds its tables. |
- Open the database.
- Go to Backups.
- Select Restore.
- In Point to restore to, select Latest, A backup, A checkpoint, or A time. When you copy a database, Now replaces Latest and copies the live data.
- In Where to restore, select Replace this database or Copy into a new database.
- For a copy, enter a Name.
- For a copy, select an Environment.
- Select Restore or Create copy.
The operation appears in Operations on the same tab.
To restore in place to a point in time:
orchard db backup restore <id> --at 2026-11-03T14:30:00Z --waitTo restore to a checkpoint:
orchard db checkpoint restore <checkpoint-id> --waitTo copy a database from now, a backup, a checkpoint, or a point in time:
orchard db fork <id> --name appdb-copy --waitFor the source, add --backup, --checkpoint, or --at.
To start a new database from an existing one, select Copy of a database in Start from when you create a database.
Undo a restore
Section titled “Undo a restore”You can undo an in-place restore for 24 hours.
- Open the database.
- Go to Backups.
- In Operations, select Undo on the restore.
- Select Undo restore.
Orchard moves aside anything written since the restore.
orchard db ops undo <op-id> --waitRecover a deleted database
Section titled “Recover a deleted database”A deleted database stays in Recently deleted for 30 days, and Orchard then purges it. You can bring it back only if it had at least one completed backup, because recovery replays that backup.
- Open the project’s Overview.
- In Recently deleted, select Bring back.
orchard db trash listorchard db trash restore <deleted-id> --waitTo block deletion, turn on Deletion protection as described in Protect a database.
Test a backup
Section titled “Test a backup”A restore test restores the latest backup into a temporary copy, compares its tables and estimated row counts with the source, and deletes the copy. A failed test sends a notification.
- Open the database.
- Go to Backups.
- In Restore tests, select Test this backup.
To run a test every week, turn on Weekly restore tests under Settings > Protection.
orchard db test-backup run <id> --waitSuperadmins set instance-wide defaults under Instance admin > Configuration > Databases. By default, checkpoints before drops are on and weekly restore tests are off.
Verify your backups
Section titled “Verify your backups”- Open the database.
- Go to Backups.
- Confirm that the status reads Protected.
- In Restore tests, select Test this backup.
In the API, an empty liveStatus.firstRecoverabilityPoint means no base backup has completed.
How backups use memory
Section titled “How backups use memory”The base backup runs inside the database container and shares its memory limit with Postgres. Compressing a backup on a small database can use enough memory for the kernel to kill Postgres. For this reason, Orchard chooses base backup compression from the memory limit.
To override the choice, set backupCompression through the database settings API. Orchard always compresses WAL, one segment at a time.
Retention
Section titled “Retention”Orchard removes backups and WAL older than 30 days. This limit also sets how far back point-in-time restore and checkpoints reach.
If your bucket has its own lifecycle rule, keep objects for longer than 30 days. A shorter rule deletes backups Orchard still needs.
Backup storage for operators
Section titled “Backup storage for operators”To set up instance storage, refer to Add S3 storage. The setup flow, Instance admin, orchardctl backups s3, and the installer all save the same settings. Any S3-compatible service works.
Organization backup endpoints
Section titled “Organization backup endpoints”The server checks an organization’s own backup endpoint when it is saved and again every time it connects, so a hostname that later resolves to a private address is refused. Set BACKUP_ALLOW_INTERNAL_ENDPOINT=true to allow private endpoints.
Database pods write their own backups to the endpoint, and the tenant network policy lets them reach any public address. That policy does not limit them to the endpoint an organization saved. If you need an allowlist of backup destinations, enforce it at the node or cloud firewall.
The store on the server
Section titled “The store on the server”The one-command installer runs an S3 store (versitygw) in the orchard-object-storage namespace, with the backup proxy, and sends the instance’s backups to it. Checkpoints, point-in-time restore, copies, deleted database recovery, and restore tests work from this store.
The chart keys are under objectStorage.local. The installer overrides some of the chart defaults:
| Key | Chart default | Installer value |
|---|---|---|
enabled | false | true |
bucket | orchard-backups | orchard-backups |
uploadsBucket | orchard-uploads | orchard-uploads |
storage.size | 20Gi | One fifth of free disk, from 5 GiB to 50 GiB |
storage.storageClass | The cluster’s default class | The local-path class, which does not enforce the size |
To install without this store, pass --object-storage false. Databases then have no backups until you add S3 storage.
On an installer host whose values file does not set objectStorage.local.enabled, orchardctl update turns the store on, unless object storage is already configured in the values file (in the server environment, server.envFrom, or r2Proxy.upstream) or under Instance admin.
Add S3 storage later
Section titled “Add S3 storage later”When you add S3 storage, new databases back up to it. Databases you already have keep backing up to where they are now, and their existing backups stay restorable from there. To move a database, create a copy of it. For details, refer to What happens when you change storage.
Related resources
Section titled “Related resources”- Back up and restore an instance - Learn what else an instance needs backed up to survive the loss of a machine.
orchard dbreference - Review the backup, checkpoint, and restore commands and their flags.