Discipline

The Supabase Migration Playbook

Migration discipline — numbering, guards, application, and the never-destructive rule.

SUPABASE-MIGRATION-PLAYBOOK.md · 14 sections · 1,767 words · 14 KB · markdown

How to change a production schema without losing data. Sequential numbering, IF NOT EXISTS guards so a re-run is a no-op, applying via the Management API, tracking what's actually been applied, and the hard rule that sync routines never delete.

What's inside

//Numbering and file-naming convention
//IF NOT EXISTS guards that make every migration re-runnable
//Applying migrations via the Management API
//An applied-migration tracking doc pattern
//The never-destructive rule and the incident that produced it
//PostgREST gotchas: float-to-int coercion, the 1000-row cap

When to use it

Every migration. Every time.

Build these first

App Infrastructure

Straight from the file

Every migration must be safe to re-apply against a DB where it has already run. Real-world reason: applied-state tracking drifts; you WILL re-run a migration by accident; the migration must no-op gracefully instead of crashing.

Table of contents

0. Use this spec
1. File naming convention (load-bearing)
2. Idempotency is mandatory
3. Application: how to actually run a migration
4. Applied-migration tracking
Applied
Pending (in repo, not yet live)
Skipped (intentionally not applied)
5. RLS hygiene — non-negotiable
6. Never destructive on user-owned data
7. Schema patterns that age well
8. Approval + backup workflow
9. Common pitfalls
10. Kickoff prompt

How to run it

Drop SUPABASE-MIGRATION-PLAYBOOK.md into your repo, then tell Claude Code: “Read SUPABASE-MIGRATION-PLAYBOOK.md and implement it in this codebase.” It's written for an agent to execute end to end. Search the file for angle-bracket placeholders and swap in your own project names, domains, and keys before the first run.

↓ Download the playbook

More discipline playbooks

C-tier

← All 28 Claude templates

The Supabase Migration Playbook

Pre-Production Hardening

Core Web Vitals Audit

AI Compliance Gate