Skip to main content

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.

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: 
supabase link --project-ref srcaoozjkrughebmbvfb
supabase db push --dry-run
supabase db push
Then validate: 
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