Loading post…
SupabaseqiaoExplainer
How a new branch gets its config, migrations, and functions
Summary
Supabase branches are independent projects that require settings, schema, and edge functions to be set up before use. When a branch is created, configuration copies main project settings including Postgres, Auth, and Realtime config, then applies them with a single Postgres restart via walg_enable; Auth secrets do not carry over. Migrations come from the git repo for GitHub-connected branches or from the main project’s migration history for gitless branches; each file runs as one transaction in pipeline mode. Edge functions are copied from the main project at creation in parallel with configuration, and on each push only changed functions are redeployed using Brotli compression and SHA-256 checksums. If a step fails, it shows as DEAD and stops dependent steps, while PAUSED indicates a warning that does not block subsequent steps.
Context
Supabase branches are independent projects that need settings, schema, and edge functions set up before use. The post explains the branching workflow: how configuration is copied and applied, where migrations come from and how they run, how edge functions are deployed, and what happens when steps fail.
Approach / What changed
The approach involves three parallel steps when a branch is created: configuration copies main project settings (Postgres, Auth, Realtime, etc.) and applies them with a single Postgres restart via walg_enable; migrations apply schema from the git repo (GitHub-connected) or from the main project’s migration history (gitless), with each file running as one transaction in pipeline mode; edge functions are copied from the main project at creation or deployed from the repo on each push, with unchanged functions skipped via Brotli-compressed SHA-256 checksum comparison. GitHub-connected branches also run a repo workflow that applies config.toml settings on top of the copied config.
Takeaways
Configuration writes Postgres settings to disk without restarting, then a single restart via walg_enable applies them and starts backups, avoiding multiple restarts.
Migrations run each file as one transaction in pipeline mode; a file either applies fully or rolls back, and the splitter is validated against PG 16 with a large corpus.
Edge function deployment skips unchanged functions by comparing Brotli-compressed bundle SHA-256 checksums and JWT settings; copied functions reuse the main project’s compressed bundle.
FAQ
How does a gitless branch get its migrations?
A gitless branch reads supabase_migrations.schema_migrations from the main project, where each row holds version, name, and statements. The pull step turns each row into a migration file and also reads the branch's own history to avoid reapplying already-run migrations.
What happens when a migration file fails?
The migration runs as one transaction; if any statement fails, the entire file rolls back and leaves no trace in the history table. The error shows which statement failed with a caret at the position.
How are Edge Functions deployed on each push?
On each push, the deploy step builds the function bundle, compresses it with Brotli, computes a SHA-256 checksum, and compares it with the stored checksum and JWT setting. If both match, the function is skipped; otherwise the new bundle is uploaded.
Source and freshness
- Source
- supabase.com
- Published
- Added to Yomu
Summaries are generated from the original by a language model. Check the original before relying on it.
Keep reading
Related reading
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
The best engineering reads, once a week
One useful email. Unsubscribe anytime.