Supabase Migration Assistant Launcher

Generate, validate, test, and apply Supabase database migrations with automatic TypeScript type generation and rollback support.

When to Use This Command

Run this command when you need to:

• Create new SQL migration files for schema changes with proper versioning and dependency ordering
• Validate migrations against a development database before applying to staging or production
• Generate updated TypeScript types after schema changes to keep client code in sync

Consider alternatives when:

• You need a one-time ad-hoc query without schema changes (use smart-supabase-tool)
• You want to compare schemas between environments (use supabase-schema-sync-action)

Quick Start

Configuration

Copy
name: supabase-migration-assistant-launcher
type: command
category: database

Example Invocation

Copy
claude command:run supabase-migration-assistant-launcher --action create --name add-user-preferences-table

Example Output

[Context] Supabase project detected from supabase/config.toml
[Migrations] Existing: 14 migrations (latest: 20260310_add_audit_logs)

[Generate] Migration: 20260315_add_user_preferences_table.sql
  CREATE TABLE user_preferences (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
    theme TEXT DEFAULT 'light',
    notifications JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT now()
  );
  RLS policy: enabled (user can read/write own rows)

[Validate] Dry-run on local dev... PASSED
[Types] TypeScript types regenerated: src/types/database.ts
[Rollback] Rollback migration created: 20260315_add_user_preferences_table_down.sql

Core Concepts

Migration Management Overview

Aspect	Details
File Format	Timestamped SQL files in supabase/migrations/ directory
Validation	Dry-run against local Supabase instance before remote deployment
Type Generation	Auto-generates TypeScript interfaces from the updated schema
Rollback	Creates companion _down.sql files for every forward migration

Migration Workflow

[Plan Schema Change]
        |
[Generate Migration SQL]
        |
[Create Rollback SQL]
        |
[Validate on Local Dev]
   |          |
 Pass        Fail --> [Fix + Retry]
   |
[Generate TypeScript Types]
        |
[Apply to Remote (staging/prod)]

Configuration

Parameter	Type	Default	Description
action	string	create	Operation: create, validate, apply, rollback, or generate-types
name	string	required	Descriptive name for the migration (used in filename)
include-rls	boolean	true	Auto-generate RLS policies for new tables
include-rollback	boolean	true	Generate companion rollback migration file
target	string	local	Target environment: local, staging, or production

Best Practices

1. One Change Per Migration - Each migration file should contain a single logical change (one table, one column addition, one index). This makes rollbacks predictable and debugging straightforward.

2. Always Generate Rollback Files - Keep --include-rollback enabled. Even if you never use them, rollback files document the reverse operation and are critical during incident response.

3. Validate Locally Before Remote - Always run --action validate against your local Supabase instance first. Catching SQL errors locally is instant; catching them in production is an incident.

4. Regenerate Types After Every Migration - Run --action generate-types after applying migrations to keep your TypeScript interfaces in sync. Stale types cause runtime errors that the compiler cannot catch.

5. Review RLS Policies Carefully - Auto-generated RLS policies use sensible defaults but may not match your authorization model. Review every generated policy against your access control requirements.

Common Issues

1. Migration Order Conflict in Team - Two developers creating migrations simultaneously may generate conflicting timestamps. Coordinate via a shared migration naming convention or rebase before applying.

2. Rollback Fails on Data-Dependent Changes - Dropping a column that already contains data requires explicit CASCADE or data migration. The auto-generated rollback may not handle data preservation.

3. Type Generation Shows Stale Schema - If types do not reflect recent migrations, ensure the local Supabase instance has all migrations applied. Run supabase db reset to rebuild from scratch.