# Supabase → Local Postgres Migration Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Migrate IMS database from Supabase cloud to self-hosted local postgres with zero data loss, enable full self-hosting. **Architecture:** Five-phase migration: pre-flight checks → export from Supabase → import to local → validate data → cutover app → decommission Supabase **Tech Stack:** PostgreSQL 13+, pg_dump/psql utilities, bcryptjs password hashes, SSH access to production ## Global Constraints - Production server: 175.136.239.121:9321 (user setia) - Local postgres: 127.0.0.1:5433/ims (credentials in .env.production) - App location: /var/www/ims (PM2 wsims process) - Data volume: ~100MB, 30 users, 500 incidents - Downtime: 1-2 hour planned maintenance window acceptable - Supabase backup retention: 7 days (rollback window) - Password hashes: bcryptjs format ($2a$ or $2b$ prefix only) --- ## Task 1: Pre-Migration Verification & Planning **Files:** - Read: `/Users/yapweeihan/Projects/IMS.nosync/docs/superpowers/specs/2026-09-30-supabase-to-local-migration-design.md` - No files modified in this task **Interfaces:** - Consumes: Migration design spec - Produces: Pre-migration checklist (mental model), timeline confirmation - [ ] **Step 1: Verify Supabase access** You need Supabase credentials to export the database. Check that you have: - Supabase project URL: `nkcfjbgappslicotwopl.supabase.co` - Supabase database password (from project settings) - OR access to Supabase console at https://app.supabase.com (project: nkcfjbgappslicotwopl) If you have console access, you can export via the UI (Database → Backups → Download). If you need CLI access, construct connection string: ``` postgres://postgres:@db.nkcfjbgappslicotwopl.supabase.co:5432/postgres ``` - [ ] **Step 2: Verify production server access** Test SSH access to production: ```bash ssh -p 9321 setia@175.136.239.121 "uname -a" ``` Expected output: Linux kernel info. If fails, check SSH keys and network. - [ ] **Step 3: Verify local postgres is running on production** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c 'SELECT version();'" ``` Expected output: PostgreSQL version string. If fails, postgres is down or config wrong. - [ ] **Step 4: Check disk space on production** ```bash ssh -p 9321 setia@175.136.239.121 "df -h | grep -E '^/dev/|Mounted'" ``` Expected: At least 500MB free on `/var/www` (for 100MB DB import + overhead). - [ ] **Step 5: Get Supabase row counts (baseline for validation)** Log into Supabase console or run: ```bash psql "postgres://postgres:@db.nkcfjbgappslicotwopl.supabase.co:5432/postgres" -c " SELECT 'users' as table_name, COUNT(*) as count FROM users UNION ALL SELECT 'incidents', COUNT(*) FROM incidents UNION ALL SELECT 'investigations', COUNT(*) FROM investigations UNION ALL SELECT 'capa_actions', COUNT(*) FROM capa_actions UNION ALL SELECT 'evidence_files', COUNT(*) FROM evidence_files; " ``` Record these numbers. You'll compare them post-import. - [ ] **Step 6: Verify local postgres schema exists** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c '\dt'" ``` Expected output: List of tables (users, incidents, investigations, etc.). If empty, run migrations first (Task 2). --- ## Task 2: Prepare Local Postgres Schema (If Empty) **Files:** - Read: `/Users/yapweeihan/Projects/IMS.nosync/db/schema.sql` - Modify: /var/www/ims/.env.production (no changes yet, just verify) - Execute on: Production server (127.0.0.1:5433/ims) **Interfaces:** - Consumes: Local postgres empty database - Produces: Full schema with all tables, indexes, constraints - [ ] **Step 1: Check if schema exists** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c 'SELECT COUNT(*) as table_count FROM information_schema.tables WHERE table_schema = '\''public'\'''" ``` If `table_count` > 0, schema exists. Skip to Task 3. If `table_count` = 0, continue to Step 2. - [ ] **Step 2: Run migrations on local postgres** The IMS app uses Drizzle ORM. Migrations live in: ```bash ls -la /Users/yapweeihan/Projects/IMS.nosync/supabase/migrations/ ``` Transfer the schema from Supabase using pg_dump (metadata only): ```bash # Get Supabase connection string SUPABASE_URL="postgres://postgres:@db.nkcfjbgappslicotwopl.supabase.co:5432/postgres" # Dump schema only (no data) from Supabase pg_dump -s "$SUPABASE_URL" > /tmp/supabase-schema.sql # Import schema to local postgres ssh -p 9321 setia@175.136.239.121 "cat > /tmp/schema.sql << 'SCHEMA_EOF' $(cat /tmp/supabase-schema.sql) SCHEMA_EOF" ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_admin -d ims -f /tmp/schema.sql" ``` - [ ] **Step 3: Verify schema created** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c '\dt'" ``` Expected output: All tables listed (users, incidents, investigations, capa_actions, evidence_files, etc.). --- ## Task 3: Export Data from Supabase **Files:** - No files modified - Output: `/tmp/supabase-full-backup.sql` (on local machine) **Interfaces:** - Consumes: Supabase connection (postgres://...) - Produces: SQL dump file with all data - [ ] **Step 1: Create Supabase backup via console (safest method)** 1. Log into https://app.supabase.com 2. Select project: nkcfjbgappslicotwopl 3. Go to Database → Backups 4. Click "Back up now" (takes 1-5 minutes) 5. Download the backup file Save as `/tmp/supabase-full-backup.sql` on your local machine. **Alternative: Export via pg_dump CLI** ```bash SUPABASE_URL="postgres://postgres:@db.nkcfjbgappslicotwopl.supabase.co:5432/postgres" pg_dump "$SUPABASE_URL" \ --no-password \ --compress=0 \ > /tmp/supabase-full-backup.sql ``` Expected: File created, size ~100MB. - [ ] **Step 2: Verify dump file** ```bash ls -lh /tmp/supabase-full-backup.sql file /tmp/supabase-full-backup.sql ``` Expected: File exists, size ~100MB, type: ASCII text / SQL script. - [ ] **Step 3: Record Supabase row counts (for later validation)** Get these numbers from Task 1, Step 5. Write them down: ``` users: [count] incidents: [count] investigations: [count] capa_actions: [count] evidence_files: [count] ``` You'll use these in Task 5 (validation). --- ## Task 4: Import Data to Local Postgres & Announce Downtime **Files:** - Transfer: `/tmp/supabase-full-backup.sql` → production server - Modify: Production server configuration (Task 6) **Interfaces:** - Consumes: Supabase dump file - Produces: Full database populated in local postgres - [ ] **Step 1: Announce maintenance window** Send to users (via email, Slack, or in-app banner): ``` Subject: Scheduled Maintenance - Database Migration We will be performing a scheduled database migration on [DATE] from [TIME] to [TIME] (~1-2 hours). During this time, IMS will be unavailable. This is required to move our infrastructure to on-premises servers for better performance and data residency. We apologize for any inconvenience. Thank you, IMS Team ``` - [ ] **Step 2: Stop IMS app on production** ```bash ssh -p 9321 setia@175.136.239.121 "pm2 stop wsims" ``` Expected output: `[wsims] ✓`. App is now stopped. Verify: ```bash ssh -p 9321 setia@175.136.239.121 "pm2 list | grep wsims" ``` Expected: wsims shows `stopped`. - [ ] **Step 3: Copy dump file to production server** ```bash scp -P 9321 /tmp/supabase-full-backup.sql setia@175.136.239.121:/tmp/ ``` Expected: File transferred, no errors. - [ ] **Step 4: Backup current local postgres (in case we need to rollback)** ```bash ssh -p 9321 setia@175.136.239.121 "pg_dump -h 127.0.0.1 -p 5433 -U app_admin -d ims > /tmp/local-postgres-pre-migration-backup.sql" ``` This creates a backup of the (empty) local DB. Takes <1 minute. - [ ] **Step 5: Import Supabase dump to local postgres** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_admin -d ims -f /tmp/supabase-full-backup.sql" ``` Expected output: Many `CREATE`, `INSERT`, `ALTER` statements. Should take 5-15 minutes for 100MB. Monitor for errors: ```bash ssh -p 9321 setia@175.136.239.121 "tail -50 /tmp/pg_import.log" ``` If errors about permissions or sequences, see Troubleshooting below. - [ ] **Step 6: Verify import completed without syntax errors** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c 'SELECT COUNT(*) as total_tables FROM information_schema.tables WHERE table_schema = '\''public'\''''" ``` Expected output: `total_tables | [number > 10]` (should be 14+ tables). --- ## Task 5: Validate Data Integrity Post-Import **Files:** - No files modified - Read: Supabase row counts from Task 3, Step 3 **Interfaces:** - Consumes: Imported local database - Produces: Validation report (console output, no files) - [ ] **Step 1: Compare row counts** Run on production: ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c \" SELECT 'users' as table_name, COUNT(*) as count FROM users UNION ALL SELECT 'incidents', COUNT(*) FROM incidents UNION ALL SELECT 'investigations', COUNT(*) FROM investigations UNION ALL SELECT 'capa_actions', COUNT(*) FROM capa_actions UNION ALL SELECT 'evidence_files', COUNT(*) FROM evidence_files; \"" ``` **Compare with baseline from Task 3, Step 3:** - users: should match - incidents: should match - investigations: should match - capa_actions: should match - evidence_files: should match If any counts differ, STOP and investigate (likely partial import failure). - [ ] **Step 2: Check for orphaned foreign keys** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c \" SELECT COUNT(*) as orphan_incidents FROM incidents WHERE reported_by NOT IN (SELECT id FROM users); SELECT COUNT(*) as orphan_investigations FROM investigations WHERE incident_id NOT IN (SELECT id FROM incidents); \"" ``` Expected output: `0` for both counts. If > 0, data is corrupted — rollback and re-import. - [ ] **Step 3: Verify password hash format** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c \" SELECT id, email, LEFT(password_hash, 4) as hash_prefix FROM users LIMIT 5; \"" ``` Expected output: All hash_prefix values start with `$2a$` or `$2b$` (bcryptjs format). If any are different, password hashes are corrupted. - [ ] **Step 4: Spot-check recent data** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c \" SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 3; SELECT id, title, created_at FROM incidents ORDER BY created_at DESC LIMIT 3; \"" ``` Expected: Recent records visible with correct timestamps. If missing or corrupted, rollback. - [ ] **Step 5: Check constraint integrity** ```bash ssh -p 9321 setia@175.136.239.121 "psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c \" SELECT constraint_name FROM information_schema.table_constraints WHERE table_schema = 'public' AND constraint_type IN ('PRIMARY KEY', 'FOREIGN KEY') ORDER BY table_name; \"" ``` Expected output: List of constraints (> 20). If empty, schema import failed. - [ ] **Step 6: Document validation results** Create a validation report (paste this into a text file): ``` MIGRATION VALIDATION REPORT Date: [current date] Supabase → Local Postgres Row Counts: - users: [count] ✓/✗ - incidents: [count] ✓/✗ - investigations: [count] ✓/✗ - capa_actions: [count] ✓/✗ - evidence_files: [count] ✓/✗ Data Integrity: - Orphaned foreign keys: 0 ✓ - Password hashes: bcryptjs format ($2a$/$2b$) ✓ - Recent data: Present and uncorrupted ✓ - Constraints: [count] ✓ Status: PASSED / FAILED ``` Keep this for post-migration review. --- ## Task 6: Update Application Configuration & Cutover **Files:** - Modify: `/var/www/ims/.env.production` (on production server) - No code changes **Interfaces:** - Consumes: Migrated database, validation passed - Produces: App configured to use local postgres, Supabase vars removed - [ ] **Step 1: Get current .env.production to understand its structure** ```bash ssh -p 9321 setia@175.136.239.121 "grep -E 'DATABASE_URL|SUPABASE' /var/www/ims/.env.production" ``` Expected output: ``` DATABASE_URL=postgres://app_user:...@127.0.0.1:5433/ims DATABASE_URL_ADMIN=postgres://app_admin:...@127.0.0.1:5433/ims NEXT_PUBLIC_SUPABASE_URL=https://nkcfjbgappslicotwopl.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_... SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOi... ``` - [ ] **Step 2: Back up the current .env.production** ```bash ssh -p 9321 setia@175.136.239.121 "cp /var/www/ims/.env.production /var/www/ims/.env.production.backup.$(date +%s)" ``` This preserves the old config in case you need to rollback. - [ ] **Step 3: Remove Supabase variables** SSH into production and edit .env.production to remove these lines: ```bash ssh -p 9321 setia@175.136.239.121 "cat > /tmp/update_env.sh << 'EOF' #!/bin/bash cd /var/www/ims # Remove Supabase-specific vars sed -i '/^NEXT_PUBLIC_SUPABASE_URL=/d' .env.production sed -i '/^NEXT_PUBLIC_SUPABASE_ANON_KEY=/d' .env.production sed -i '/^SUPABASE_SERVICE_ROLE_KEY=/d' .env.production echo 'Supabase vars removed from .env.production' EOF chmod +x /tmp/update_env.sh /tmp/update_env.sh" ``` - [ ] **Step 4: Verify DATABASE_URL is set correctly** ```bash ssh -p 9321 setia@175.136.239.121 "grep '^DATABASE_URL=' /var/www/ims/.env.production" ``` Expected output: ``` DATABASE_URL=postgres://app_user:145edf53b9fdca6b189ccf6260422809355b0ce258178ecdeba206f825dcd144@127.0.0.1:5433/ims ``` If missing or wrong, restore from backup and re-edit. - [ ] **Step 5: Restart IMS app** ```bash ssh -p 9321 setia@175.136.239.121 "pm2 restart wsims" ``` Expected output: `[wsims] ✓`. Wait 5 seconds for startup. - [ ] **Step 6: Verify app started successfully** ```bash ssh -p 9321 setia@175.136.239.121 "pm2 list | grep wsims" ``` Expected: wsims shows `online` with uptime > 0s. If `errored` or `stopped`, check logs: ```bash ssh -p 9321 setia@175.136.239.121 "pm2 logs wsims --lines 50" ``` Look for connection errors. If found, rollback to Supabase and debug. - [ ] **Step 7: Test login** Go to https://ims.setia.com.my and login with credentials: - Email: `admin@ims.local` - Password: `Admin@1234` (if this was set earlier) Expected: Login succeeds, redirected to admin dashboard. - [ ] **Step 8: Manual functional tests** In app, verify: 1. Click "Incidents" → list loads (data present) 2. Click one incident → detail page loads with all data 3. Click "Create Incident" → form loads 4. Fill out test incident, submit → incident created, appears in list 5. Check email notifications work (if configured) If any test fails, check logs and rollback if needed. --- ## Task 7: Post-Migration Cleanup & Documentation **Files:** - Modify: `/Users/yapweeihan/Projects/IMS.nosync/CLAUDE.md` - Modify: `/Users/yapweeihan/.claude/projects/-Users-yapweeihan-Projects-Setia/memory/ims-database-setup.md` - Create: `/Users/yapweeihan/Projects/IMS.nosync/docs/database/local-postgres-setup.md` - No production files **Interfaces:** - Consumes: Successful migration + validation - Produces: Updated documentation, decommission plan for Supabase - [ ] **Step 1: Update CLAUDE.md to remove Supabase references** Read the current CLAUDE.md: ```bash grep -n "Supabase\|supabase" /Users/yapweeihan/Projects/IMS.nosync/CLAUDE.md ``` Find and remove any sections mentioning Supabase setup. Replace with local postgres requirement. In CLAUDE.md, find the Stack section and update: ``` - **DB + Auth + Storage:** Supabase (Postgres + RLS + pgvector) ``` Change to: ``` - **DB:** Local PostgreSQL 13+ at 127.0.0.1:5433 (see docs/database/local-postgres-setup.md for setup) ``` - [ ] **Step 2: Update memory/ims-database-setup.md** Edit the memory file: ```bash cat /Users/yapweeihan/.claude/projects/-Users-yapweeihan-Projects-Setia/memory/ims-database-setup.md ``` Change the status from "needs setup" to "migrated Sep 30 2026". Update the "Action items" section to mark items complete: ``` - [x] Initialize local postgres with schema migrations - [x] Seed admin@ims.local user - [x] Verify app uses local DB not cloud - [ ] Remove Supabase dependency (future) - [x] Update deployment docs (CLAUDE.md) ``` - [ ] **Step 3: Create new database setup documentation** Create `/Users/yapweeihan/Projects/IMS.nosync/docs/database/local-postgres-setup.md`: ```markdown # Local PostgreSQL Setup Guide ## Connection Details IMS uses a local PostgreSQL database for development and production: - **Host:** 127.0.0.1 - **Port:** 5433 - **Database:** ims - **App user:** app_user (read/write) - **Admin user:** app_admin (read/write/DDL) Credentials are stored in `.env.production`. ## Running Locally ### Install PostgreSQL ```bash # macOS brew install postgresql@13 # Ubuntu/Debian sudo apt-get install postgresql postgresql-contrib ``` ### Create Database ```bash createdb -U postgres ims ``` ### Run Migrations ```bash # Using Supabase migrations (in supabase/migrations/) # Copy the SQL files from supabase/migrations/ into a local migration tool # Or manually import the schema: psql -U postgres -d ims < db/schema.sql ``` ### Backup & Restore **Backup:** ```bash pg_dump -h 127.0.0.1 -p 5433 -U app_admin -d ims > backup.sql ``` **Restore:** ```bash psql -h 127.0.0.1 -p 5433 -U app_admin -d ims -f backup.sql ``` ## Monitoring Check disk usage: ```bash df -h | grep -E '^/dev/' ``` Check query performance: ```bash psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c "EXPLAIN ANALYZE " ``` ## Troubleshooting **Connection refused:** Verify postgres is running (`pg_isready`), port is correct, credentials match. **"role 'app_user' does not exist":** Create the role: ```bash psql -U postgres -c "CREATE ROLE app_user WITH PASSWORD 'password' CREATEDB;" ``` **Disk space full:** Vacuum old data: ```bash psql -h 127.0.0.1 -p 5433 -U app_admin -d ims -c "VACUUM FULL ANALYZE;" ``` ``` Save this file and commit in the next task. - [ ] **Step 4: Mark Supabase for decommissioning** In the migration report, document: ``` Supabase Project Decommissioning Plan: - Backup retention period: 7 days (ends Oct 7, 2026) - Deletion scheduled: Oct 8, 2026 - Contact: [your name/team] - Reason: Migrated to local postgres for self-hosting Do NOT delete Supabase project before Oct 8 without explicit approval. ``` - [ ] **Step 5: Commit documentation updates** ```bash cd /Users/yapweeihan/Projects/IMS.nosync git add CLAUDE.md docs/database/local-postgres-setup.md git commit -m "docs: update database documentation post-Supabase migration Removed Supabase references, added local postgres setup guide. Migration completed Sep 30 2026. Co-Authored-By: Claude Haiku 4.5 " ``` - [ ] **Step 6: Update memory and commit** Edit `/Users/yapweeihan/.claude/projects/-Users-yapweeihan-Projects-Setia/memory/ims-database-setup.md`: Change the description to: ``` IMS database migrated from Supabase to local postgres (Sep 30 2026) ``` Update the document content to reflect completion. Then: ```bash git add /Users/yapweeihan/.claude/projects/-Users-yapweeihan-Projects-Setia/memory/ims-database-setup.md git commit -m "memory: mark database migration complete" ``` - [ ] **Step 7: Create post-migration monitoring task** Add to documentation or as a note: ``` Post-Migration Monitoring (Next 30 days): - Day 1-7: Monitor local postgres daily for performance issues, disk space - Day 7: Backup is safe to delete - Day 30: If no issues, mark as stable Alert if: - Disk usage > 80% - Query latency > 1s for standard operations - Connection pool exhausted - Any login/auth failures ``` --- ## Rollback Procedure (If Needed) **If migration fails during cutover:** 1. Restore `.env.production` from backup: ```bash ssh -p 9321 setia@175.136.239.121 "cp /var/www/ims/.env.production.backup.* /var/www/ims/.env.production" ``` 2. Restart app: ```bash ssh -p 9321 setia@175.136.239.121 "pm2 restart wsims" ``` 3. App will reconnect to Supabase 4. Investigate issue and re-attempt migration after fixes **Do not delete Supabase backup for at least 7 days.** --- ## Success Checklist - [ ] Supabase dump exported successfully - [ ] Local postgres schema created (or verified existing) - [ ] Data imported to local postgres - [ ] Row counts match Supabase baseline - [ ] No orphaned foreign keys - [ ] Password hashes intact (bcryptjs format) - [ ] App stops cleanly before migration - [ ] .env.production updated (Supabase vars removed, DATABASE_URL correct) - [ ] App restarts and comes online - [ ] Login works with local credentials - [ ] Dashboard loads, incidents visible - [ ] Test incident created successfully - [ ] Documentation updated (CLAUDE.md, memory, new postgres setup guide) - [ ] All changes committed to git - [ ] Supabase backup retained for 7-day rollback window