@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-migration-deep-dive/SKILL.md

@@ -1,244 +1,405 @@
 ---
 name: supabase-migration-deep-dive
-description: |
-  Execute Supabase major re-architecture and migration strategies with strangler fig pattern.
-  Use when migrating to or from Supabase, performing major version upgrades,
-  or re-platforming existing integrations to Supabase.
-  Trigger with phrases like "migrate supabase", "supabase migration",
-  "switch to supabase", "supabase replatform", "supabase upgrade major".
-allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(node:*), Bash(kubectl:*)
+description: 'Database migration patterns with Supabase CLI: npx supabase migration
+  new, zero-downtime
+
+  migrations, data backfill strategies, schema versioning, rollback strategies, and
+  type generation.
+
+  Use when creating database migrations, performing zero-downtime schema changes,
+  backfilling
+
+  data in production, managing schema versions, or planning rollback strategies.
+
+  Trigger: "supabase migration", "supabase schema change", "supabase zero downtime",
+
+  "supabase rollback", "supabase db push", "supabase migration new".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(npx supabase:*), Bash(supabase:*), Bash(psql:*),
+  Grep, Glob
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- migration
+- database
+- schema
+- zero-downtime
+- rollback
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Supabase Migration Deep Dive
 
 ## Overview
-Comprehensive guide for migrating to or from Supabase, or major version upgrades.
+
+Supabase migrations are SQL files managed by the CLI that track schema changes across environments. This skill covers the complete migration lifecycle: creating migrations with `npx supabase migration new`, writing zero-downtime schema changes that avoid table locks, backfilling data in batches, managing schema versioning across environments, planning rollback strategies, and regenerating TypeScript types after schema changes. Every pattern uses real Supabase CLI commands and `createClient` from `@supabase/supabase-js`.
+
+**When to use:** Creating new database migrations, modifying production schemas without downtime, backfilling existing data after adding columns, managing migration history across dev/staging/production, rolling back failed migrations, or regenerating TypeScript types.
 
 ## Prerequisites
-- Current system documentation
-- Supabase SDK installed
-- Feature flag infrastructure
-- Rollback strategy tested
 
-## Migration Types
+- Supabase CLI installed: `npm install -g supabase` or `npx supabase --version`
+- `@supabase/supabase-js` v2+ installed in your project
+- Local Supabase running: `npx supabase start`
+- Understanding of PostgreSQL DDL and transaction behavior
 
-| Type | Complexity | Duration | Risk |
-|------|-----------|----------|------|
-| Fresh install | Low | Days | Low |
-| From competitor | Medium | Weeks | Medium |
-| Major version | Medium | Weeks | Medium |
-| Full replatform | High | Months | High |
+## Instructions
+
+### Step 1: Create and Manage Migrations
 
-## Pre-Migration Assessment
+Use the Supabase CLI to create, test, and apply migrations. Each migration is a timestamped SQL file that runs in order.
+
+**Create a new migration:**
 
-### Step 1: Current State Analysis
 ```bash
-# Document current implementation
-find . -name "*.ts" -o -name "*.py" | xargs grep -l "supabase" > supabase-files.txt
+# Create a migration file with a descriptive name
+npx supabase migration new add_profiles_table
+# Creates: supabase/migrations/20260322120000_add_profiles_table.sql
 
-# Count integration points
-wc -l supabase-files.txt
+# List all migrations and their status
+npx supabase migration list
 
-# Identify dependencies
-npm list | grep supabase
-pip freeze | grep supabase
+# Check which migrations have been applied locally
+npx supabase db reset --dry-run
 ```
 
