Skip to content

Commit 26b19ce

Browse files
sandikodevsandikodev
committed
feat: Add proper database migration structure with Supabase CLI
Migration System Setup: ✅ Supabase CLI installed (pnpm add -D supabase) ✅ Migration folder structure created ✅ Version-controlled migrations ✅ Professional database management Files Created: 1. supabase/config.toml - Project configuration - API, DB, Studio settings - Auth redirect URLs 2. supabase/migrations/20251013000001_initial_schema.sql - All core tables - Students, chat, insights, achievements, sessions - Indexes, RLS, triggers - Complete initial setup 3. supabase/migrations/20251013000002_add_admins.sql - Admin table - Default admin account - Indexes and RLS - Auto-update trigger 4. supabase/.gitignore - Local development files - Temp files exclusion 5. MIGRATION_GUIDE.md - Complete migration documentation - Best practices - CLI commands - Workflow guide Migration Benefits: ✅ Version controlled schema ✅ Reproducible across environments ✅ Team collaboration friendly ✅ Easy rollback capability ✅ CI/CD ready ✅ Professional workflow Running Migrations: Option 1 (Current): Manual via Dashboard - Simple for static site - Copy migration file → SQL Editor → Run Option 2 (Advanced): Supabase CLI - npx supabase db push - Requires CLI auth - Full automation Migration Files: - 20251013000001_initial_schema.sql (Core tables) - 20251013000002_add_admins.sql (Admin system) To Fix 404: Run migration 2 in Supabase SQL Editor: https://supabase.com/dashboard/project/cycacvbiknngaoxrgzci/sql/new Professional upgrade from ad-hoc SQL to proper migrations!
1 parent 53fed20 commit 26b19ce

7 files changed

Lines changed: 675 additions & 0 deletions

File tree

‎MIGRATION_GUIDE.md‎

