A disaster recovery runbook for Supabase

A disaster recovery plan is a written answer to one question: when this database is gone or wrong, what exactly do we do? A runbook is that plan made executable — failure scenarios mapped to recovery paths, each with the preconditions it needs, owned by a named person, and rehearsed before it is needed. Supabase gives you real building blocks — daily backups on paid plans, a point-in-time recovery add-on — but building blocks are not a plan: the official backups skip Storage files, live inside the platform they protect, and are never restore-tested. This guide is the missing document: recovery objectives in Supabase terms, a failure-to-path matrix, a three-phase runbook, and a checklist you can pin to the wall.

RPO and RTO, in Supabase terms

Every disaster recovery conversation runs on two numbers. Pin them down first, because they decide everything else you buy or build.

RPO — how much data you can afford to lose

The Recovery Point Objective is the maximum gap, measured in time, between the last recoverable state and the moment of failure. In Supabase terms (numbers checked against the official docs, July 2026): daily backups on the Pro plan and above mean a worst case of roughly 24 hours of lost writes. The PITR add-on archives WAL every two minutes, for a worst-case RPO of two minutes at $100/month per project — if you genuinely need sub-24-hour recovery points, PITR is the right tool and nothing snapshot-based substitutes for it. An external backup’s RPO is simply its schedule: daily snapshots, 24-hour worst case. And the Free plan includes no automated backups at all — its RPO is undefined until you set something up.

RTO — how long recovery takes

The Recovery Time Objective is how long the service may stay down while you recover. Supabase does not publish one, for an honest reason: restore duration depends on database size, and the project is offline for the duration of an in-place restore. Which leads to the uncomfortable rule this whole guide keeps returning to: you do not know your RTO until you have restored a real backup and timed it. A restore drill produces that number as a side effect — the wall-clock restore time of your latest snapshot, measured on a schedule instead of during an outage.

Failure scenarios and the path back

Two facts shape every row of this table: the official backups cover the database only — never Storage files — and they live inside the same platform and account they protect. Scenarios where those two facts bite are the ones where only an external copy saves you.

Where an “external backup” appears above, it means a scheduled copy in a bucket you own — DIY pg_dump (the backup options guide has working commands), a GitHub Actions workflow, or a service like BackupDrill that also backs up Storage files and restore-tests the result. What matters for the matrix is not which tool — it is that the copy exists outside the platform, includes the files, and has been proven to restore.

The runbook, part 1 — before anything breaks

Everything in this section is cheap on a calm Tuesday and expensive to discover missing mid-incident.

• Backup inventory. Write down, per project: the plan tier and what it implies (daily backups from Pro, nothing automated on Free), whether PITR is enabled, where external backups land and on what schedule, whether Storage files are covered, and what the dump actually contains (the public schema by default — not auth, not storage metadata).
• Access and ownership. Name an owner and a deputy. Verify both can log into the Supabase dashboard, both can reach the backup bucket, and both know where this runbook lives — somewhere readable while your own infrastructure is down.
• Pre-migration snapshots. Make “snapshot before migrating” a step in the deploy process, not a habit in someone’s head. The bad-migration row of the matrix is only survivable if this happened.
• Drills on a schedule. The restore testing guide covers the how — manually in Docker, with the open-source CLI, or hosted on a schedule. Weekly for production is the default worth arguing yourself out of; each drill also measures the restore time that becomes your real RTO figure.

Part 2 — during the incident

The failure mode of smart people in an outage is skipping to step five. The order below exists because each step protects the ones after it.

1. Contain the damage

Stop whatever is making it worse before touching backups: pause the deploy, disable the failing job, cut the application’s write path if a bad process is still running. Then — counterintuitive but critical — take a fresh backup of the damaged database. A restore overwrites the current state; if the recovery goes wrong, the damaged state you destroyed still contained every write since the last good snapshot.

2. Establish the scope

Which tables, which files, since when? The damage timestamp decides your recovery point — restoring to yesterday when the corruption started last week recovers corrupted data with extra steps. The damage surface decides the intervention: three deleted rows call for surgical recovery, not a full restore that rolls the whole database back a day.

3. Choose the recovery path

This is what the matrix above is for — match the failure, check the preconditions column honestly. The general rule: prefer the smallest intervention that recovers the data. PITR beats a snapshot for a recent bad write; extracting rows from a restored copy beats an in-place restore; an in-place restore beats migrating to a new project.

4. Verify in a disposable environment first

Restore into a fresh database or a throwaway Postgres and check what came back — table counts, the tables that must never be empty, the recency of an append-heavy table — before production sees any of it. The restore testing guide is this exact loop with working commands. Never point production at unverified data: one recovery is an incident, a bad recovery on top of it is a crisis.

5. Switch over and confirm

Apply the verified recovery — in-place restore, surgical re-insert, or a new project with pg_restore and a file copy — then run application-level checks, the queries your app actually issues. Tell your users what happened and what window of data, if any, was lost. The RPO you wrote down in part 1 is what makes that sentence sayable.

Part 3 — after: the postmortem

• Reconstruct the timeline — detection, decision, recovery — and compare the RPO and RTO you actually achieved against the numbers you assumed. The gap between them is the most useful output of the whole incident.
• Fix the class, not the instance. If a bad migration burned you, the fix is a pre-migration snapshot step in the deploy process — not a resolution to be more careful.
• Add the check that would have caught it earlier — a drill, an alert, a checklist line. Every incident should make the next one shorter.
• Update this runbook the same week, while the wrong assumptions are still fresh. A runbook that survived an incident unchanged was not read during it.

The checklist

Fifteen lines. Print it, pin it, or paste it into the incident channel topic. Every unchecked box is a scenario in the matrix above with a worse ending.

• ☐Automated database backups run on a schedule you chose, and you can say from memory what that schedule is.
• ☐Storage files have their own backup — a database backup alone does not include them.
• ☐At least one backup copy lives outside Supabase, in an account you control.
• ☐The credentials that write backups are not the credentials that run production.
• ☐Your worst-case data loss (RPO) is written down as a number of hours, and someone with authority has accepted it.
• ☐You have restored a real backup at least once and know how long it takes (RTO).
• ☐A restore test ran in the last month, and someone would notice if it stopped running.
• ☐Every schema migration is preceded by a snapshot — as a deploy-process step, not a habit.
• ☐Projects that need sub-24-hour RPO have PITR enabled — or the decision not to pay $100/month per project is recorded.
• ☐The runbook names an owner and a deputy, and either can execute it alone.
• ☐The runbook is reachable when your infrastructure is down.
• ☐Dashboard access and bucket credentials are re-verified quarterly — people leave, keys rotate.
• ☐Backup-failure alerts reach a human, not just a log file.
• ☐Free-plan projects: someone owns the pause risk — either activity is monitored or the 90-day restore window is understood.
• ☐A postmortem template exists, and the last incident actually produced one.

FAQ