-### Step 2: Data Inventory
-```typescript
-interface MigrationInventory {
-  dataTypes: string[];
-  recordCounts: Record<string, number>;
-  dependencies: string[];
-  integrationPoints: string[];
-  customizations: string[];
-}
-
-async function assessSupabaseMigration(): Promise<MigrationInventory> {
-  return {
-    dataTypes: await getDataTypes(),
-    recordCounts: await getRecordCounts(),
-    dependencies: await analyzeDependencies(),
-    integrationPoints: await findIntegrationPoints(),
-    customizations: await documentCustomizations(),
-  };
-}
+**Write the migration SQL:**
+
+```sql
+-- supabase/migrations/20260322120000_add_profiles_table.sql
+
+-- Create the profiles table
+CREATE TABLE public.profiles (
+  id uuid REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
+  email text UNIQUE NOT NULL,
+  full_name text,
+  avatar_url text,
+  bio text,
+  created_at timestamptz DEFAULT now(),
+  updated_at timestamptz DEFAULT now()
+);
+
+-- Enable RLS
+ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
+
+-- Create policies
+CREATE POLICY "users_read_own_profile" ON public.profiles
+  FOR SELECT USING (auth.uid() = id);
+
+CREATE POLICY "users_update_own_profile" ON public.profiles
+  FOR UPDATE USING (auth.uid() = id)
+  WITH CHECK (auth.uid() = id);
+
+-- Create an index for email lookups
+CREATE INDEX idx_profiles_email ON public.profiles(email);
+
+-- Auto-create profile on user signup (trigger)
+CREATE OR REPLACE FUNCTION public.handle_new_user()
+RETURNS trigger AS $$
+BEGIN
+  INSERT INTO public.profiles (id, email, full_name, avatar_url)
+  VALUES (
+    new.id,
+    new.email,
+    new.raw_user_meta_data ->> 'full_name',
+    new.raw_user_meta_data ->> 'avatar_url'
+  );
+  RETURN new;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+CREATE TRIGGER on_auth_user_created
+  AFTER INSERT ON auth.users
+  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();
+
+-- Updated_at trigger
+CREATE OR REPLACE FUNCTION public.update_updated_at()
+RETURNS trigger AS $$
+BEGIN
+  new.updated_at = now();
+  RETURN new;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER set_updated_at
+  BEFORE UPDATE ON public.profiles
+  FOR EACH ROW EXECUTE FUNCTION public.update_updated_at();
 ```
 
-## Migration Strategy: Strangler Fig Pattern
+**Test the migration locally:**
 
+```bash
+# Apply all migrations and seed data (destructive — resets local DB)
+npx supabase db reset
+
+# Run pgTAP tests if configured
+npx supabase test db
+
+# Verify the schema
+npx supabase db lint
+
+# Generate updated TypeScript types
+npx supabase gen types typescript --local > lib/database.types.ts
 ```
-Phase 1: Parallel Run
-┌─────────────┐     ┌─────────────┐
-│   Old       │     │   New       │
-│   System    │ ──▶ │  Supabase   │
-│   (100%)    │     │   (0%)      │
-└─────────────┘     └─────────────┘
-
-Phase 2: Gradual Shift
-┌─────────────┐     ┌─────────────┐
-│   Old       │     │   New       │
-│   (50%)     │ ──▶ │   (50%)     │
-└─────────────┘     └─────────────┘
-
-Phase 3: Complete
-┌─────────────┐     ┌─────────────┐
-│   Old       │     │   New       │
-│   (0%)      │ ──▶ │   (100%)    │
-└─────────────┘     └─────────────┘
+
+**Apply migrations to remote environments:**
+
+```text
+# Push to staging
+npx supabase link --project-ref <staging-ref>
+npx supabase db push
+# Verify: npx supabase migration list --linked
+
+# Push to production (same migration files)
+npx supabase link --project-ref <prod-ref>
+npx supabase db push
 ```
 
-## Implementation Plan
+### Step 2: Zero-Downtime Migration Patterns
 
-### Phase 1: Setup (Week 1-2)
-```bash
-# Install Supabase SDK
-npm install @supabase/supabase-js
+Production schema changes must avoid locking tables. These patterns ensure migrations complete without blocking reads or writes.
 
-# Configure credentials
-cp .env.example .env.supabase
-# Edit with new credentials
+**Add a column (safe — no lock):**
 
-# Verify connectivity
-node -e "require('@supabase/supabase-js').ping()"
+```sql
+-- supabase/migrations/20260323000000_add_status_column.sql
+
+-- Adding a nullable column with a default does NOT lock the table in Postgres 11+
+ALTER TABLE public.orders ADD COLUMN status text DEFAULT 'pending';
+
+-- Create an index CONCURRENTLY (does not block writes)
+-- NOTE: CONCURRENTLY cannot run inside a transaction block
+-- Supabase migrations run each file in a transaction, so use a separate migration
 ```
 