Lines changed: 374 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,374 @@
1+
# 🔄 Database Migration Guide - Supabase CLI
2+
3+
## Why Migrations?
4+
5+
✅ **Version Control** - Track database changes over time
6+
✅ **Reproducible** - Same schema across dev/staging/prod
7+
✅ **Rollback** - Easy to undo changes
8+
✅ **Team Collaboration** - Share schema changes via Git
9+
✅ **CI/CD Ready** - Automated deployments
10+
11+
---
12+
13+
## 📦 Setup (One-Time)
14+
15+
### Install Supabase CLI
16+
17+
Already installed via:
18+
19+
```bash
20+
pnpm add -D supabase
21+
```
22+
23+
### Project Structure
24+
25+
```
26+
supabase/
27+
├── config.toml # Supabase config
28+
├── migrations/
29+
│ ├── 20251013000001_initial_schema.sql # Initial tables
30+
│ └── 20251013000002_add_admins.sql # Admin table
31+
└── .gitignore
32+
```
33+
34+
---
35+
36+
## 🚀 Running Migrations
37+
38+
### Option 1: Via Supabase Dashboard (Recommended for Now)
39+
40+
**For Remote Database (cycacvbiknngaoxrgzci):**
41+
42+
1. Go to SQL Editor:
43+
44+
```
45+
https://supabase.com/dashboard/project/cycacvbiknngaoxrgzci/sql/new
46+
```
47+
48+
2. Run migrations in order:
49+
50+
**Migration 1 - Initial Schema:**
51+
52+
```bash
53+
# Copy content from:
54+
supabase/migrations/20251013000001_initial_schema.sql
55+
56+
# Paste in SQL Editor → Run ▶️
57+
```
58+
59+
**Migration 2 - Add Admins:**
60+
61+
```bash
62+
# Copy content from:
63+
supabase/migrations/20251013000002_add_admins.sql
64+
65+
# Paste in SQL Editor → Run ▶️
66+
```
67+
68+
3. Verify in Table Editor:
69+
- ✅ students
70+
- ✅ chat_messages
71+
- ✅ student_insights
72+
- ✅ achievements
73+
- ✅ study_sessions
74+
- ✅ admins (with 1 row)
75+
76+
### Option 2: Via Supabase CLI (Advanced)
77+
78+
**Note**: Requires Supabase CLI installed system-wide and authentication
79+
80+
```bash
81+
# Login to Supabase
82+
npx supabase login
83+
84+
# Link to remote project
85+
npx supabase link --project-ref cycacvbiknngaoxrgzci
86+
87+
# Push migrations to remote
88+
npx supabase db push
89+
90+
# Or run specific migration
91+
npx supabase db execute --file supabase/migrations/20251013000001_initial_schema.sql
92+
npx supabase db execute --file supabase/migrations/20251013000002_add_admins.sql
93+
```
94+
95+
---
96+
97+
## 📝 Creating New Migrations
98+
99+
### Naming Convention:
100+
101+
```
102+
YYYYMMDDHHMMSS_description.sql
103+
104+
Examples:
105+
20251013000001_initial_schema.sql
106+
20251013000002_add_admins.sql
107+
20251014120000_add_parent_table.sql
108+
```
109+
110+
### Template:
111+
112+
```sql
113+
-- Migration: [Feature Name]
114+
-- Created: YYYY-MM-DD
115+
-- Description: What this migration does
116+
117+
-- Your SQL here
118+
CREATE TABLE IF NOT EXISTS new_table (
119+
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
120+
...
121+
);
122+
123+
-- Indexes
124+
CREATE INDEX IF NOT EXISTS idx_name ON new_table(column);
125+
126+
-- RLS
127+
ALTER TABLE new_table ENABLE ROW LEVEL SECURITY;
128+
CREATE POLICY "policy_name" ON new_table FOR SELECT USING (true);
129+
```
130+
131+
### Example - Add Parent Table:
132+
133+
Create: `supabase/migrations/20251014120000_add_parents.sql`
134+
135+
```sql
136+
-- Migration: Add Parents Table
137+
-- Created: 2025-10-14
138+
-- Description: Parent accounts for monitoring student progress
139+
140+
CREATE TABLE IF NOT EXISTS parents (
141+
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
142+
email VARCHAR(255) UNIQUE NOT NULL,
143+
name VARCHAR(255) NOT NULL,
144+
phone VARCHAR(20),
145+
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
146+
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
147+
);
148+
149+
CREATE TABLE IF NOT EXISTS student_parents (
150+
student_id UUID REFERENCES students(id) ON DELETE CASCADE,
151+
parent_id UUID REFERENCES parents(id) ON DELETE CASCADE,
152+
relationship VARCHAR(20) CHECK (relationship IN ('father', 'mother', 'guardian')),
153+
PRIMARY KEY (student_id, parent_id)
154+
);
155+
156+
CREATE INDEX idx_student_parents_student ON student_parents(student_id);
157+
CREATE INDEX idx_student_parents_parent ON student_parents(parent_id);
158+
159+
ALTER TABLE parents ENABLE ROW LEVEL SECURITY;
160+
ALTER TABLE student_parents ENABLE ROW LEVEL SECURITY;
161+
162+
CREATE POLICY "Public read parents" ON parents FOR SELECT USING (true);
163+
CREATE POLICY "Public read student_parents" ON student_parents FOR SELECT USING (true);
164+
165+
CREATE TRIGGER update_parents_updated_at BEFORE UPDATE ON parents
166+
FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
167+
```
168+
169+
---
170+
171+
## 🔄 Migration Workflow
172+
173+
### Development Process:
174+
175+
1. **Create Migration File**:
176+
177+
```bash
178+
# Create new file with timestamp
179+
supabase/migrations/20251015100000_your_feature.sql
180+
```
181+
182+
2. **Write SQL**:
183+
- Add tables, columns, indexes
184+
- Update RLS policies
185+
- Insert seed data (if needed)
186+
187+
3. **Test Locally** (optional):
188+
189+
```bash
190+
npx supabase db reset
191+
```
192+
193+
4. **Run on Remote**:
194+
- Copy SQL to Supabase Dashboard
195+
- Or use `npx supabase db push`
196+
197+
5. **Commit to Git**:
198+
```bash
199+
git add supabase/migrations/
200+
git commit -m "migration: Add feature X"
201+
git push
202+
```
203+
204+
---
205+
206+
## 📊 Current Migrations
207+
208+
### Migration 1: Initial Schema
209+
210+
- **File**: `20251013000001_initial_schema.sql`
211+
- **Creates**:
212+
- students
213+
- chat_messages
214+
- student_insights
215+
- achievements
216+
- study_sessions
217+
- **Status**: ⚠️ Needs to be run
218+
219+
### Migration 2: Add Admins
220+
221+
- **File**: `20251013000002_add_admins.sql`
222+
- **Creates**:
223+
- admins table
224+
- Default admin account
225+
- **Status**: ⚠️ Needs to be run (fixes 404 error)
226+
227+
---
228+
229+
## 🎯 Quick Migration Commands
230+
231+
### Run All Pending Migrations:
232+
233+
```bash
234+
# Via Dashboard (current method)
235+
1. Open SQL Editor
236+
2. Run migration 1
237+
3. Run migration 2
238+
4. Verify tables created
239+
240+
# Via CLI (alternative)
241+
npx supabase db push
242+
```
243+
244+
### Check Migration Status:
245+
246+
```bash
247+
npx supabase migration list
248+
```
249+
250+
### Create New Migration:
251+
252+
```bash
253+
# Generate migration file
254+
npx supabase migration new feature_name
255+
256+
# Or manually create:
257+
# supabase/migrations/YYYYMMDDHHMMSS_feature_name.sql
258+
```
259+
260+
### Reset Database (Dangerous!):
261+
262+
```bash
263+
# Local only
264+
npx supabase db reset
265+
266+
# Never run on production!
267+
```
268+
269+
---
270+
271+
## 🔒 Best Practices
272+
273+
### DO:
274+
275+
✅ Use IF NOT EXISTS for idempotency
276+
✅ Add indexes for foreign keys
277+
✅ Enable RLS on all tables
278+
✅ Include descriptive comments
279+
✅ Test migrations on local first
280+
✅ Keep migrations small & focused
281+
✅ Use ON CONFLICT for seed data
282+
283+
### DON'T:
284+
285+
❌ Modify existing migrations
286+
❌ Delete data without backup
287+
❌ Skip RLS policies
288+
❌ Hardcode sensitive data
289+
❌ Run untested SQL on production
290+
291+
---
292+
293+
## 🛠️ For This Project (Static Site)
294+
295+
Since we're using **GitHub Pages** (static site), we use **manual migrations**:
296+
297+
### Current Approach:
298+
299+
1. Create migration files (version controlled)
300+
2. Run SQL manually in Supabase Dashboard
301+
3. Team shares migrations via Git
302+
4. Simple, no CLI dependency
303+
304+
### Why Not Full CLI?
305+
306+
- Static site deployment
307+
- No server-side migrations
308+
- Manual control preferred
309+
- Simpler for small team
310+
311+
### When to Use CLI?
312+
313+
- Local development (optional)
314+
- Multiple environments
315+
- CI/CD pipelines
316+
- Larger teams
317+
318+
---
319+
320+
## 📋 Migration Checklist
321+
322+
### Before Running:
323+
324+
- [ ] Review SQL for errors
325+
- [ ] Check dependencies (foreign keys)
326+
- [ ] Verify table names
327+
- [ ] Test on local (optional)
328+
- [ ] Backup if modifying data
329+
330+
### After Running:
331+
332+
- [ ] Verify tables created
333+
- [ ] Check indexes exist
334+
- [ ] Test RLS policies
335+
- [ ] Verify sample data
336+
- [ ] Update documentation
337+
338+
---
339+
340+
## 🎯 Next Steps
341+
342+
### Immediate:
343+
344+
1. ✅ Run migration 1 (initial schema)
345+
2. ✅ Run migration 2 (add admins)
346+
3. ✅ Verify tables in Supabase
347+
4. ✅ Test admin login
348+
5. ✅ Test student features
349+
350+
### Future Migrations:
351+
352+
- [ ] Add parent accounts
353+
- [ ] Add teacher portal
354+
- [ ] Add study groups
355+
- [ ] Add notifications
356+
- [ ] Add content library
357+
358+
---
359+
360+
## 📚 Learn More
361+
362+
- [Supabase Migrations](https://supabase.com/docs/guides/cli/local-development#database-migrations)
363+
- [Database Migrations Best Practices](https://www.prisma.io/dataguide/types/relational/migration-best-practices)
364+
- [SQL Migration Patterns](https://www.postgresql.org/docs/current/ddl.html)
365+
366+
---
367+
368+
**Current Status**:
369+
370+
- Migrations created ✅
371+
- Need to run on remote ⚠️
372+
- Files committed to Git ✅
373+
374+
**To fix 404 error**: Run migration 2 in Supabase Dashboard! 🚀

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
"prettier-plugin-svelte": "^3.4.0",
6262
"prettier-plugin-tailwindcss": "^0.6.14",
6363
"simple-git-hooks": "^2.13.1",
64+
"supabase": "^2.51.0",
6465
"svelte": "^5.39.5",
6566
"svelte-check": "^4.3.2",
6667
"tailwindcss": "^4.1.13",

0 commit comments

Comments
 (0)