Skip to content
Install

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.

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.

  1. Open the database.
  2. Go to Backups.
  3. Select Save a point > Backup.

The backup appears in Restore points with its status.

Orchard gives each new database a daily schedule. To change it:

  1. Open the database.
  2. Go to Backups.
  3. In Schedule, select a preset. For another schedule, select Custom cron…, enter a five-field cron expression in UTC, and select Apply.

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.

  1. Open the database.
  2. Go to Backups.
  3. Select Save a point > Checkpoint.
  4. (Optional) In Label, enter a name.
  5. Select Take checkpoint.

To checkpoint every database in a project, open the project’s Overview, select More actions, then Checkpoint all databases.

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:

TypeWhen Orchard takes it
Before a dropBefore 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 deployBefore an app that references the database deploys, so that a rollback can also restore the app’s databases.
Before a changeBefore an operation that changes the database, such as an in-place restore or a major upgrade.

You can restore in two ways.

OptionResult
Replace this databaseOrchard 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 databaseThe original keeps running. The copy keeps the source’s database name, so an app that connects to it finds its tables.
  1. Open the database.
  2. Go to Backups.
  3. Select Restore.
  4. 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.
  5. In Where to restore, select Replace this database or Copy into a new database.
  6. For a copy, enter a Name.
  7. For a copy, select an Environment.
  8. Select Restore or Create copy.

The operation appears in Operations on the same tab.

To start a new database from an existing one, select Copy of a database in Start from when you create a database.

You can undo an in-place restore for 24 hours.

  1. Open the database.
  2. Go to Backups.
  3. In Operations, select Undo on the restore.
  4. Select Undo restore.

Orchard moves aside anything written since the restore.

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.

  1. Open the project’s Overview.
  2. In Recently deleted, select Bring back.

To block deletion, turn on Deletion protection as described in Protect a database.

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.

  1. Open the database.
  2. Go to Backups.
  3. In Restore tests, select Test this backup.

To run a test every week, turn on Weekly restore tests under Settings > Protection.

Superadmins set instance-wide defaults under Instance admin > Configuration > Databases. By default, checkpoints before drops are on and weekly restore tests are off.

  1. Open the database.
  2. Go to Backups.
  3. Confirm that the status reads Protected.
  4. In Restore tests, select Test this backup.

In the API, an empty liveStatus.firstRecoverabilityPoint means no base backup has completed.

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.

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.

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.

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 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:

KeyChart defaultInstaller value
enabledfalsetrue
bucketorchard-backupsorchard-backups
uploadsBucketorchard-uploadsorchard-uploads
storage.size20GiOne fifth of free disk, from 5 GiB to 50 GiB
storage.storageClassThe cluster’s default classThe 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.

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.