-### Phase 2: Adapter Layer (Week 3-4)
-```typescript
-// src/adapters/supabase.ts
-interface ServiceAdapter {
-  create(data: CreateInput): Promise<Resource>;
-  read(id: string): Promise<Resource>;
-  update(id: string, data: UpdateInput): Promise<Resource>;
-  delete(id: string): Promise<void>;
-}
+```sql
+-- supabase/migrations/20260323000001_add_status_index.sql
 
-class SupabaseAdapter implements ServiceAdapter {
-  async create(data: CreateInput): Promise<Resource> {
-    const supabaseData = this.transform(data);
-    return supabaseClient.create(supabaseData);
-  }
+-- This migration must run outside a transaction for CONCURRENTLY
+-- Add this comment at the top of the file:
+-- supabase:disable-transaction
 
-  private transform(data: CreateInput): SupabaseInput {
-    // Map from old format to Supabase format
-  }
-}
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_status
+  ON public.orders(status);
 ```
 
-### Phase 3: Data Migration (Week 5-6)
-```typescript
-async function migrateSupabaseData(): Promise<MigrationResult> {
-  const batchSize = 100;
-  let processed = 0;
-  let errors: MigrationError[] = [];
-
-  for await (const batch of oldSystem.iterateBatches(batchSize)) {
-    try {
-      const transformed = batch.map(transform);
-      await supabaseClient.batchCreate(transformed);
-      processed += batch.length;
-    } catch (error) {
-      errors.push({ batch, error });
-    }
-
-    // Progress update
-    console.log(`Migrated ${processed} records`);
-  }
-
-  return { processed, errors };
-}
+**Rename a column (two-phase approach):**
+
+```sql
+-- Phase 1: Add new column, backfill, update application code
+-- supabase/migrations/20260324000000_add_display_name.sql
+
+-- Add the new column
+ALTER TABLE public.profiles ADD COLUMN display_name text;
+
+-- Copy data from old column
+UPDATE public.profiles SET display_name = full_name WHERE display_name IS NULL;
+
+-- Create a trigger to keep both columns in sync during transition
+CREATE OR REPLACE FUNCTION sync_name_columns()
+RETURNS trigger AS $$
+BEGIN
+  IF TG_OP = 'INSERT' OR NEW.full_name IS DISTINCT FROM OLD.full_name THEN
+    NEW.display_name = NEW.full_name;
+  END IF;
+  IF TG_OP = 'INSERT' OR NEW.display_name IS DISTINCT FROM OLD.display_name THEN
+    NEW.full_name = NEW.display_name;
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER sync_names
+  BEFORE INSERT OR UPDATE ON public.profiles
+  FOR EACH ROW EXECUTE FUNCTION sync_name_columns();
 ```
 
-### Phase 4: Traffic Shift (Week 7-8)
-```typescript
-// Feature flag controlled traffic split
-function getServiceAdapter(): ServiceAdapter {
-  const supabasePercentage = getFeatureFlag('supabase_migration_percentage');
+```sql
+-- Phase 2: After all application code uses display_name (deploy + verify)
+-- supabase/migrations/20260325000000_drop_full_name.sql
 
-  if (Math.random() * 100 < supabasePercentage) {
-    return new SupabaseAdapter();
-  }
+-- Remove the sync trigger
+DROP TRIGGER IF EXISTS sync_names ON public.profiles;
+DROP FUNCTION IF EXISTS sync_name_columns();
 
-  return new LegacyAdapter();
-}
+-- Drop the old column
+ALTER TABLE public.profiles DROP COLUMN full_name;
 ```
 
-## Rollback Plan
+**Change column type (safe approach):**
 
-```bash
-# Immediate rollback
-kubectl set env deployment/app SUPABASE_ENABLED=false
-kubectl rollout restart deployment/app
+```sql
+-- supabase/migrations/20260326000000_change_price_to_numeric.sql
+
+-- DON'T DO THIS (locks table for the entire rewrite):
+-- ALTER TABLE orders ALTER COLUMN price TYPE numeric(10,2);
+
+-- SAFE: Add new column, backfill, swap
+ALTER TABLE public.orders ADD COLUMN price_numeric numeric(10,2);
 
-# Data rollback (if needed)
-./scripts/restore-from-backup.sh --date YYYY-MM-DD
+-- Backfill in a separate migration or via application code
+UPDATE public.orders SET price_numeric = price::numeric(10,2)
+WHERE price_numeric IS NULL;
 
-# Verify rollback
-curl https://app.yourcompany.com/health | jq '.services.supabase'
+-- After verifying all data is backfilled:
+-- ALTER TABLE public.orders DROP COLUMN price;
+-- ALTER TABLE public.orders RENAME COLUMN price_numeric TO price;
 ```
 
