diff --git a/REFINED_SCHEMA_PLAN.md b/REFINED_SCHEMA_PLAN.md index d610746..e6801b2 100644 --- a/REFINED_SCHEMA_PLAN.md +++ b/REFINED_SCHEMA_PLAN.md @@ -726,10 +726,38 @@ podman compose up -d ## 📚 Documentation Create documentation explaining the automatic schema initialization: -- **docs/contributing/database-schema.md** - How schema initialization works, how to modify schema safely, PostgreSQL version requirements +- **docs/contributing/database-schema.md** - How schema initialization works, how to modify schema safely, PostgreSQL version requirements, future schema changes guidance - **README.md** - Add "Database Initialization" section documenting first-run behavior and PostgreSQL version requirements - **internal/database/schema_test.go** - Unit tests for schema parsing and verification functions +### Future Schema Changes + +This plan handles **initialization** only (ensuring database is ready for first run or existing deployments). For future schema modifications: + +**Safe changes (additive, handled by this plan):** +- ✅ Add new tables: `CREATE TABLE IF NOT EXISTS` - handled automatically +- ✅ Add new columns: `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` - handled automatically +- ✅ Add new indexes: `CREATE INDEX IF NOT EXISTS` - handled automatically +- ✅ Add new functions: `CREATE OR REPLACE FUNCTION` - handled automatically +- ✅ Insert default data: Use `ON CONFLICT DO NOTHING` - handled automatically + +**Breaking changes (require manual migration planning):** +- ⚠️ Drop columns: Requires manual migration script +- ⚠️ Rename tables/columns: Requires coordinated deployment with code changes +- ⚠️ Change column types: Requires data migration and potential downtime +- ⚠️ Modify constraints: Requires careful planning and testing +- ⚠️ Remove functions: Ensure no dependencies exist before removal + +**Migration strategy for breaking changes:** +1. Create dedicated migration script in `database/migrations/` +2. Version the migration (e.g., `001_drop_legacy_column.sql`) +3. Test migration on backup database first +4. Deploy with application code that handles both old and new schema +5. Run migration during maintenance window or use online schema change tools +6. Verify application compatibility after migration + +**Best practice:** Prefer additive changes over breaking changes whenever possible to leverage automatic initialization. + --- **End of Refined Implementation Plan**