oof

docs/MIGRATIONS.md

@@ -0,0 +1,51 @@
+# Database Migration Safety Guidelines
+
+## Principles
+
+1. **Additive changes only**: Production migrations should only add new columns, tables, or indexes
+2. **No destructive changes**: Never DROP columns or tables in production migrations
+3. **Two-phase migrations**: For destructive changes, use a two-phase approach:
+   - Phase 1: Add new schema, deploy code to use it
+   - Phase 2: Remove old schema after code is stable
+
+## Migration Process
+
+### Before Migration
+1. Test migration on staging database
+2. Verify application works with new schema
+3. Take database backup
+4. Document rollback procedure
+
+### During Migration
+1. Run migration in dry-run mode first
+2. Apply migration to production
+3. Verify migration completed successfully
+4. Monitor application for errors
+
+### After Migration
+1. Verify all queries work correctly
+2. Monitor performance metrics
+3. Update documentation if needed
+
+## Rollback Procedures
+
+### Emergency Rollback
+1. Stop application deployment
+2. Restore database from backup
+3. Revert to previous application version
+4. Verify application functionality
+
+### Planned Rollback
+1. Deploy previous application version
+2. Run rollback migration
+3. Verify application functionality
+4. Update monitoring dashboards
+
+## Migration Checklist
+
+- [ ] Migration tested on staging
+- [ ] Backup taken before production migration
+- [ ] Rollback procedure documented
+- [ ] Team notified of maintenance window
+- [ ] Monitoring dashboards prepared
+- [ ] Support team on standby