Pre-Migration Test Plan: Supabase Cloud Migration

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-01-15
Status: Active

​

Overview

​

Purpose

• Verify data isolation between staging and production branches
• Confirm migration flow (schema changes merge, data does not)
• Validate Vercel environment variable configuration
• Ensure seed data safety mechanisms work correctly

​

Scope

​

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Git Repository                            │
├─────────────────┬──────────────────┬────────────────────────────┤
│   main branch   │  staging branch  │    feature branches        │
└────────┬────────┴────────┬─────────┴──────────┬─────────────────┘
         │                 │                    │
         ▼                 ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Vercel Deployments                           │
├─────────────────┬──────────────────┬────────────────────────────┤
│   Production    │     Staging      │       Preview              │
│ encoreos...app│ encoreos...dev │   auto-generated URL       │
└────────┬────────┴────────┬─────────┴──────────┬─────────────────┘
         │                 │                    │
         │ prod anon key   │ staging anon key   │ staging anon key
         ▼                 ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│           Supabase Project: zkgxozahyczcnzpwhbbf                 │
├─────────────────┬───────────────────────────────────────────────┤
│  Production DB  │            Staging Branch DB                   │
│  (main project) │   (isolated data, shared schema when merged)   │
└─────────────────┴───────────────────────────────────────────────┘

​

Key Points

1. Same Project URL: All environments use https://zkgxozahyczcnzpwhbbf.supabase.co (expected for branching)
2. Different Anon Keys: Each branch has unique API keys (critical for isolation)
3. Data Isolation: Staging data never transfers to production
4. Schema Sync: Migrations merge from staging to production on PR merge

​

Prerequisites Checklist

​

Supabase Dashboard Verification

• Branching Enabled: Project has branching feature enabled
• Staging Branch Exists: Persistent branch named “staging” is active
• Branch Status: Staging branch shows “ACTIVE_HEALTHY” status
• API Keys Different:
  • Production anon key: eyJ... (ends differently than staging)
  • Staging anon key: eyJ... (ends differently than production)

​

Vercel Dashboard Verification

• Project Connected: cloud-migration-path project exists
• Environment Variables Set:
  • VITE_SUPABASE_URL (same for all environments - correct)
  • VITE_SUPABASE_ANON_KEY (different per environment)
  • VITE_APP_ENV (production, staging, preview)
• Deployment Active: Latest deployment shows “READY” status

​

GitHub Verification

• Branch Protection: main branch has protection rules
• Staging Branch: staging branch exists and is synced
• GitHub Integration: Supabase GitHub integration is connected

​

Test Cases

​

T001: Data Isolation - Seed Data in Staging Only

• Staging branch is active
• Seed files exist in supabase/seeds/

1. Apply seed data to staging:
   npx supabase db seed --linked
   
2. Verify seed data exists in staging:
   -- Run against STAGING
   SELECT COUNT(*) FROM pf_organizations WHERE id::text LIKE '00000000-%';
   -- Expected: > 0 (seed organizations exist)
   
3. Verify seed data does NOT exist in production:
   -- Run against PRODUCTION
   SELECT COUNT(*) FROM pf_organizations WHERE id::text LIKE '00000000-%';
   -- Expected: 0 (no seed organizations)
   

• PASS: Production seed count = 0, Staging seed count > 0
• FAIL: Any seed data appears in production

​

T002: Migration Flow - Schema Changes Merge

• Feature branch with new migration exists
• Staging branch is synced with feature branch

1. Create a test migration in staging:
   -- Create test table (will be removed after test)
   CREATE TABLE IF NOT EXISTS public.test_migration_verify (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     test_data TEXT,
     created_at TIMESTAMPTZ DEFAULT NOW()
   );
   
2. Commit migration to staging Git branch
3. Verify table exists in staging:
   SELECT EXISTS (
     SELECT FROM pg_tables WHERE tablename = 'test_migration_verify'
   );
   -- Expected: true
   
4. Create PR from staging to main and merge
5. Verify table now exists in production:
   SELECT EXISTS (
     SELECT FROM pg_tables WHERE tablename = 'test_migration_verify'
   );
   -- Expected: true
   
6. Clean up: Create migration to drop test table

• PASS: Table appears in production after merge
• FAIL: Table does not appear, or appears before merge

​

T003: Migration Flow - Data Does Not Merge

• T002 has passed (test table exists in both environments)

1. Insert test data in staging:
   -- Run against STAGING
   INSERT INTO test_migration_verify (test_data) VALUES ('staging_test_data');
   
2. Verify data exists in staging:
   -- Run against STAGING
   SELECT COUNT(*) FROM test_migration_verify WHERE test_data = 'staging_test_data';
   -- Expected: 1
   
3. Verify data does NOT exist in production:
   -- Run against PRODUCTION
   SELECT COUNT(*) FROM test_migration_verify WHERE test_data = 'staging_test_data';
   -- Expected: 0
   

