Backup and restore

Take a portable, schema-versioned snapshot of an oo-workers instance (config plus execution history, optionally S3 artifacts) and restore it on another host.

A full logical snapshot of an instance, configuration and execution history, that you can move to a new host, keep for disaster recovery, or use to clone an instance for staging. It is not pg_dump: the dump is a portable, schema-versioned NDJSON stream that survives a Postgres major-version change and restores through the app's own schema.

What is in a dump#

  • All configuration: every monitor type, assertions, alert channels, status pages, regions, users (password hashes), and API keys (hashes). Restored keys and logins keep working.
  • Execution history: windowed to the last 90 days by default.
  • Browser test script bodies (they live in a database column).

Not included by default: sessions (log in again after a restore) and object-storage artifacts. Tick Include browser run artifacts (or pass --include-artifacts) to bundle every S3 object (QA scripts, Playwright trace.zip, failure screenshots) into the dump. Without it, a fresh-host restore leaves QA script pointers dangling and per-run "Download trace" links broken, which is why the toggle is on by default.

From the dashboard#

Settings → Backup & restore → Download backup. Pick a scope (last 90 days, all history, or config only) and the browser streams the dump to disk.

Settings → Backup & restore → Restore. Choose a dump file and confirm. Restore replaces everything in the target instance, so it asks you to confirm the wipe first. Restoring into the instance you are logged into signs you out when it finishes.

From the CLI#

Run inside the worker container:

# Back up (DB only)
docker compose exec worker bun scripts/export.ts -o /tmp/backup.oodump.gz


# Back up the DB plus every S3 object
docker compose exec worker bun scripts/export.ts --include-artifacts -o /tmp/full.oodump.tar.gz


# Restore (target must be empty, or pass --force to wipe it first)
docker compose exec worker bun scripts/import.ts --from /tmp/backup.oodump.gz --force

import.ts auto-detects the format, and dumps from earlier releases stay restorable.

Restore rules#

  • Fresh-restore only. The target must be empty, or wiped with --force. There is no merge-into-a-running-instance mode.
  • Schema version must match. The dump records the migration head, and restore refuses unless the target is migrated to the same version. Migrate the target first, then restore. This is the error you are most likely to hit when moving between releases.
  • IDs are preserved and the sequences are bumped past the restored rows, so monitors created after a restore do not collide. The whole load runs in one transaction, so a failed restore leaves the target untouched.

This is different from the dashboard's Import JSON, which is a config-only adapter for pulling an ObserveOne SaaS export into a fresh instance. Backup and restore is the full database-direct snapshot described here.

Was this page helpful?