docs: Clarify database schema update process in PROJECT_GUIDELINES

- Add explicit note that this is pre-production (no deployments)
- Document two options for updating local databases after schema changes
- Option 1: Recreate database (recommended, loses data)
- Option 2: Manual SQL migration (preserves data)
- Explicitly state: DO NOT create migration files
- Update checklist to include database update step
- Cross-reference from full-stack tasks section

Clarifies the 'no migration needed' philosophy for future developers
This commit is contained in:
2026-02-09 15:19:45 -05:00
parent 255b1c6cf5
commit c2cba82146
+21 -1
View File
@@ -89,6 +89,7 @@ VERIFY → Compile successfully
### When Working on Full-Stack Tasks ### When Working on Full-Stack Tasks
- Backend changes are allowed when explicitly part of the task - Backend changes are allowed when explicitly part of the task
- Still follow all database protocols (atomic changes, validation, etc.) - Still follow all database protocols (atomic changes, validation, etc.)
- **If modifying database schema:** Update local database after schema.sql changes (see Database Operations section)
- Still use Podman for all builds - Still use Podman for all builds
- Still include Bruno tests for API changes - Still include Bruno tests for API changes
@@ -99,7 +100,15 @@ VERIFY → Compile successfully
### Database Operations (Full-Stack Tasks Only) ### Database Operations (Full-Stack Tasks Only)
- ✅ Follow **pgx v5 standards** for all database operations - ✅ Follow **pgx v5 standards** for all database operations
- ✅ Treat schema changes as **ATOMIC** - complete success or complete rejection - ✅ Treat schema changes as **ATOMIC** - complete success or complete rejection
-When schema changes occur: delete database and rebuild with clean Podman cache -**⚠️ CRITICAL: This is a pre-production application (NO production deployments exist)**
- When `database/schema/schema.sql` is updated, local databases must be updated
- **Option 1 (Recommended):** Recreate database with fresh schema:
```bash
podman compose down -v # Delete volumes (WARNING: loses all data)
podman compose up -d # Start fresh with new schema
```
- **Option 2:** Manually apply schema changes to existing database using psql
- **DO NOT create migration files** - no legacy schema support needed
- ✅ Use **pre-change checklist**: read schema → identify columns → plan changes → verify → read back - ✅ Use **pre-change checklist**: read schema → identify columns → plan changes → verify → read back
- ✅ **Post-change validation**: ensure schema.sql, models.go, and queries.sql are in sync - ✅ **Post-change validation**: ensure schema.sql, models.go, and queries.sql are in sync
@@ -297,6 +306,17 @@ git checkout -- internal/handlers/auth.go
- [ ] Immediately verify by reading back modified sections - [ ] Immediately verify by reading back modified sections
- [ ] Confirm ALL expected columns are present - [ ] Confirm ALL expected columns are present
- [ ] Verify schema.sql, models.go, and queries.sql are in sync - [ ] Verify schema.sql, models.go, and queries.sql are in sync
- [ ] **Update local database** (choose ONE):
- [ ] **Option 1 - Recreate database** (recommended, loses data):
```bash
podman compose down -v # Delete all volumes
podman compose up -d # Start with fresh schema
```
- [ ] **Option 2 - Manual SQL migration** (preserves data):
```bash
podman exec bookhoard_db psql -U postgres -d bookhoard -c "YOUR SQL HERE"
```
- [ ] Verify database has new schema (check column types, indexes, etc.)
### After API Changes ### After API Changes
- [ ] Create/update Bruno DSL .bru requests - [ ] Create/update Bruno DSL .bru requests