Introduction to Fluent Migrator

03 May 2021 at 10:00 by ParTech Media - Post a comment

A key aspect of any project is managing database migrations. While working on developing an application it is critical for team members to work in tandem especially when it comes to handling databases.

Databases are manually managed while developing an application. For example, developers often create SQL scripts for updating tables and stored procedures. They then have to manage them in a certain order so that they be executed in the upper environments smoothly.

In short, managing databases is not easy at all. This is where Fluent Migrator comes in handy. It is a tool that helps in solving all the above problems and more. Let us begin the post by understanding what is Fluent Migrator and how it works.

Table of contents

  • What is a Fluent Migrator?
  • How does a Fluent Migrator work?
  • Useful Features and Techniques in Fluent Migrator
  • Conclusion

What is a Fluent Migrator?

Fluent Migrator is a framework used for database migration in .NET. It involves writing a series of classes that can create and modify the database and data. Each class in Fluent Migrator depicts a single migration i.e. migration from an empty database to a database filled with some information.

In order to use Fluent Migrator, schema changes are written in classes that have two methods-

  • Down( )
  • Up( )

As the name suggests, the Up( ) method is used to upgrade the database while the Down( ) method is used to downgrade it.

While using Fluent Migrator, you can also call out the version to which you want to migrate to. When you do that, all the necessary migrations will run in such a way that your database is brought up to the version you want it to migrate to.

How does Fluent Migrator work?

The simple C# classes which are inherited from the “Migration” base class are called Migration classes. The version number of migration is put as a unique identifier in the Migration attribute in each class. When multiple developers are creating migrations, one can use the format YYYYMMDDHHMM to avoid any clashes in migrations of different developers. Alternatively, one can use an incremental integer in its place.

After assigning a unique identifier in the migration attribute in each class, the Up( ) and Down( ) methods are implemented. For example, a new table can be created in the database by using the Up( ) method while a table can be removed from the database using the Down( ) method.

Migrate.exe is the Migration runner tool that comes with the Fluent Migrator. It is used to execute the methods of migration classes like Up( ) and Down( ) in the correct sequence. To automate the migration process, integration of Migrate.exe can be done in any Continuous Integration (CI) tool such as Team-City, Azure DevOps Server, Jenkins etc. A “Version” table is maintained by the Fluent Migrator to keep track of the migration version which is executed in the database.

Useful Features and Techniques in FluentMigrator

Dealing with multiple database types

From the same migration project, you can target multiple database types in Fluent Migrator. Remember this - every project in FluentMigrator is database agnostic. However, there are always situations when you need to execute only a handful of migrations in a project against a database. In such cases, you can use the IfDatabase expression in FluentMigrator.

Imagine you have a migration that runs a script file to create a view. Here is how it will look like -

Now imagine a scenario when you want to create few views in the SQLServer database and few views in the Oracle database. You also want both these tasks to be carried out in the same migration and have them share the same migration number in both databases. This can be easily handled by first creating the scripts for both databases and then specifying which database needs to be executed:

Filter migrations run based on Tags

There was a time when multiple databases had the same schema. But this has changed over the years as you can see differences being introduced in them. As a result, a vast majority of the migrations present in a single assembly can be executed against all the databases. However, you also have to filter select migrations to run against the country-specific and environment-specific databases.

In order to accomplish this in Fluent Migrator, you are allowed to tag migrations and then filter them by passing tags into the runner. Once the migrations are filtered, only those migrations will be executed which have no tags or have all the tags that were passed into the runner.


Using Fluent Migrator you can easily upgrade and downgrade the databases and also automate the database migration process by integrating it with any CI. It is a really handy tool to possess since database management is not only a critical component of any development project, it is also a challenging one.