Migration Test & Push

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

<environments>

Environments

</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](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](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>

<whentouse>

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

<references>

Reference Files

Detailed documentation:

• [Local Mode Steps](references/local-mode.md)
• [Production Mode Steps](references/production-mode.md)
• [Rollback Patterns](references/rollback-patterns.md)
• [Error Recovery](references/error-recovery.md)
• [Command Reference](references/commands.md)

</references>

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