-## Post-Migration Validation
+**Verify zero-downtime from the SDK:**
 
 ```typescript
-async function validateSupabaseMigration(): Promise<ValidationReport> {
-  const checks = [
-    { name: 'Data count match', fn: checkDataCounts },
-    { name: 'API functionality', fn: checkApiFunctionality },
-    { name: 'Performance baseline', fn: checkPerformance },
-    { name: 'Error rates', fn: checkErrorRates },
-  ];
-
-  const results = await Promise.all(
-    checks.map(async c => ({ name: c.name, result: await c.fn() }))
-  );
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
+
+// Run during migration to verify no downtime
+async function migrationHealthCheck(tableName: string) {
+  const checks = [];
+
+  for (let i = 0; i < 10; i++) {
+    const start = performance.now();
+    const { error } = await supabase
+      .from(tableName)
+      .select('id')
+      .limit(1);
+
+    checks.push({
+      attempt: i + 1,
+      latencyMs: Math.round(performance.now() - start),
+      success: !error,
+      error: error?.message,
+    });
+
+    await new Promise((r) => setTimeout(r, 1000));
+  }
 
-  return { checks: results, passed: results.every(r => r.result.success) };
+  const failures = checks.filter((c) => !c.success);
+  console.log(`Health check: ${checks.length - failures.length}/${checks.length} passed`);
+  if (failures.length > 0) {
+    console.warn('Failures:', failures);
+  }
 }
 ```
 
-## Instructions
-
-### Step 1: Assess Current State
-Document existing implementation and data inventory.
+### Step 3: Data Backfill, Versioning, and Rollback
 
-### Step 2: Build Adapter Layer
-Create abstraction layer for gradual migration.
+See [data backfill, versioning, and rollback](references/backfill-versioning-rollback.md) for batch backfill patterns with the SDK, schema versioning across environments, three rollback strategies (compensating migration, repair, feature flags), and type regeneration after migrations.
 
-### Step 3: Migrate Data
-Run batch data migration with error handling.
+## Output
 
-### Step 4: Shift Traffic
-Gradually route traffic to new Supabase integration.
+After completing this skill, you will have:
 
-## Output
-- Migration assessment complete
-- Adapter layer implemented
-- Data migrated successfully
-- Traffic fully shifted to Supabase
+- **Migration creation workflow** — `npx supabase migration new` with descriptive SQL files and local testing
+- **Zero-downtime patterns** — safe column additions, two-phase renames, concurrent index creation
+- **Batch backfill** — SDK-based row-by-row updates with progress logging and rate limiting
+- **Schema versioning** — `supabase migration list` and `db diff` for comparing environments
+- **Rollback strategies** — compensating migrations, `migration repair`, and feature-flagged schema changes
+- **Type regeneration** — `supabase gen types typescript` after every schema change
+- **Migration promotion** — `db push` workflow from local to staging to production
 
 ## Error Handling
-| Issue | Cause | Solution |
+
+| Error | Cause | Solution |
 |-------|-------|----------|
-| Data mismatch | Transform errors | Validate transform logic |
-| Performance drop | No caching | Add caching layer |
-| Rollback triggered | Errors spiked | Reduce traffic percentage |
-| Validation failed | Missing data | Check batch processing |
+| `migration has already been applied` | Re-running existing migration | Use `supabase migration list` to check status; never modify applied migrations |
+| `cannot run inside a transaction block` | `CREATE INDEX CONCURRENTLY` in transaction | Add `-- supabase:disable-transaction` comment at top of migration file |
+| `column does not exist` after migration | Migration not applied or types stale | Run `supabase db push` then `supabase gen types typescript` |
+| `deadlock detected` during backfill | Concurrent updates on same rows | Reduce batch size; add retry logic with exponential backoff |
+| `statement timeout` on large table | Migration takes longer than timeout | Increase `statement_timeout` in migration: `SET statement_timeout = '300s';` |
+| `migration repair` failed | Wrong version number | Use exact version from `supabase migration list` (the timestamp prefix) |
+| `db diff` shows unexpected changes | Schema drift from manual SQL Editor changes | Run `supabase db pull` to capture manual changes as a migration |
+| Type mismatch after migration | Generated types don't match new schema | Delete `database.types.ts` and regenerate from `--local` or `--linked` |
 
 ## Examples
 
