Backups and restore

Consistent snapshots

Snapshots are created through the database owner using PGlite dumpDataDir(), then encrypted using AES-256-GCM and recorded with a checksum and schema version. Use the owner snapshot workflow; copying a live database directory is not a consistent backup.

Manual snapshots are available in Studio and the CLI. The maintenance worker requests scheduled backups. Project admins configure automatic schedule and retention on Studio /backups; deployment environment variables remain the operator ceiling and kill switch (QB_SCHEDULED_BACKUPS, QB_BACKUP_RETENTION_DAYS, QB_BACKUP_RETENTION_WEEKS). Defaults stay daily snapshots with seven daily days and four weekly copies.

Isolated restore

Restore decrypts and verifies the checksum, loads a snapshot into a new branch database and validates schema, constraints and manifest evidence. Active sessions, verification challenges and stored OAuth access/refresh tokens are excluded. Restored application users remain in the isolated database and must establish new sessions.

Validate expected table data, policies and migrations before cutover. The restored branch has its own authentication identity and routing.

Production cutover

The cutover endpoint requires the project owner role and an explicit project-slug confirmation. It creates a rollback backup, closes the old primary owner and changes the primary alias. Existing requests and sockets must be reconciled against the changed branch.

The previous primary is retired and refuses public reads and writes. Restore the rollback snapshot into another isolated branch to reverse the cutover. Do not assume that alias switching merges data.

Object bytes and control metadata

Branch snapshots do not back up S3 object bytes. The worker separately creates encrypted, checksummed control catalog snapshots under backups/control with the same daily/weekly retention. Protect the master key and copy archives off the node; configure object-store versioning/backups separately.

Control recovery is offline. Stop the API/worker, preserve all referenced project database files and verify the archive before replacement. The local ownership lock prevents restoration over a running API. The command checks integrity, foreign keys, applied control migrations and referenced branch files, creates an encrypted rollback checkpoint, excludes platform sessions and revokes all restored project/management credentials. Reissue keys after recovery.

bun run qb backup control-create --data-dir .data
bun run qb backup control-restore --data-dir .data --file CONTROL_ARCHIVE --confirm-local-control-restore

Inject the original QB_MASTER_KEY for production recovery. A catalog archive does not include project databases or object bytes; coordinate their recovery to a compatible checkpoint.

Recovery Center (experimental)

Studio /backups exposes the experimental Recovery Center: per-project schedule and retention, encrypted off-node S3-compatible destinations, inventory with freshness warnings, and isolated restore drills. Destinations use separate sealed credentials and never receive the master key. Archives progress staging → encrypted → uploading → verified | failed. Drills progress queued → restoring → validating → complete | partial | failed | cancelled and never change the primary alias.

A drill is complete only when database validation, application-object backup verification (versioning plus bounded object heads) and master-key authentication all pass. Database-only success is partial. QB Flex verifies operator-provided object-store backups; it does not copy object bytes. Findings use stable codes such as BACKUP_STALE, DESTINATION_UNAVAILABLE, BACKUP_CORRUPT, OBJECT_BACKUP_MISSING and KEY_UNAVAILABLE. Outbound mail or webhook alerts are not part of this surface.

Retention keeps the configured daily window, weekly copies and always the newest checkpoint per branch. Control-catalog snapshots under backups/control continue to follow deployment environment retention.

Manual recovery drills remain useful: create representative data, take a snapshot, restore into another branch and compare results. Publish measured RPO/RTO only after a reference-dataset drill passes. The daily/seven-daily/four-weekly defaults and reference RPO 24 hours/RTO 60 minutes are planning defaults, not certified guarantees.

Retention and cancellation

Project retention cannot exceed QB_BACKUP_RETENTION_DAYS (default 7) and QB_BACKUP_RETENTION_WEEKS (default 4). Preserve encrypted snapshots and the master key on separate storage for disaster recovery. A local backup volume is not off-site redundancy.

