# 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.

- Skill name: `supabase-schema-migrations`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/imbhargav5/nextbase-nextjs-supabase-starter/blob/HEAD/.agents/skills/supabase-schema-migrations/SKILL.md
- Repository: imbhargav5/nextbase-nextjs-supabase-starter (797 GitHub stars when collected)

## SKILL.md

# 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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   pnpm supabase migration up
   ```

7. Run relevant validation:

   ```bash
   pnpm test-db
   ```

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

   ```bash
   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.

---

Source: https://www.openparable.com/skill/development/supabase-schema-migrations (OpenParable). Cite the canonical URL above.
