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>
This commit is contained in:
@@ -0,0 +1,736 @@
|
|||||||
|
# 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:
|
||||||
|
```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:<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**
|
||||||
|
|
||||||
|
```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:<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**
|
||||||
|
|
||||||
|
```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:<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**
|
||||||
|
|
||||||
|
```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 <query>"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 <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:
|
||||||
|
|
||||||
|
```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
|
||||||
Reference in New Issue
Block a user