Project provisioning can be cancelled through POST /management/v1/operations/{id}/cancel while its status is requested. Running or completed operations return OPERATION_NOT_CANCELLABLE; cancellation never rolls back a committed database operation.

Streaming branch archive v2 and compatibility

New branch archives use authenticated QBFARCH2 framing, AES-256-GCM and an incremental raw SHA-256 manifest digest. Encryption/decryption use bounded streams and private staging rather than reading the whole snapshot into memory. Authentication, expected size and checksum must pass before restored data is registered or exposed. Wrong keys, damaged headers/tags/bytes or digest mismatch fail with BACKUP_CORRUPT; failed partial files are cleaned up.

Legacy branch archives remain readable, including their original checksum semantics. Do not rewrite stored checksums by hand. The new format is not promised readable by older API versions; preserve a validated compatible restore runtime during upgrades. Control-catalog snapshots now also use streamed v2 framing with an authenticated control-kind marker, creation time and raw SHA-256 digest. Legacy encrypted JSON/base64 control archives remain readable through a bounded decoder.

Backup/restore shares a two-operation concurrency bound and a 120-second stream deadline. Archive validation has a size bound of at least 1 GiB or the configured database-write quota, whichever is larger. This is a bound, not a certified restore-time target. Snapshot schema version comes from the captured database, not a concurrently changed live branch.

Restores remove durable jobs as well as sessions/challenges/provider tokens. Neither old pending deliveries nor push registrations/campaigns should be revived. Object bytes and master-key custody remain separate responsibilities. Restart cleanup removes recognized abandoned temporary artifacts only under exclusive data-volume ownership; never manually sweep arbitrary live database files.

Streamed offline control recovery

qb backup control-create and control-restore keep their existing command names, data directory and explicit restore-confirmation flag. They wait for streams before returning. Create retains path and raw 64-character SHA-256 checksum, adding format: 2 and snapshot byte size. Restore retains its original result flags/rollback path and adds the source format.

New control archives authenticate kind, creation time, size, checksum and PGlite engine/version inside the v2 header. Physical datadir snapshots require the pinned compatible PGlite runtime. Legacy SQLite archives produced by QB Flex remain readable through the validated offline converter, which blocks incompatible schemas or values. Legacy archive envelopes remain readable without buffering their entire encrypted JSON/base64 envelope. Control archives are not interchangeable with branch archives, even with a matching key. The original master key remains mandatory and is never stored alongside archives.

Control snapshots permit one active write per catalog, default to a 1 GiB plaintext limit and have a 120-second streaming deadline. Disk checks budget private staging plus encryption/rollback headroom. Temporary directories use mode 0700 and plaintext/archive files use 0600. Authentication/checksum and native integrity/foreign-key/migration/dependency checks precede replacement. Missing branch files or bad archives fail without replacing the catalog.

Control recovery excludes platform sessions/challenges/provider tokens and revokes project/management credentials as before. Branch files and their identities are a separate recovery asset; coordinate compatible branch snapshots rather than assuming the control archive contains them. The replacement and its directory are fsynced, and an encrypted rollback is created before replacement. Only exact recognized abandoned control staging is removed under the exclusive volume lease; final archives and operator files are preserved. Graceful API shutdown waits for in-flight maintenance/control streams before closing the catalog and releasing ownership.

PGlite dumpDataDir(), integrity checks and checkpointing remain native synchronous operations. The streaming deadline/cancellation applies to hashing/encryption/decryption, not preemption of a running PGlite call. This is not an off-node Recovery Center or an automated drill/cutover service. New-format archives require a compatible restore runtime; older binaries are not guaranteed to read v2.

Engine conversion preserves live credentials and durable work in a stopped installation. Backup restoration has different semantics: it strips sessions, provider tokens, jobs and webhook subscriptions, and control recovery revokes credentials. See engine migration.