Kordant/docs/MIGRATIONS.md

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