Supabase preview environments per PR: branch, migrate, test, merge, delete

TL;DR

Apply the PR's migrations to it. Run CI against the branch database: migrations apply cleanly, the test suite passes, and the app's critical paths work end to end.

Steps

1. Application preview deployments without a matching database preview prove nothing about migrations. Pair them: one Supabase branch per pull request, wired to that PR's preview deployment.
2. On PR open, create a Supabase branch. Apply the PR's migrations to it. Point the PR's preview deployment at the branch credentials.
3. Seed the branch with production-shaped data (anonymized). An empty database passes tests that real data would fail, especially around constraints and RLS.
4. Run CI against the branch database: migrations apply cleanly, the test suite passes, and the app's critical paths work end to end.
5. Review the migration diff as part of the PR review. The branch proves it applies; the review proves it is correct and reversible.
6. On merge, apply the migrations to production and delete the branch. Stale branches accumulate data and cost; the merge is the trigger for cleanup.

When to use

You are seeing this: Application preview deployments without a matching database preview prove nothing about migrations. Use this skill when you run into "Supabase preview environments per PR: branch, migrate, test, merge, delete".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/deployment/branching