• PASS: Production has 0 test records, staging has 1
• FAIL: Any test data appears in production

​

T004: Vercel Integration - Correct API Keys Per Environment

• Production deployment is live
• Staging deployment is live (or preview deployment exists)

1. Access production deployment:
   • URL: https://northsightrecovery.app or production Vercel URL
   • Open browser DevTools → Network tab
   • Observe API requests to Supabase
2. Verify production anon key in requests:
   • Check Authorization: Bearer <token> header
   • Token should match production anon key
3. Access staging deployment:
   • URL: https://northsightrecovery.dev or staging Vercel URL
   • Open browser DevTools → Network tab
4. Verify staging anon key in requests:
   • Token should be DIFFERENT from production

• PASS: Anon keys are different between environments
• FAIL: Same anon key used in both environments

​

T005: Seed Safety - Production Detection Works

• Seed files exist with safety checks
• Access to test against production (carefully!)

1. Review seed file safety check:
   -- Expected pattern in seed files
   DO $$
   BEGIN
     IF EXISTS (
       SELECT 1 FROM pf_organizations 
       WHERE id NOT LIKE '00000000-%'
       LIMIT 1
     ) THEN
       RAISE WARNING 'Real data detected. Ensure you are connected to staging.';
     END IF;
   END $$;
   
2. Verify safety check is present in all seed files:
   grep -l "Real data detected" supabase/seeds/**/*.sql
   
3. If production has real data, attempt to run seed (will warn/fail)

• PASS: Safety check present and functional
• FAIL: No safety check or check bypassed

​

T006: RLS Verification - Tenant Isolation Active

• Database schema is deployed

1. Count tables with RLS enabled:
   SELECT COUNT(*) FROM pg_tables 
   WHERE schemaname = 'public' AND rowsecurity = true;
   -- Expected: > 400 (most tables have RLS)
   
2. Verify critical tables have RLS:
   SELECT tablename, rowsecurity FROM pg_tables 
   WHERE schemaname = 'public' 
   AND tablename IN ('pf_organizations', 'hr_employees', 'fa_accounts')
   ORDER BY tablename;
   -- Expected: All show rowsecurity = true
   

• PASS: All critical tables have RLS enabled
• FAIL: Any critical table missing RLS

​

Current Database State (Verified via MCP)

​

Staging Branch Status

​

Key Tables Available

• pf_organizations - Platform organizations
• hr_employees - HR employees
• hr_* - 50+ HR module tables
• rh_* - Recovery Housing tables (rh_alumni, rh_beds, etc.)
• fa_* - Finance module tables
• fw_* - Forms/Workflow tables

​

Rollback Procedures

​

If Seed Data Accidentally Applied to Production

1. Immediate Action: Do NOT merge any branches
2. Identify seed records:
   SELECT * FROM pf_organizations WHERE id::text LIKE '00000000-%';
   
3. Delete seed records (if safe):
   DELETE FROM pf_organizations WHERE id::text LIKE '00000000-%';
   
4. Verify cleanup:
   SELECT COUNT(*) FROM pf_organizations WHERE id::text LIKE '00000000-%';
   -- Should return 0
   

​

If Migration Causes Issues

1. Do NOT panic - Supabase branches are isolated
2. For staging: Reset the branch
   supabase branches reset <branch-id>
   
3. For production: Create rollback migration
   supabase migration new rollback_issue
   # Write reverse DDL statements
   

​

If Vercel Environment Variables Wrong

1. Go to Vercel Dashboard → Project → Settings → Environment Variables
2. Update incorrect variable
3. Trigger redeploy:
   vercel --prod  # for production
   vercel         # for preview
   

​

Sign-Off Checklist

​

Pre-Migration Sign-Off

• All test cases (T001-T006) have passed
• Staging branch has seed data (T001)
• Production has no seed data (T001)
• Schema changes merge correctly (T002)
• Data stays isolated (T003)
• Vercel uses correct keys (T004)
• Seed safety checks work (T005)
• RLS is active on all tables (T006)

​

Final Approvals

​

Related Documentation

• Pre-Migration Checklist - Manual verification steps
• Vercel Integration Guide - Vercel configuration
• Supabase MCP Usage - MCP tool reference
• Migration Completion Plan - Overall migration plan
• Seed Files README - Seed file documentation

​

Appendix: SQL Verification Queries

​

Quick Reference Queries

-- Check staging is clean (no seed data)
SELECT COUNT(*) FROM pf_organizations WHERE id::text LIKE '00000000-%';

-- Count RLS-enabled tables
SELECT COUNT(*) FROM pg_tables WHERE schemaname = 'public' AND rowsecurity = true;

-- View recent migrations
SELECT version, name FROM supabase_migrations.schema_migrations ORDER BY version DESC LIMIT 10;

-- Check table exists
SELECT EXISTS (SELECT FROM pg_tables WHERE tablename = 'your_table_name');