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