46 lines
1.6 KiB
Markdown
46 lines
1.6 KiB
Markdown
|
# Database Migrations and Data Evolution
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
|
||
|
|
Change schemas and data safely while protecting compatibility, correctness, rollout reliability, and recovery options.
|
||
|
|
|
||
|
|
## When to use
|
||
|
|
|
||
|
|
- Adding, removing, or changing database schema
|
||
|
|
- Backfilling or transforming data
|
||
|
|
- Introducing compatibility windows between old and new code
|
||
|
|
- Planning rollout for data-sensitive changes
|
||
|
|
|
||
|
|
## Inputs to gather
|
||
|
|
|
||
|
|
- Current schema, access patterns, and data volume
|
||
|
|
- Migration tooling and deployment model
|
||
|
|
- Compatibility requirements across services, jobs, or clients
|
||
|
|
- Rollback constraints and data recovery options
|
||
|
|
|
||
|
|
## How to work
|
||
|
|
|
||
|
|
- Prefer staged migrations when compatibility matters: expand, backfill, switch reads or writes, then contract.
|
||
|
|
- Minimize lock risk, data loss risk, and long-running migration risk.
|
||
|
|
- Consider how old and new code will coexist during rollout.
|
||
|
|
- Define verification steps for schema state and critical data correctness.
|
||
|
|
- Document irreversible steps and operator actions clearly.
|
||
|
|
|
||
|
|
## Output expectations
|
||
|
|
|
||
|
|
- Safe migration plan or implementation
|
||
|
|
- Compatibility and rollout notes
|
||
|
|
- Verification and rollback considerations
|
||
|
|
|
||
|
|
## Quality checklist
|
||
|
|
|
||
|
|
- The migration is safe for the repository's deployment model.
|
||
|
|
- Data correctness is protected during and after rollout.
|
||
|
|
- Backwards and forwards compatibility are considered when needed.
|
||
|
|
- Irreversible or risky steps are made explicit.
|
||
|
|
|
||
|
|
## Handoff notes
|
||
|
|
|
||
|
|
- Call out sequencing requirements across application code, migrations, and background jobs.
|
||
|
|
- Pair with release/change summary and technical docs when operators or teammates need a clear rollout path.
|