Home

Welcome to the dotMigrator wiki!

Many applications maintain persistent stored data in some kind of database. To be useful to the application, that data is kept in a certain, (explicit or implicit), structure. As the application evolves, the structure of its stored data needs to evolve with it. dotMigrator is a tool to help manage the data structure changes in an automated way during application development, testing, and release. Changes to the data structure are called migrations and can be maintained in source control along with the application's source code.

In addition to the structures used to hold data, many data stores hold the definitions of executable objects such as views, functions and stored procedures that can be dropped and re-created or replaced without impact to the stored data. dotMigrator can also track these definitions and run "repeatable" scripts to revise these objects when their definitions need to change.

For development and testing, dotMigrator can also run a sequence of scripts or code to populate the application's database with test data. These test data scripts can be

Migrations can be either scripts (such as .SQL scripts) or executable code and are expected to be maintained in source control with the application code that requires the target database.

Each target data store that will be managed with dotMigrator is expected to have an associated journal of migrations that have been applied. This journal is consulted when dotMigrator runs to determine which migrations and repeatable scripts, if any, need to be applied to bring the data structure up to the version matching the application being deployed. By tracking the migrations that have already been applied to a given data store, dotMigrator will also detect and prevent an attempt to deploy an incompatible version.

With inspiration from:

• Flyway
• DbUp
• DSMigrator
• Several other similar tools

SQL Script migrations

Migrations implemented as SQL scripts are assumed to require the application to be offline while they run.

If a SQL migration script fails, dotMigrator will not continue. The database is assumed to be broken and will need to be repaired before dotMigrator will run again. It might be repaired by restoring from a backup, or by manual intervention. If it is corrected by manual intervention, the associated migration journal will need to be updated to reflect that the the migration was either backed-out, or completed. This way, dotMigrator will know what it needs to apply when it is run again.

Code-based migrations

Migrations implemented in executable code are assumed to require the application to be offline while they run.

Sometimes a data migration can be written such that it can run over the course of a long time while the application remains online. dotMigrator is not used to run this type of migration.

Code-based migrations can optionally be marked as "resumable" meaning that if they fail or are interrupted, dotMigrator can restart it, allowing it to recover itself and then complete. The migration must be written carefully to anticipate a potential failure or interruption at any point and be able to continue from where it left off when it restarts.