Hop til hovedindhold

Data Model Changes and Database Migrations

Document status35 - Reviewed

Maintaining a reliable and consistent data model is essential for the stability of any production system. Whenever we modify the model — whether by adding new entities, changing relationships, or adjusting existing fields — those changes must be safely and predictably reflected in the database.

Database migrations are the mechanism that ensures our code and database schema evolve together. Handled correctly, they make deployment smooth and predictable. Handled carelessly, they can lead to data loss, broken environments, and difficult rollbacks. This page outlines our best practices for handling data model changes and migrations — when to create them, how to review them, and what to consider before merging changes into production.

1. Always Create a Migration​

Whenever you make changes to the data model, you must always create a corresponding migration.

If the generated migration doesn’t look like what you expected, don’t just accept it - investigate why.  

Unexpected changes often point to differences between your intentions and how Entity Framework interprets the model.

Typical reasons include:

  • Missing or incorrect relationships or navigation properties  
  • Unintended renaming of columns or tables  
  • Implicit type changes (e.g., int → long, nullable → not nullable)

2. Migrations Are Not “Auto-generated Code”​

Migrations are not disposable scaffolding. The generated code represents Entity Framework’s understanding of how your model should look in the database. If that understanding doesn’t match your intention, something is wrong - either in your model definitions, entity configurations, or relationships.

Note:
It’s not enough to manually edit or delete lines in the migration file. Fix the root cause in the model so Entity Framework generates the correct migration automatically.

Think of migrations as a diagnostic tool - they reflect whether your data model is accurately and consistently defined.

3. Consider the Impact in Production​

Any change to the data model has real consequences once deployed to production.

Before creating a pull-request, consider:

  • Are we at risk of losing important data?
  • Does existing data need to be moved or transformed before a column or table is dropped?
  • Do we need to populate default values when adding new non-nullable columns?
  • Should seed data or enums be updated to match the new constraints?
  • Is this a multi-step migration (e.g., add new column → copy data → remove old column)?
  • Are there performance implications, such as adding or removing indexes on large tables?  
  • Other?

4. Review Migrations as Code​

Migrations must be reviewed with the same level of attention as application code.

During pull requests, reviewers should check:

  • Are the schema changes intentional and clearly understood?
  • Are there unexpected drops or renames that could lead to data loss?
  • Is there appropriate data handling for existing records?
  • Are migration and model files consistent with each other?

5. Ask for Help​

If you are uncertain about a migration, ask the project architects before merging. It’s much cheaper to discuss a change early than to recover from data loss in production.