Database Migration,
as a requirement diagram.

A requirement diagram for database migration maps every functional and non-functional requirement involved in executing a schema change without taking a production system offline. It captures constraints such as backward compatibility, rollback procedures, data integrity checks, and deployment sequencing, giving every stakeholder a single structured view of what must be true before, during, and after the migration. By formalizing requirements in a visual format, teams can trace each migration step back to a specific business or technical need, reducing the risk of overlooked dependencies that cause outages.

## When to Use This Template

This template is most valuable during the planning phase of any schema change that must preserve service continuity—adding nullable columns, renaming tables through view aliases, splitting or merging columns, or introducing new indexes on high-traffic tables. It is equally useful when coordinating across multiple teams, such as backend developers, database administrators, and SRE engineers, who each own different parts of the migration pipeline. Use it to document expand-contract (parallel-change) patterns, feature-flag requirements, and monitoring thresholds that define a successful cutover, ensuring nothing is treated as implicit.

## Common Mistakes to Avoid

One of the most frequent errors is treating zero-downtime as a single requirement rather than a collection of interdependent constraints—omitting items like connection-pool draining time or replication lag tolerance can invalidate the entire plan. Another pitfall is failing to link each requirement to a verification method; without acceptance criteria, teams cannot confirm the migration succeeded before decommissioning the old schema. Avoid listing only technical requirements while ignoring operational ones such as alerting rules, on-call escalation paths, and rollback time objectives. Finally, do not finalize the diagram without reviewing it against your actual deployment pipeline: requirements that cannot be enforced by your CI/CD tooling or migration framework (e.g., Flyway, Liquibase, Alembic) should be flagged as risks rather than accepted silently.