Files
ims/docs/superpowers/plans/2026-09-30-supabase-to-local-migration.md
T
adminandClaude Haiku 4.5 26120862a1 docs: Supabase to local postgres migration implementation plan
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>
2026-09-30 09:06:47 +08:00

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 (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:<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)

  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

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:

  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:

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:

  1. Restore .env.production from backup:

    ssh -p 9321 setia@175.136.239.121 "cp /var/www/ims/.env.production.backup.* /var/www/ims/.env.production"
    
  2. Restart app:

    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