Migrations

Obsolete

Easier Database Migrations (v2 only)

Migrations support helps you to setup/upgrade the db schema, code first and organized. In a nutshell, you define migrations tasks grouped organized by a 'schema' (no direct relation to a database schema) that will be executed in a certain order. SqlFu also provides an Automatic Migrations feature which will keep track of the schema versions.

To help you to organize better the database structure, all the migrations are associated with a migration schema which is just the name of one or more tasks grouped together. Use the schema name to organize the database in logical units. For example, a database for a blog engine would consist of the Blog schema (config stuff), Users schema and Posts schema. This way, it will be much easier to upgrade only specific tables. Once again, the migration schema has no relation to the database schema, it's just a logical name to organize migration tasks.

A migration consists of one or more tasks. At least it has to have one task, which will run as an install on a new database. As an example, let's say the app is at the version 1.0.2 . If it's a clean install, then the task versioned 1.0.2 will run, else it will try to run all the tasks which upgrade the database. So if it tries to update an existing 1.0.0 version, the migrations run will be 1.0.0 -> 1.0.1 -> 1.02 .

Let's define some tasks

 [Migration("1.0.2",SchemaName = "Users",Priority = 3)]
    public class UserInstallerTask:AbstractMigrationTask
    {
        public UserInstallerTask()
        {
            
        }
        public override void Execute(DbConnection db)
        {
           //do db stuff
        }
    }

There are 2 important things: the MigrationAttribute and the AbstractMigrationTask class. Both are needed in order to define a migration task.

If a [Migration] lacks the NextVersion it's considered to be the 'installer' task. You MUST have one installer task. Also for this case, you can set the Priority property (higher means more important) which will be used by hhe migration manager to execute migrations in the desired order. The Priority property has effect ONLY on the installer task, it's ignored for upgrading tasks.

The AbstractMigrationTask is the base class from which any task should inherit.

[Migration("1.0.0","1.0.1",SchemaName = "Users")]
    public class UsersUpdate101:AbstractMigrationTask
    {
        public override void Execute(DbConnection db)
        {
           //do db stuff
        }
    }

The above task marks a migration from the version 1.0.0 to 1.0.1 for the Users schema.

Running Tasks

At the absolute minimum you need only this, when the app starts

using (var db=SqlFuDao.GetConnection())
{
 DatabaseMigration.ConfigureFor(db).SearchAssemblyOf<UserInstallerTask>().PerformAutomaticMigrations();
}

The Automatic Migrator will install/upgrade all the migration schemas found in the specified assembly. By default, it's assumed that the migrations tasks have a parameterless constructor i.e they don't have dependencies. If you're using a DI Container, you need to wrap it in an implementation of IContainerScope.

DatabaseMigration.ConfigureFor(db)
 .SearchAssemblyOf<UserInstallerTask>()
 .WithResolver([an implementation of IContainerScope])
 .WithLogger(LogHelper.DefaultLogger)
 .PerformAutomaticMigrations();

For details on how to implement IContainerScope see this