Migration Test & Push

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

Environments

<mode_selection>

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,
    },
  ];
}

</mode_selection>

<local_workflow>

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 </local_workflow>

<staging_workflow>

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

</staging_workflow>

<production_workflow>

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 </production_workflow>

<approval_gates>

Approval Gates

All gates use AskUserQuestion tool. Stop execution if user declines. </approval_gates>

<safety_rules>

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. </safety_rules>

<quick_reference>

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

</quick_reference>

<when_to_use>

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 </when_to_use>

Reference Files

Detailed documentation:

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

<version_history>

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

</version_history>