Entity Framework Migrations Tool Basics

Introduction

Entity Framework Migrations is used for changing the database design with the code-first approach. The code-first approach enables a developer to first design the model by writing the POCO classes and then to create the database from the model. The problem comes with the desire to upgrade the model. With the model upgrade the database has to be altered as well to reflect the changed model.

Migrations tool deals with this problem by keeping track of all the changes to the model. The initial model design image is created upon the developer's request. After modifying the model, the developer can request the creation of the differential migration image. The database can then be automatically altered to conform to any of the stored migration images.

Migrations is only used to automatically alter the database. The model has to be altered by hand or by using some other method or tool.

The problem definition

The developer has created the model and the database using the code first approach. During the development phase the need arose to alter the model. The developer has then altered the model and started the application. The application failed with the following error:

The model backing the 'CustomDbContext' context has changed since the database was created. Consider using Code First Migrations to update the database (http://go.microsoft.com/fwlink/?LinkId=238269).

Enabling Migrations and creating initial model image

It is assumed the solution has an implemented class deriving from DbContext and implemented POCO classes describing a desired model. The first step is to set up the Migrations tool in the Visual Studio:

1. In Solution Explorer find the project containing the class overriding the DbContext class and set it as the default project 
2. Start the Package Manager Console and enter "Enable-Migrations" in the prompt:

PM> Enable-Migrations

This creates the Migrations folder in the selected project. This folder contains the following files:

• The initial model image in the "InitialCreate" file
• The Configuration file used to define the desired context behaviour and seeding
• All the differential images, which contain the information how to migrate from the previous migration to the current one and back

Adding Migrations

When the initial model image is created, the developer is free to change the model. When the model is changed to the desired specification, it is necessary to add another migration. This is done by calling the "Add-Migration" command in the Package Manager Console:

PM> Add-Migration MigrationName

The result is the added differential migration in Migrations directory named "MigrationName". It contains two methods, Up() and Down(). Each instructs the Migrations tool how to change the database to the current migration or how to change it back to the previous one. This enables the developer to freely jump between migrations and use the desired one.
Reflecting the model to the database

When the new migration is created, the database can be automatically modified. This is done using the "Update-Database" command in the Package Manager Console:

PM> Update-Database

After the successful call the Database is updated to the last migration.

Migrating to the specific version

The database can be updated to any available migration, including downgrading to some previous migration. This can be accomplished by setting the "TargetMigration" property:

PM> Update-Database –TargetMigration:"MigrationName"

To revert all the changes and go back to the initial database design, use the following command:

PM> Update-Database –TargetMigration:$InitialDatabase

It is important to note that the model has to be altered by hand to conform with the database design after the database migration. The database design and the model design must be the same.

Getting a SQL script

Migrations folder can be shared between the developers using TFS. They can easily modify their databases using the previously described techniques. The problem is when the need arises to alter the deployment database. In that case the SQL script can be generated, which can be run on the deployment database to alter its design.

PM> Update-Database -Script -SourceMigration:$InitialDatabase 
    -TargetMigration:"MigrationName"

If the TargetMigration is not specified, the latest migration is used as the TargetMigration. The result is the SQL document which can be stored, moved and executed on a target database.

Conclusion

Entity Framework Migrations tool can be used to automatically alter the database to conform to the model changes. It is easily installed and used. When the model is changed by hand or using a tool, the database can be easily changed with only two calls to the tool.

Sources and additional reading

1. EF 4.3 Code-Based Migrations Walkthrough
2. Entity Framework Code First Migrations