-### Quick Migration Status
+**Example 1 — Complete migration workflow:**
+
+```text
+# 1. Create migration
+npx supabase migration new add_tags_to_projects
+
+# 2. Write SQL
+cat > supabase/migrations/20260322150000_add_tags_to_projects.sql << 'SQL'
+ALTER TABLE public.projects ADD COLUMN tags text[] DEFAULT '{}';
+CREATE INDEX idx_projects_tags ON public.projects USING GIN(tags);
+SQL
+
+# 3. Test locally
+npx supabase db reset
+npx supabase gen types typescript --local > lib/database.types.ts
+
+# 4. Push to staging
+npx supabase link --project-ref <staging-ref>
+npx supabase db push
+
+# 5. Push to production
+npx supabase link --project-ref <prod-ref>
+npx supabase db push
+```
+
+**Example 2 — Backfill with progress tracking:**
+
 ```typescript
-const status = await validateSupabaseMigration();
-console.log(`Migration ${status.passed ? 'PASSED' : 'FAILED'}`);
-status.checks.forEach(c => console.log(`  ${c.name}: ${c.result.success}`));
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(url, serviceRoleKey, {
+  auth: { autoRefreshToken: false, persistSession: false },
+});
+
+// Backfill default tags for existing projects
+const { count } = await supabase
+  .from('projects')
+  .select('*', { count: 'exact', head: true })
+  .is('tags', null);
+
+console.log(`${count} projects need backfill`);
+
+await backfillColumn('projects', 'tags', (row) => {
+  // Derive tags from project name and description
+  const tags: string[] = [];
+  if (row.name?.includes('API')) tags.push('api');
+  if (row.name?.includes('Web')) tags.push('web');
+  return tags.length > 0 ? tags : ['untagged'];
+});
+```
+
+**Example 3 — Safe enum migration:**
+
+```sql
+-- supabase/migrations/20260328000000_add_order_status_enum.sql
+
+-- DON'T: ALTER TYPE with new values inside a transaction
+-- DO: Use text with CHECK constraint instead
+
+ALTER TABLE public.orders
+  ADD CONSTRAINT chk_order_status
+  CHECK (status IN ('pending', 'processing', 'shipped', 'delivered', 'cancelled'));
+
+-- To add a new status later, just drop and recreate the constraint:
+-- ALTER TABLE public.orders DROP CONSTRAINT chk_order_status;
+-- ALTER TABLE public.orders ADD CONSTRAINT chk_order_status
+--   CHECK (status IN ('pending', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded'));
 ```
 
 ## Resources
-- [Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html)
-- [Supabase Migration Guide](https://supabase.com/docs/migration)
 
-## Flagship+ Skills
-For advanced troubleshooting, see `supabase-advanced-troubleshooting`.
+- [Database Migrations — Supabase Docs](https://supabase.com/docs/guides/deployment/database-migrations)
+- [Supabase CLI Migration Commands](https://supabase.com/docs/reference/cli/supabase-migration)
+- [supabase db push — Supabase Docs](https://supabase.com/docs/reference/cli/supabase-db-push)
+- [supabase gen types — Supabase Docs](https://supabase.com/docs/reference/cli/supabase-gen-types)
+- [Zero-Downtime PostgreSQL Migrations](https://www.postgresql.org/docs/current/sql-altertable.html)
+- [supabase db diff — Supabase Docs](https://supabase.com/docs/reference/cli/supabase-db-diff)
+
+## Next Steps
+
+- For advanced troubleshooting after migrations, see `supabase-advanced-troubleshooting`
+- For multi-environment migration promotion, see `supabase-multi-env-setup`
+- For performance tuning after schema changes, see `supabase-performance-tuning`