Backups & restore

Every PerSQL database has continuous point-in-time recovery (PITR) out of the box. The underlying Cloudflare SQLite engine retains a 30-day rolling history of every write — no schedule, no agent, no cron. To get back to any moment in that window, restore.

How it works

• Continuous history. Every committed write produces a recoverable bookmark. The 30-day window is rolling: anything older than 30 days is no longer reachable.
• Two restore modes.
  • By time — pick a moment with the datetime picker in the console (or pass timestamp to the API). PerSQL resolves the closest bookmark.
  • By label — take a manual labeled snapshot before a risky operation, then restore to that label.
• Restore is destructive. Everything written after the chosen moment is discarded. There is no partial-table restore — the whole database snaps back.
• Brief unavailability. A restore tears down and reincarnates the database; expect a few seconds of downtime for the affected database. Other databases in your namespace are unaffected.

Labeled snapshots

A snapshot is a named pointer to a moment. Cloudflare already keeps the 30-day history; PerSQL stores the label so you can find the moment again.

In the console: Database → Backups → Snapshot now, give it a label like before-migration-v3, click Snapshot.

Snapshots inherit the same 30-day horizon — once a snapshot is older than 30 days, the underlying bookmark is no longer recoverable. The label row stays visible until you delete it.

REST

Method	Path	Notes
GET	/api/namespaces/:ns/databases/:db/snapshots	List labeled snapshots
POST	/api/namespaces/:ns/databases/:db/snapshots	Body: { label: string } (1–80 chars)
DELETE	/api/namespaces/:ns/databases/:db/snapshots/:id	Removes the label only
POST	/api/namespaces/:ns/databases/:db/restore	Body: one of { snapshotId }, { bookmark }, { timestamp }

timestamp is unix milliseconds and must fall within the last 30 days. bookmark is the opaque string returned by Cloudflare — useful if you’ve stored bookmarks in your own system.

Restore requires owner or admin on the namespace. Snapshot creation/deletion follows the database’s write permission.

Caveats

• The 30-day horizon is a hard limit. For longer retention, schedule your own dump (e.g. a daily SELECT * FROM … to R2).
• The bookmark string is opaque — treat it as a blob.
• During restore the database is briefly unavailable; clients should retry on 503 / connection errors.