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:
+29
-1
@@ -726,10 +726,38 @@ podman compose up -d
|
|||||||
## 📚 Documentation
|
## 📚 Documentation
|
||||||
|
|
||||||
Create documentation explaining the automatic schema initialization:
|
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
|
- **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
|
- **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**
|
**End of Refined Implementation Plan**
|
||||||
|
|||||||
Reference in New Issue
Block a user