# 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.