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.

Purpose: Establish a repeatable process for keeping staging and production databases in sync. Last Updated: 2026-01-16

​
Overview

This procedure ensures staging and production databases remain synchronized by:
  1. Identifying migration differences
  2. Applying missing migrations to each environment
  3. Verifying both databases are in sync

​
When to Run Sync

  • After applying migrations to one environment
  • Before major releases
  • When migration divergence is detected
  • Weekly maintenance (recommended)

​
Prerequisites

  • Supabase CLI installed and authenticated
  • Access to both staging and production projects
  • Backups created for both environments

​
Sync Process

​
Step 1: Identify Divergence

# Compare migration histories
# Production
supabase link --project-ref zkgxozahyczcnzpwhbbf
supabase migration list

# Staging  
supabase link --project-ref rzfzikcargkoyhgqllap
supabase migration list
Or use SQL queries: 
SELECT version, name 
FROM supabase_migrations.schema_migrations 
ORDER BY version;

​
Step 2: Create Backups

CRITICAL: Always create backups before syncing. See: reports/database-sync-backup-instructions.md

​
Step 3: Apply Missing Migrations

Use the sync scripts:
  • scripts/database-sync-complete.ps1 (PowerShell)
  • scripts/database-sync-complete.sh (Bash)
Or follow manual steps in: reports/database-sync-execution-guide.md

​
Step 4: Verify Sync

Run verification queries from: scripts/verify-database-sync.sql Key checks:
  • Migration counts match
  • Migration histories identical
  • Schema dumps match
  • RLS policies complete
  • Expected columns exist

​
Step 5: Test

  • Run functional tests on both environments
  • Verify critical workflows
  • Check error logs

​
Prevention

To prevent future divergence:
  1. Always apply migrations to both environments
  2. Use migration files, not manual SQL
  3. Never apply migrations directly via Dashboard without creating migration files
  4. Document all manual changes as migrations

​
Troubleshooting

​
Migration Conflicts

If migrations conflict:
  1. Review both migration files
  2. Determine correct resolution
  3. Create reconciliation migration
  4. Apply to both environments

​
Missing Migration Files

If a migration exists in database but not in codebase:
  1. Extract migration SQL from database
  2. Create migration file with correct timestamp
  3. Add to codebase
  4. Document in sync report
  • reports/database-sync-execution-guide.md - Detailed execution steps
  • reports/database-sync-backup-instructions.md - Backup procedures
  • scripts/verify-database-sync.sql - Verification queries