> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PROD Migration Promotion Runbook

> This runbook documents the safe path for promoting migrations from repo state to hosted production Supabase.

**Version:** 1.0.0\
**Last Updated:** 2026-05-13\
**Owner:** Platform / Database maintainers

***

## Scope

This runbook documents the safe path for promoting migrations from repo state to hosted production Supabase.

Use this for both:

* normal release promotion, and
* targeted catch-up windows when production trails development.

***

## Preconditions

* PR to `production` includes reviewed migration files.
* `db-migration-guard` and `supabase-ci` checks are green.
* Supabase credentials are available in CI/secrets (or local env for manual path):
  * `SUPABASE_ACCESS_TOKEN`
  * `SUPABASE_PROJECT_ID` / project link context

***

## Standard promotion path (preferred)

1. Open PR targeting `production`.
2. Confirm migration review, lane checks, and dry-run outputs.
3. Merge PR.
4. Observe `.github/workflows/supabase-deploy-prod.yml` execution.
5. Confirm `supabase db push` success in workflow logs.

***

## Manual fallback path

If CI deployment is unavailable, run manually from a clean checkout:

```bash theme={null}
supabase link --project-ref srcaoozjkrughebmbvfb
supabase db push --dry-run
supabase db push
```

Then validate:

```bash theme={null}
npm run db:catalog:remote:prod
npm run db:docs:refresh:prod
npm run db:docs:check:prod
```

***

## Post-promotion verification checklist

* [ ] `supabase db push` completed with no failed migrations.
* [ ] Hosted PROD catalog snapshot refreshed successfully.
* [ ] `docs/database/SCHEMA_CATALOG.PROD.md` regenerated.
* [ ] DEV vs PROD table/policy deltas reviewed for expected differences only.
* [ ] Any follow-up drift or hotfix migration captured in a new PR (no direct manual DDL drift).

***

## Catch-up window notes

For multi-file catch-up batches:

* Review each pending migration for destructive operations (`DROP TABLE`, `DROP COLUMN`, `ALTER TYPE`, `DROP FUNCTION`).
* Verify index statements are transaction-safe for Supabase migrations (avoid `CONCURRENTLY` inside transactional migrations unless explicitly supported by tooling).
* If a migration fails mid-batch, author a forward-fix migration; do not rewrite applied production migration history.

### Partition migrations (two-phase safety)

When a batch includes partition strategy migrations (see `ADR-020`), treat cutover as a separate tracked operation:

1. **Phase 1 only in standard promotion:** shadow partition table, sync trigger, helper functions.
2. **Backfill and parity checks:** before any rename/swap, validate row-count variance within 0.1% (or \<= 100 rows absolute), compute sampled record hashes with SHA-256 (1% sample up to 10,000 rows per partition), and include recent + overlap windows for time partitions (for example, last 30 days plus prior 7-day overlap). Reference ADR-020 and this runbook's cutover checklist for evidence capture.
3. **Cutover window:** perform writer/read-path cutover in an explicit maintenance window with rollback criteria.
4. **Retention drops:** run prune helpers with dry-run first, review output, then execute.

Do not combine phase-1 schema setup and phase-2 cutover in the same unreviewed promotion batch.

### Current catch-up batch (after PROD `20260512220528`)

1. `20260512231500_cl46_fix_problem_permission_helper.sql`
2. `20260513041000_ce13_sequence_alignment.sql`
3. `20260513042000_ce13_sequence_permissions.sql`
4. `20260513043000_ce13_sequence_executor_cron.sql`
5. `20260513050000_ce13_active_enrollment_index_concurrently.sql`
6. `20260513051000_ce13_reorder_sequence_steps_rpc.sql`
7. `20260513052000_ce13_sequence_delete_policies_admin.sql`
8. `20260513120123_permissions_sync_eba09871.sql`
9. `20260513122600_fix_fw_execution_worker_role_assignments.sql`
10. `20260513124500_ce08_enhancements_schema_foundation.sql`
11. `20260513125500_fix_form_analytics_cron_and_backfill.sql`
12. `20260513130700_fix_fw_enqueue_submission_automations_trigger.sql`
13. `20260513132700_fix_form_completion_metrics_rls_args.sql`
14. `20260513175000_permissions_sync_pf30_nav_permission_backfill.sql`

***

## Related references

* [MIGRATION\_LANES.md](/development/supabase/MIGRATION_LANES)
* [SUPABASE\_CLI\_LOCAL\_WORKFLOW.md](/development/supabase/SUPABASE_CLI_LOCAL_WORKFLOW)
* [ADR-020: Two-Phase Partition Strategy](https://github.com/Encore-OS/encoreos/blob/development/docs/architecture/decisions/ADR-020-partitioned-event-and-audit-tables.md)