OpenParable
Skip to content
← Back to skills

Supabase Schema Migrations

Development
supabase-schema-migrations

Supabase Schema Migrations is an Agent Skill for development published in the imbhargav5/nextbase-nextjs-supabase-starter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/imbhargav5/nextbase-nextjs-supabase-starter/blob/HEAD/.agents/skills/supabase-schema-migrations/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/supabase-schema-migrations, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.