docs: add future schema changes guidance to initialization plan

- Document safe vs breaking changes distinction
- List additive changes handled automatically by initialization
- List breaking changes requiring manual migration
- Provide 6-step migration strategy for breaking changes
- Recommend preferring additive changes for automatic initialization
This commit is contained in:
2026-02-10 16:45:29 -05:00
parent 8689dc0847
commit 5b85f61125
+29 -1
View File
@@ -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**