Record migration dependencies in history

- store declared dependencies as diagnostic migration metadata
- preserve dependency order and optional-scope markers
- prevent dependent migrations from bypassing migration plans
- optimize dependency descriptors with readonly value semantics
- update migration tests and documentation

Author: ivanvoyager

README.md

@@ -143,7 +143,7 @@ Migrations are applied in the order in which they are registered within each sco
 
 Dependencies may reference required scopes or optional scopes. An optional-scope dependency is ignored only when the scope is neither registered in the plan nor present in migration history. This prevents migrations from ignoring schema changes left by a module that was previously installed but is not currently loaded.
 
-Applied migrations are recorded in the `__nuext_migrations` table with a global history identifier, scope-local sequence, application time, and optional version information. This preserves the complete migration chronology while allowing the application core and independently installed modules to maintain separate migration chains.
+Applied migrations are recorded in the `__nuext_migrations` table with a global history identifier, scope-local sequence, declared dependencies, application time, and optional version information. This preserves the complete migration chronology while allowing the application core and independently installed modules to maintain separate migration chains.
 
 When a connection factory is used, the complete migration plan is executed within a synchronized transaction and is rolled back if any migration fails. A plan can also run within an existing `SQLiteDbContext`, allowing migrations and application operations to share the same caller-owned transaction.
 

src/System/Data/SQLite/SQLiteDbMigrationDependency.cs

@@ -3,7 +3,7 @@
 /// <summary>
 /// Represents a dependency on a migration from another migration scope.
 /// </summary>
-public sealed record SQLiteDbMigrationDependency
+public readonly record struct SQLiteDbMigrationDependency
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="SQLiteDbMigrationDependency"/> class.

src/System/Data/SQLite/SQLiteDbMigrationExtensions.cs

