7-task implementation plan with step-by-step instructions: - Task 1: Pre-migration verification - Task 2: Prepare local postgres schema - Task 3: Export data from Supabase - Task 4: Import to local + announce downtime - Task 5: Validate data integrity - Task 6: Update app config & cutover - Task 7: Post-migration cleanup & docs Estimated timeline: 3-4 hours total (1-2 hours downtime). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
21 KiB
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 (
2aor2bprefix 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:<password>@db.nkcfjbgappslicotwopl.supabase.co:5432/postgres
- Step 2: Verify production server access
Test SSH access to production:
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
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
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:
psql "postgres://postgres:<password>@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
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
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:
ls -la /Users/yapweeihan/Projects/IMS.nosync/supabase/migrations/
Transfer the schema from Supabase using pg_dump (metadata only):
# Get Supabase connection string
SUPABASE_URL="postgres://postgres:<password>@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
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)
- Log into https://app.supabase.com
- Select project: nkcfjbgappslicotwopl
- Go to Database → Backups
- Click "Back up now" (takes 1-5 minutes)
- Download the backup file
Save as /tmp/supabase-full-backup.sql on your local machine.
Alternative: Export via pg_dump CLI
SUPABASE_URL="postgres://postgres:<password>@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
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
ssh -p 9321 setia@175.136.239.121 "pm2 stop wsims"
Expected output: [wsims] ✓. App is now stopped.
Verify:
ssh -p 9321 setia@175.136.239.121 "pm2 list | grep wsims"
Expected: wsims shows stopped.
- Step 3: Copy dump file to production server
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)
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
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:
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
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:
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
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
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
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
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
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
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:
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
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
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
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:
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:
- Click "Incidents" → list loads (data present)
- Click one incident → detail page loads with all data
- Click "Create Incident" → form loads
- Fill out test incident, submit → incident created, appears in list
- 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:
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:
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:
# 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
createdb -U postgres ims
Run Migrations
# 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:
pg_dump -h 127.0.0.1 -p 5433 -U app_admin -d ims > backup.sql
Restore:
psql -h 127.0.0.1 -p 5433 -U app_admin -d ims -f backup.sql
Monitoring
Check disk usage:
df -h | grep -E '^/dev/'
Check query performance:
psql -h 127.0.0.1 -p 5433 -U app_user -d ims -c "EXPLAIN ANALYZE <query>"
Troubleshooting
Connection refused: Verify postgres is running (pg_isready), port is correct, credentials match.
"role 'app_user' does not exist": Create the role:
psql -U postgres -c "CREATE ROLE app_user WITH PASSWORD 'password' CREATEDB;"
Disk space full: Vacuum old data:
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 <noreply@anthropic.com>"
- 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:
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:
-
Restore
.env.productionfrom backup:ssh -p 9321 setia@175.136.239.121 "cp /var/www/ims/.env.production.backup.* /var/www/ims/.env.production" -
Restart app:
ssh -p 9321 setia@175.136.239.121 "pm2 restart wsims" -
App will reconnect to Supabase
-
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