DEV Community

william lao
william lao

Posted on

Supabase Free Has No Backups — Here's the Free Way to Add Them

If your side project lives on a Supabase Free project, here is the uncomfortable fact: there are no automated backups. None. If you drop the wrong table tonight, there is no restore button waiting for you in the dashboard tomorrow. The fix Supabase sells you is the Pro plan at $25/month — mostly, for a lot of us, just to get daily backups retained for 7 days.

The DIY fix looks trivial: run pg_dump from a GitHub Actions cron job, upload the result somewhere cheap. It is about 30 lines of YAML. But those 30 lines hide five traps, and every one of them fails quietly — you find out your backup doesn't work on the one day you actually need it.

I hit all five while building my own setup. Here they are, in the order you'll meet them.

Trap 1: The connection string Supabase shows you first breaks pg_dump

In the dashboard (Settings → Database → Connection string), the prominent option is the transaction pooler on port 6543. pg_dump cannot run through it — it needs a real session, and through the transaction pooler the dump fails or hangs with errors that point nowhere near the real cause.

Use the session pooler instead: port 5432, host aws-0-<region>.pooler.supabase.com. Same panel, different tab. This one line is the difference between a working backup and a week of debugging.

Trap 2: The "direct connection" is IPv6-only, and GitHub runners are not

The other string in the dashboard, db.<your-ref>.supabase.co, looks like the obvious choice for a dump. On the Free plan that host is IPv6-only. GitHub-hosted runners are IPv4-only. The result is a connection error that looks exactly like a firewall or credentials problem — it is neither. (This is also why the same string works fine from your laptop on an IPv6 network and fails in CI.)

Session pooler, port 5432. Again. Traps 1 and 2 are the same lesson: the two connection strings Supabase offers first are the two that don't work.

Trap 3: Your pg_dump is older than the server

Supabase runs PostgreSQL 17. The ubuntu-latest GitHub runner ships a PostgreSQL client that tops out at 16 — and pg_dump flatly refuses to dump a server newer than itself:

pg_dump: error: server version mismatch
Enter fullscreen mode Exit fullscreen mode

postgresql-client-17 isn't in Ubuntu's default repos, so the fix is to add PostgreSQL's official PGDG apt repository first, then install the 17 client. Three extra lines in the workflow — once you know you need them.

Trap 4: GitHub silently disables scheduled workflows in public repos

This is the nastiest one because nothing ever errors. If your backup repo is public and sees no activity for 60 days, GitHub disables scheduled workflows — quietly. No failed run, no red X, just backups that stop happening while you believe you're covered.

Put the backup workflow in a private repo. (You want this anyway: the repo holds your database connection string as a secret and your backup config.)

Trap 5: Daily backups blow straight through the Free egress cap

Every dump pulls your entire database out of Supabase, and the Free plan includes 5 GB/month of egress. The math is unforgiving:

  • 500 MB database, dumped weekly → ~2 GB/month. Fine.
  • 500 MB database, dumped daily → ~15 GB/month. Over the cap.

Weekly is the sweet spot on Free. And double-check your cron while you're at it: 42 3 * * 0 is weekly (Sundays 03:42 UTC); drop the trailing 0 and 42 3 * * * quietly becomes daily — trap 5, self-inflicted.

One honest scope note: pg_dump covers your database, including auth.users (they live in the database). It does not cover Storage files — those live in S3, not Postgres, and need a separate approach. Anyone who tells you their pg_dump setup protects "everything" hasn't checked.

The free version: the smallest thing that actually works

Once you know the five traps, the working minimum fits in one workflow:

  1. GitHub Actions cron, weekly, in a private repo
  2. Install postgresql-client-17 from the PGDG repo
  3. pg_dump over the session pooler (5432), custom format
  4. Upload to a Cloudflare R2 bucket (10 GB free tier, zero egress fees)

I packaged exactly this as a free lite version — script, workflow, and a 10-minute setup guide:

→ supabase-free-backup-lite on GitHub

It is deliberately minimal: the dump is uploaded unencrypted, there is no validation that the dump is restorable, and if a run fails, nobody tells you. For a hobby project, that's a fair trade. For a project with real users, those three gaps are exactly where backups go to die — which is why I built the full kit.

The full kit: encryption, proof it restores, and a watchdog

The Supabase Free-Tier Backup Kit is the same weekly workflow with the failure modes engineered out:

  • GPG AES-256 encryption before upload — a leaked R2 credential no longer means a leaked database
  • Pre-flight validator that rejects the 6543 pooler and the IPv6-only host before the run, with an error that names the actual fix, and checks your pg_dump version against the server
  • Validation on every dump: SHA-256 checksum plus pg_restore --list, so a truncated or corrupt dump gets caught the week it's made, not the day you need it
  • A restore drill and step-by-step runbook (English + Chinese): spin up a throwaway Postgres, restore into it, prove it works — because a backup you have never restored is a hope, not a backup
  • Failure alerts via webhook (Slack / Discord), a watchdog bonus workflow that notices if the backup job never runs, and a Healthchecks.io heartbeat
  • An egress calculator for the 5 GB/month cap, and 90-day R2 retention rules (server-side, so CI never holds delete permissions)

It's $29 one-time for the first 50 buyers, then $39 — no subscription, and a 14-day money-back guarantee. Current version is v1.0.7. For scale: Pro is $25 every month. The kit pays for itself in five weeks, and the lite version above stays free forever if money is the blocker.

The one-sentence version

Supabase Free gives you a great database and zero safety net; a weekly pg_dump to R2 closes the hole for $0 — as long as you dodge the pooler, the IPv6 host, the version mismatch, the public-repo kill switch, and the egress cap.

Start with the free lite version today. The worst backup strategy is the one you were meaning to set up next week.

Disclosure: I'm the author of both the lite version and the kit. Everything in the free version is genuinely free and fully functional — the kit exists for the encryption, validation, and restore proof.

Top comments (1)

Collapse
 
mariosfong profile image
Mario Fang •

Trap 4 is the one that would have bitten me — GitHub silently disabling a scheduled workflow after 60 days in a public repo is exactly the kind of failure that looks fine from the dashboard. I learned the same lesson with a nightly job of my own: the schedule said it was running, and the only thing that told the truth was the timestamp on the file it was supposed to produce. These days I check for a fresh dump with today's date rather than a green tick. How often do you actually test a restore from one of those R2 copies — is that part of the routine, or still on the to-do list?