Migration Dependencies
Overview
Migration dependencies are a powerful feature in Curiosus.Migrations that allow you to explicitly define relationships between migrations. Rather than relying solely on version numbers to determine execution order, dependencies give you precise control over which migrations must be applied before others.
This feature is essential for managing complex migration scenarios, particularly in large applications with multiple development teams or when migrations affect related database objects but are developed independently.
When to Use Dependencies
Dependencies are especially valuable in these scenarios:
- Cross-Module Migrations: When migrations in different modules or components need to be coordinated
- Logical Grouping: When related migrations should be applied together despite having non-sequential versions
- Complex Database Objects: When certain database objects must exist before others can be created
- Team Collaboration: When multiple teams are contributing migrations that may have interdependencies
- Hotfixes: When a critical fix needs to build upon existing migrations but use a special version number
- Complex migration: When running firstly short running migration (like add column), then running long running migration to fill it (like update set for million of rows), and lastly running short running migration to make column nullable
How Dependencies Work
When you specify dependencies for a migration:
- Right before applying the migration, the engine verifies that all dependencies are in the journal: applied by an earlier run or earlier in this run
- If any dependency hasn't been applied, the run fails with
MigrationErrorCode.MigratingErrorat this migration: the migrations applied before it stay applied, the next ones are not applied
Dependencies work alongside the standard version-based ordering. The engine still applies migrations in version order, but adds the additional constraint that all dependencies must be satisfied before a migration runs. Dependencies don't reorder migrations, so a dependency must have a lower version than the migration that declares it: a dependency on a higher version always fails.
Dependencies are not validated when the engine is built: a dependency on a version that doesn't exist is reported only when the migration is about to run.
A migration skipped by the migration policy is not applied, so a migration depending on it fails the run. This is what keeps the "short, long, short" sequence of scenario 6 safe: with a startup policy that allows short-running migrations only, the run fails at the third migration until the long-running one has been applied.
Implementing Dependencies in Script Migrations
For SQL script migrations, specify dependencies using the -- CURIOSUS: DEPENDENCIES directive (usually at the beginning of your file):
-- Version: 3.0
-- Migration to add user permissions
--CURIOSUS:Dependencies=1.0, 2.0
CREATE TABLE user_permissions (
id SERIAL PRIMARY KEY,
user_id INT NOT NULL REFERENCES users(id),
permission_name VARCHAR(100) NOT NULL,
granted_at TIMESTAMP NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_user_permissions_user_id ON user_permissions(user_id);
In this example, the migration declares that versions 1.0 and 2.0 must be applied before it can run. This might be because those migrations create the "users" table and add necessary columns that this migration references.
The DEPENDENCIES directive should:
- Be a line of its own, anywhere in the script; spaces around
:and=are optional and the option name is case-insensitive - List dependencies as comma-separated version numbers
- Use the same version format as your migration versioning scheme
Don't put other text on the directive line: everything after = is read as the list of versions.
Examples:
-- Simple versions
--CURIOSUS:Dependencies=1.0, 2.0
-- Date-based versions
-- CURIOSUS: DEPENDENCIES = 20230101, 20230102.1
-- Versions with underscores
-- CURIOSUS: DEPENDENCIES = 2023_01_01, 2023_01_02
Implementing Dependencies in Code Migrations
For code migrations, set the Dependencies property in your migration class:
public class AddUserSettingsMigration : CodeMigration
{
public override MigrationVersion Version => new(3, 0);
public override string? Comment => "Add user settings table";
// Set dependencies in the constructor
public AddUserSettingsMigration()
{
// This migration depends on versions 1.0 and 2.0
Dependencies = new List<MigrationVersion>()
{
new(1, 0), // Users table migration
new(2, 0) // User profile migration
};
}
public override async Task UpgradeAsync(DbTransaction? transaction = null,
CancellationToken cancellationToken = default)
{
var sql = @"
CREATE TABLE user_settings (
user_id INT NOT NULL REFERENCES users(id),
setting_key VARCHAR(100) NOT NULL,
setting_value TEXT,
PRIMARY KEY (user_id, setting_key)
);";
await MigrationConnection.ExecuteNonQuerySqlAsync(
sql, null, cancellationToken);
}
}
This approach provides type safety and IntelliSense support for specifying dependencies.
Troubleshooting
Missing Dependency Errors
If you receive a MigrationErrorCode.MigratingError with a message about missing dependencies:
- Verify that all dependent migrations exist in your migration source (directory, assembly, etc.)
- Check that dependent migration versions are correctly specified and lower than the version of the migration
- Check whether the dependency was skipped by the migration policy (
result.SkippedByPolicyMigrations) - Check the migration journal table to see the current state of applied migrations
Circular Dependencies
Circular dependencies (A depends on B, and B depends on A) are not detected separately: one of the migrations of a cycle depends on a higher version, so it fails when it is about to run. Redesign your migrations to eliminate the circular reference, merge them if they're tightly coupled, or create an intermediate migration that both can depend on.
Example: Migration Dependency Chain
Here's a complete example showing a chain of dependent migrations:
-
First, create the users table:
-- Version: 1.0-- users.sqlCREATE TABLE users (id SERIAL PRIMARY KEY,username VARCHAR(100) NOT NULL UNIQUE,created_at TIMESTAMP NOT NULL DEFAULT NOW()); -
Next, add authentication fields:
-- Version: 2.0-- authentication.sql--CURIOSUS:Dependencies=1.0ALTER TABLE usersADD COLUMN password_hash VARCHAR(255) NOT NULL DEFAULT '',ADD COLUMN email VARCHAR(255) UNIQUE,ADD COLUMN last_login TIMESTAMP; -
Then add permissions:
-- Version: 3.0-- permissions.sql--CURIOSUS:Dependencies=2.0CREATE TABLE permissions (id SERIAL PRIMARY KEY,name VARCHAR(100) NOT NULL UNIQUE,description TEXT);CREATE TABLE user_permissions (user_id INT NOT NULL REFERENCES users(id),permission_id INT NOT NULL REFERENCES permissions(id),granted_at TIMESTAMP NOT NULL DEFAULT NOW(),PRIMARY KEY (user_id, permission_id)); -
Finally, seed initial permissions:
public class SeedPermissionsMigration : CodeMigration{public override MigrationVersion Version => new(3, 1);public override string? Comment => "Seed initial permissions";public SeedPermissionsMigration(){Dependencies = new List<MigrationVersion>() { new(3, 0) };}public override async Task UpgradeAsync(DbTransaction? transaction = null,CancellationToken cancellationToken = default){var defaultPermissions = new[] {("user.read", "Can view user information"),("user.create", "Can create new users"),("user.update", "Can modify user information"),("user.delete", "Can delete users")};foreach (var (name, description) in defaultPermissions){await MigrationConnection.ExecuteNonQuerySqlAsync("INSERT INTO permissions (name, description) VALUES (@name, @description)",new Dictionary<string, object?> {{ "@name", name },{ "@description", description }},cancellationToken);}}}
This chain of migrations ensures that:
- The users table exists before adding authentication fields
- Authentication fields exist before creating permission tables
- Permission tables exist before seeding permissions data