@@ -54,16 +54,21 @@ public static void MigrateScope(this IEnumerable<SQLiteDbMigration> migrations,
     /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
     /// <exception cref="ArgumentNullException"><paramref name="migrations"/> or <paramref name="createConnection"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentException"><paramref name="scope"/> is <see langword="null"/>, empty, or consists only of white-space characters.</exception>
+    /// <exception cref="DbMigrationException">A migration declares dependencies and must be executed through <see cref="SQLiteDbMigrationPlan"/>, or the migration configuration or applied history is invalid.</exception>
     public static void MigrateScope(this IEnumerable<SQLiteDbMigration> migrations, Func<SQLiteDbConnection> createConnection, string scope, string? version, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(migrations);
         ArgumentNullException.ThrowIfNull(createConnection);
         ArgumentException.ThrowIfNullOrWhiteSpace(scope);
         cancellationToken.ThrowIfCancellationRequested();
 
+        SQLiteDbMigration[] migrationArray = [.. migrations];
+
+        ValidateIndependentMigrations(migrationArray);
+
         var executor = new SQLiteMigrationExecutor(createConnection);
         var history = new SQLiteMigrationHistory(scope);
-        var migrator = new DbMigrator<SQLiteDbMigrationContext>(executor, history, migrations, version);
+        var migrator = new DbMigrator<SQLiteDbMigrationContext>(executor, history, migrationArray, version);
         migrator.Migrate(cancellationToken);
     }
 
@@ -128,16 +133,33 @@ public static void MigrateScope(this IEnumerable<SQLiteDbMigration> migrations,
     /// <remarks>
     /// The caller owns the database context and is responsible for committing or rolling back its transaction.
     /// </remarks>
+    /// <exception cref="DbMigrationException">A migration declares dependencies and must be executed through <see cref="SQLiteDbMigrationPlan"/>, or the migration configuration or applied history is invalid.</exception>
     public static void MigrateScope(this IEnumerable<SQLiteDbMigration> migrations, SQLiteDbContext dbContext, string scope, string? version, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(migrations);
         ArgumentNullException.ThrowIfNull(dbContext);
         ArgumentException.ThrowIfNullOrWhiteSpace(scope);
         cancellationToken.ThrowIfCancellationRequested();
 
+        SQLiteDbMigration[] migrationArray = [.. migrations];
+
+        ValidateIndependentMigrations(migrationArray);
+
         var executor = new SQLiteDbContextMigrationExecutor(dbContext);
         var history = new SQLiteMigrationHistory(scope);
-        var migrator = new DbMigrator<SQLiteDbMigrationContext>(executor, history, migrations, version);
+        var migrator = new DbMigrator<SQLiteDbMigrationContext>(executor, history, migrationArray, version);
         migrator.Migrate(cancellationToken);
     }
+
+    private static void ValidateIndependentMigrations(SQLiteDbMigration[] migrations)
+    {
+        for (var i = 0; i < migrations.Length; i++)
+        {
+            var migration = migrations[i];
+            if (migration is { Dependencies.Count: > 0 })
+            {
+                throw new DbMigrationException($"Migration '{migration.Id}' declares dependencies and must be executed through '{nameof(SQLiteDbMigrationPlan)}'.");
+            }
+        }
+    }
 }

src/System/Data/SQLite/SQLiteDbMigrationPlan.cs

@@ -178,12 +178,38 @@ private void ApplyMigration(SQLiteDbMigrationContext context, int scopeIndex, Sp
 
         var appliedMigration = new AppliedDbMigration(migrationIndex + 1, migration.Id, DateTimeOffset.UtcNow, scope.Version);
 
-        scope.History.Add(context, appliedMigration);
+        scope.History.Add(context, appliedMigration, FormatDependencies(migration.Dependencies));
         history.Add(scope.Name, appliedMigration);
 
         nextMigrationIndexes[scopeIndex]++;
     }
 
+    private static string? FormatDependencies(IReadOnlyList<SQLiteDbMigrationDependency> dependencies)
+    {
+        if (dependencies.Count == 0)
+        {
+            return null;
+        }
+
+        var result = new ValueStringBuilder(stackalloc char[SQLiteDbConnection.StackallocCharBufferSizeLimit]);
+        string delimiter = string.Empty;
+        for (var i = 0; i < dependencies.Count; i++)
+        {
+            result.Append(delimiter);
+            delimiter = "; ";
+
+            var dependency = dependencies[i];
+            result.Append(dependency.Scope);
+            result.Append('/');
+            result.Append(dependency.MigrationId);
+            if (dependency.OptionalScope)
+            {
+                result.Append('?');
+            }
+        }
+        return result.ToString();
+    }
+
     private bool AreDependenciesApplied(SQLiteDbMigration migration, SQLiteMigrationHistorySnapshot history)
     {
         var dependencies = migration.Dependencies;
@@ -348,14 +374,17 @@ private static void ValidateDependencies(string scope, SQLiteDbMigration migrati
 
         for (var i = 0; i < dependencies.Count; i++)
         {
-            var dependency = dependencies[i] ?? throw new DbMigrationException($"Dependency at index {i} of migration '{scope}/{migration.Id}' is null.");
+            var dependency = dependencies[i];
 
+            if (string.IsNullOrWhiteSpace(dependency.Scope) || string.IsNullOrWhiteSpace(dependency.MigrationId))
+            {
+                throw new DbMigrationException($"Dependency at index {i} of migration '{scope}/{migration.Id}' is invalid.");
+            }
             if (StringComparer.Ordinal.Equals(scope, dependency.Scope) &&
                 StringComparer.Ordinal.Equals(migration.Id, dependency.MigrationId))
             {
                 throw new DbMigrationException($"Migration '{scope}/{migration.Id}' cannot depend on itself.");
             }
-
             if (!dependencyKeys.Add((dependency.Scope, dependency.MigrationId)))
             {
                 throw new DbMigrationException($"Duplicate dependency '{dependency.Scope}/{dependency.MigrationId}' in migration '{scope}/{migration.Id}'.");

src/System/Data/SQLite/SQLiteMigrationHistory.cs

@@ -12,6 +12,7 @@ internal sealed class SQLiteMigrationHistory : IDbMigrationHistory<SQLiteDbMigra
     scope TEXT NOT NULL CHECK(scope <> ''),
     sequence INTEGER NOT NULL CHECK(sequence > 0),
     migration_id TEXT NOT NULL CHECK(migration_id <> ''),
+    dependencies TEXT,
     version TEXT,
     applied_at INTEGER NOT NULL,
     UNIQUE(scope, sequence),
@@ -31,13 +32,15 @@ migration_id TEXT NOT NULL CHECK(migration_id <> ''),
     scope,
     sequence,
     migration_id,
+    dependencies,
     version,
     applied_at
 )
 VALUES (
     @scope,
     @sequence,
     @migration_id,
+    @dependencies,
     @version,
     @applied_at
 );
@@ -74,13 +77,15 @@ internal SQLiteMigrationHistory(string scope)
         _scope = scope;
     }
 
+    /// <inheritdoc/>
     public void EnsureCreated(SQLiteDbMigrationContext context)
     {
         ArgumentNullException.ThrowIfNull(context);
 
         context.Connection.ExecuteNonQuery(CreateMigrationHistoryTableCommand, cancellationToken: context.CancellationToken);
     }
 
+    /// <inheritdoc/>
     public IReadOnlyList<AppliedDbMigration> GetAppliedMigrations(SQLiteDbMigrationContext context)
     {
         ArgumentNullException.ThrowIfNull(context);
@@ -111,7 +116,13 @@ static void Read(SQLiteDataReader reader, SQLiteMigrationHistorySnapshot history
         }
     }
 
+    /// <inheritdoc/>
     public void Add(SQLiteDbMigrationContext context, AppliedDbMigration migration)
+    {
+        Add(context, migration, null);
+    }
+
+    internal void Add(SQLiteDbMigrationContext context, AppliedDbMigration migration, string? dependencies)
     {
         ArgumentNullException.ThrowIfNull(context);
         ArgumentNullException.ThrowIfNull(migration);
@@ -120,6 +131,7 @@ public void Add(SQLiteDbMigrationContext context, AppliedDbMigration migration)
             DbType.String.CreateInputParam("@scope", _scope),
             DbType.Int32.CreateInputParam("@sequence", migration.Sequence),
             DbType.String.CreateInputParam("@migration_id", migration.Id),
+            DbType.String.CreateInputParam("@dependencies", dependencies),
             DbType.String.CreateInputParam("@version", migration.Version),
             DbType.Int64.CreateInputParam("@applied_at", migration.AppliedAt.ToUnixTimeMilliseconds()));
     }

tests/SQLiteDbMigrationTests.cs

@@ -1657,6 +1657,92 @@ public void MigrationPlan_ScopeVersions_RecordsConfiguredVersions()
         Assert.AreEqual("1.5.0", GetAppliedMigrationVersion(connection, 1, "module.video"));
     }
 
+    [TestMethod]
+    public void MigrationPlan_Dependencies_RecordsDiagnosticInformation()
+    {
+        var coreMigration = new DelegateMigration("0001_Core", static _ => { });
+
+        var videoMigration = new DelegateMigration(
+            "0001_Video",
+            static _ => { },
+            [
+                new SQLiteDbMigrationDependency("core", "0001_Core"),
+                new SQLiteDbMigrationDependency("module.storage", "0002_Storage", optionalScope: true)
+            ]);
+
+        var plan = new SQLiteDbMigrationPlan()
+            .AddScope("core", [coreMigration])
+            .AddScope("module.video", [videoMigration]);
+
+        plan.Migrate(CreateConnection, CancellationToken.None);
+
+        using var connection = CreateConnection();
+        Assert.IsNull(GetAppliedMigrationDependencies(connection, 1, "core"));
+        Assert.AreEqual("core/0001_Core; module.storage/0002_Storage?", GetAppliedMigrationDependencies(connection, 1, "module.video"));
+    }
+
+    [TestMethod]
+    public void Migrate_RecordsNullDependencies()
+    {
+        var migration = new DelegateMigration("0001_CreateSchema", static _ => { });
+        SQLiteDbMigration[] migrations =
+        [
+            migration
+        ];
+
+        migrations.Migrate(CreateConnection, CancellationToken.None);
+
+        using var connection = CreateConnection();
+        Assert.IsNull(GetAppliedMigrationDependencies(connection, 1));
+    }
+
+    [TestMethod]
+    public void MigrationPlan_Dependencies_PreservesConfiguredOrder()
+    {
+        var migration1 = new DelegateMigration("0001_Core", static _ => { });
+        var migration2 = new DelegateMigration("0001_Storage", static _ => { });
+        var migration3 = new DelegateMigration(
+            "0001_Video",
+            static _ => { },
+            [
+                new SQLiteDbMigrationDependency("module.storage", "0001_Storage"),
+                new SQLiteDbMigrationDependency("core", "0001_Core")
+            ]);
+
+        var plan = new SQLiteDbMigrationPlan()
+            .AddScope("core", [migration1])
+            .AddScope("module.storage", [migration2])
+            .AddScope("module.video", [migration3]);
+
+        plan.Migrate(CreateConnection, CancellationToken.None);
+
+        using var connection = CreateConnection();
+        Assert.AreEqual("module.storage/0001_Storage; core/0001_Core", GetAppliedMigrationDependencies(connection, 1, "module.video"));
+    }
+
+    [TestMethod]
+    public void MigrateScope_MigrationWithDependencies_ThrowsDbMigrationException()
+    {
+        var migration = new DelegateMigration(
+            "0001_Video",
+            static _ => { },
+            [
+                new SQLiteDbMigrationDependency("core", "0001_Core")
+            ]);
+        SQLiteDbMigration[] migrations =
+        [
+            migration
+        ];
+
+        Assert.ThrowsExactly<DbMigrationException>(() =>
+            migrations.MigrateScope(CreateConnection, "module.video", CancellationToken.None));
+
+        Assert.AreEqual(0, migration.ExecutionCount);
+
+        using var connection = CreateConnection();
+        Assert.IsFalse(connection.TableExists("__nuext_migrations", CancellationToken.None));
+    }
+
     private SQLiteDbConnection CreateConnection()
     {
         return new SQLiteDbConnection(_connectionString);
@@ -1712,6 +1798,7 @@ CREATE TABLE __nuext_migrations (
                 scope TEXT NOT NULL CHECK(scope <> ''),
                 sequence INTEGER NOT NULL CHECK(sequence > 0),
                 migration_id TEXT NOT NULL CHECK(migration_id <> ''),
+                dependencies TEXT,
                 version TEXT,
                 applied_at INTEGER NOT NULL,
                 UNIQUE(scope, sequence),
@@ -1748,6 +1835,19 @@ FROM __nuext_migrations
         return Convert.ToString(result)!;
     }
 
+    private static string? GetAppliedMigrationDependencies(SQLiteDbConnection connection, int sequence, string scope = DefaultScope)
+    {
+        object? result = connection.ExecuteScalar(
+            """
+            SELECT dependencies
+            FROM __nuext_migrations
+            WHERE scope = @scope AND sequence = @sequence;
+            """,
+            DbType.String.CreateInputParam("@scope", scope),
+            DbType.Int32.CreateInputParam("@sequence", sequence));
+        return result is null or DBNull ? null : Convert.ToString(result);
+    }
+
     private static string? GetAppliedMigrationVersion(SQLiteDbConnection connection, int sequence, string scope = DefaultScope)
     {
         object? result = connection.ExecuteScalar(