Migration Test And Push

Migration Test & Push

Promotion pipeline for database migrations: Local → Staging → Production with gates at each stage.

Environments

Step 0: Choose Mode (Always First)

Use AskUserQuestion to determine workflow:

{
  questions: [
    {
      question: "What do you want to do with this migration?",
      header: "Mode",
      options: [
        {
          label: "Test locally only",
          description:
            "Reset local DB, run pgTAP, setup dev. No commit, no push.",
        },
        {
          label: "Push to staging only",
          description:
            "Test locally first, then push to staging for E2E testing.",
        },
        {
          label: "Full deployment",
          description:
            "Complete pipeline: local → staging → production with all safety gates.",
        },
      ],
      multiSelect: false,
    },
  ];
}

LOCAL MODE (6 Steps)

Quick local testing - no commits, no remote changes.

Result: Ready for testing at localhost:8080. No commit, no push.

For detailed steps: references/local-mode.md

STAGING MODE (8 Steps)

Push to staging for Vercel E2E testing. Includes local testing first.

Result: Staging database updated. Ready for Vercel E2E tests.

Note: No backup needed for staging (test data only). No types commit (staging types not used).

FULL DEPLOYMENT MODE (18 Steps)

Complete promotion pipeline: Local → Staging → Production.

Critical: Each stage must pass before proceeding to the next.

For detailed steps: references/production-mode.md

Approval Gates

All gates use AskUserQuestion tool. Stop execution if user declines.

Safety Rules

Rule 1: Sequential Promotion

Local → Staging → Production

Never skip environments. Each must pass before proceeding.

Rule 2: Never Push Without Approval

Use AskUserQuestion before any npx supabase db push - required for safety.

Rule 3: Follow Exact Workflow Order

Never skip or reorder steps within a phase.

Rule 4: Stop on Any Error

• Local test fails → STOP, fix migration
• Staging push fails → STOP, investigate
• User denies → STOP, cancel deployment
• Production push fails → STOP, show rollback guidance

Rule 5: Permission is Temporary

Add pattern to bash_validator.py before production push, remove immediately after.

Rule 6: Backup Before Production Only

Staging uses test data - no backup needed. Production requires backup.

Quick Reference

Local Testing

npx supabase db reset
npm run test:sql
npx supabase gen types typescript --local > src/integrations/supabase/types.ts

Staging Push

npx supabase link --project-ref <staging-project-id>
npx supabase db push --dry-run
npx supabase db push

Production Push

npx supabase link --project-ref <production-project-id>
npx supabase db push --dry-run
npx supabase db push
npx supabase gen types typescript --project-id <production-project-id> > src/integrations/supabase/types.ts

Verification (both staging and production)

SELECT version FROM supabase_migrations.schema_migrations ORDER BY version DESC LIMIT 1;

Production Backup

PGPASSWORD="<password>" pg_dump -h aws-0-us-west-1.pooler.supabase.com -p 6543 \
  -U postgres.<production-project-id> -d postgres --schema=public -Fc \
  > supabase/backups/pre_migration_$(date +%Y%m%d_%H%M%S).dump

When to Use

Triggers for this skill:

• "test migration"
• "push migration"
• "deploy migration"
• "reset local database"
• "apply migration"
• "db push"
• "test and push"
• "push to staging"
• "push to production"

Ambiguous requests → Ask which mode first

Reference Files

Detailed documentation:

• Local Mode Steps
• Production Mode Steps
• Rollback Patterns
• Error Recovery
• Command Reference

Version History

• v4.0.0 (2026-01-19): Add staging environment to promotion pipeline

  • New 3-tier workflow: Local → Staging → Production
  • Added staging project ID (<staging-project-id>)
  • New "Push to staging only" mode for E2E test prep
  • Full deployment now includes staging verification before production
  • Updated approval gates for staging push

• v3.1.0 (2025-01-18): AI optimization updates

  • Add blockquote summary after title
  • Soften directive language (NON-NEGOTIABLE → required for production safety)

• v3.0.0 (2025-12-28): Rewrite following Anthropic best practices

  • Progressive disclosure: Core in SKILL.md, details in references/
  • XML tags for structure
  • Imperative form throughout
  • Reduced from 1,071 lines to ~200 lines

• v2.0.0 (2025-12-28): Merged with migration-test-local skill

  • Mode selection (local test vs production push)
  • Local mode: 7 steps, no commits
  • Production mode: 16 steps, full safety

• v1.2.0 (2025-12-28): Industry best practices update

  • Test BEFORE commit workflow order
  • Added rollback analysis, locking check, backup, verification

• v1.0.0 (2025-10-26): Initial release