supabase-schema-migrations

name

supabase-schema-migrations

description

Enforce the Nextbase Supabase schema-first migration workflow. Use when changing database structure, RLS policies, functions, triggers, enums, indexes, extensions, generated database types, or any files under apps/database/supabase; especially when asked to create, update, fix, or review database migrations. Requires editing or creating declarative schema files first, generating migrations with the Supabase CLI, and never manually creating or editing migration SQL files.

Supabase Schema Migrations

Use Supabase declarative schemas as the source of truth for database changes in this repo.

Non-Negotiables

• Keep repo-local skills only in .agents/skills; do not duplicate them in .codex, .claude, or other runner-specific skill directories.
• Never manually create migration files in apps/database/supabase/migrations.
• Never manually edit generated migration files.
• Never paste hand-written SQL directly into a migration file.
• Make schema changes first in apps/database/supabase/schemas/*.sql.
• Generate migrations from the schema diff with the Supabase CLI.
• Read generated migrations for review only. If the generated SQL is wrong, fix the schema file and regenerate.

Workflow

1. Work from apps/database for Supabase CLI commands.

2. Ensure the local Supabase stack is running:

   pnpm start
   

3. Add or update declarative schema SQL in supabase/schemas/*.sql.

   • Keep schema files focused by domain or object.
   • Preserve dependency order. Schema files run lexicographically unless supabase/config.toml declares [db.migrations].schema_paths.
   • When adding table columns, append new columns to the end to avoid noisy diffs for entities that care about order.

4. Generate a migration from the schema diff:

   pnpm supabase db diff -f descriptive_snake_case_name
   

5. Review the generated migration under supabase/migrations.

   • Confirm it contains only the intended incremental change.
   • If it contains unrelated churn, do not hand-edit it. Fix schema/local DB drift, remove the generated migration if needed, and regenerate.

6. Apply the pending migration locally:

   pnpm supabase migration up
   

7. Run relevant validation:

   pnpm test-db
   

   From the repo root, regenerate local types when schema shape changes:

   pnpm gen-types-local
   

Unsupported or Risky Changes

Supabase schema diff does not reliably capture every database operation, including DML such as insert, update, or delete, and some ownership, grants, comments, partition, publication, policy, or domain edge cases.

If a requested change cannot be represented safely through declarative schema files and generated diffs:

• Stop before writing a manual migration.
• Explain the limitation.
• Ask the user for explicit direction.

Review Checklist

Before finishing database work, verify:

• This repo-local skill exists only under .agents/skills.
• Schema changes are in supabase/schemas/*.sql.
• Migration files were generated by pnpm supabase db diff, not written by hand.
• Generated migration SQL matches the intended schema change.
• pnpm supabase migration up succeeds locally.
• pnpm test-db passes or any failure is reported.
• pnpm gen-types-local was run when generated TypeScript database types should change.