Backups

Backups are project-scoped snapshots of the instance database. On D1 they’re backed by Time Travel, so a snapshot is a bookmark you can restore to without copying data around.

Kinds

• auto — created on a schedule by the platform; old ones are garbage-collected past their retention window.
• manual — taken on demand (e.g. before a risky migration). Created by an admin.

Create a backup

From the project’s Backups tab, or via the API:

curl -X POST https://cloud.backlex.com/api/org/<org>/projects/<project>/backups \
  -H "Authorization: Bearer pak_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"manual"}'

Restore

Restoring rolls the project database to the snapshot. It’s a destructive operation on the live data — take a fresh manual backup first if you might want to come back.

curl -X POST \
  https://cloud.backlex.com/api/org/<org>/projects/<project>/backups/<id>/restore \
  -H "Authorization: Bearer pak_..."

Caution

Restore overwrites the current database state. There is no undo beyond restoring a different snapshot, so confirm you’ve picked the right one.

Creating and restoring backups requires the admin role and is written to the audit log.

Two different things called “backup”

Everything above is a platform snapshot: the control plane takes a D1 Time Travel bookmark of the whole database, and restoring rolls the whole database back to it. It is an infrastructure operation, and it is the one this page is about.

Your project’s own admin — the one running inside the instance — has a separate backup feature that works on your data rather than your database:

	platform snapshot (here)	instance backup (project admin)
granularity	the entire database	chosen tables, or all of them
restore	rolls everything back to a point in time	writes rows back, with a mode
modes	—	replace (default), or overwrite: update existing rows and insert missing ones, leaving everything else alone
narrowing	—	onlyTables restores just the tables you name
stored as	a D1 bookmark, no data copied	a JSONL dump
where	your project’s Backups tab in the cloud panel	your project’s own admin

They compose rather than compete: take a platform snapshot before anything drastic, and use an instance backup when you want a table back without rewinding the rest of the workspace.

Three classes of row are deliberately not restored by an instance backup, and it reports them as keptAdditive rather than silently skipping them: tables with no single-column id (a restore could not address the rows), users rows (identity is global to the instance — restoring one workspace’s users would change what every other workspace that person belongs to sees), and instance-global rows (tenant_id IS NULL), so a workspace admin cannot reach instance-wide configuration from an operation scoped to their own workspace.

If your project admin says backups are off

Your project’s own admin has an advisor that warns “Automatic backups are off” when the instance-side backup schedule is unset — which it is by default.

On a managed project that warning does not apply. Your backups are taken at the platform level, on the schedule described at the top of this page, and they do not depend on any setting inside the instance. You can leave the instance-side schedule off.

Schema changes take their own snapshot

Dropping a collection or a field in your project’s admin captures a pre-drop backup first, in the same format and the same list, before it destroys anything. That covers the REST route, the SDK, the CLI, MCP and GraphQL, because the guard lives in the schema service rather than in one handler.

A confirmation is required only when the operation would actually destroy data — dropping an empty scaffolding column stays a one-step operation, so CI and template automation are not broken by the guard. ?dryRun=1 reports what would be lost without doing it.