Allow migrations within existing SQLite transactions

- add migration executor for an existing SQLiteDbContext
- add migration overloads accepting an active database context
- preserve caller ownership of transaction commit and rollback
- allow migrations and application operations to share one transaction

Author: ivanvoyager

src/System/Data/SQLite/SQLiteDbContextMigrationExecutor.cs

@@ -0,0 +1,28 @@
+namespace System.Data.SQLite;
+
+/// <summary>
+/// Executes SQLite database migrations within an existing database context.
+/// </summary>
+internal sealed class SQLiteDbContextMigrationExecutor : IDbMigrationExecutor<SQLiteDbMigrationContext>
+{
+    private readonly SQLiteDbContext _dbContext;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SQLiteDbContextMigrationExecutor"/> class.
+    /// </summary>
+    /// <param name="dbContext">The existing SQLite database context.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="dbContext"/> is <see langword="null"/>.</exception>
+    public SQLiteDbContextMigrationExecutor(SQLiteDbContext dbContext)
+    {
+        _dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext));
+    }
+
+    /// <inheritdoc/>
+    public void Execute(Action<SQLiteDbMigrationContext> operation, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(operation);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        operation(new SQLiteDbMigrationContext(_dbContext.Connection, cancellationToken));
+    }
+}

src/System/Data/SQLite/SQLiteDbMigrationExtensions.cs

@@ -36,4 +36,42 @@ public static void Migrate(this IEnumerable<SQLiteDbMigration> migrations, Func<
         var migrator = new DbMigrator<SQLiteDbMigrationContext>(executor, history, migrations, version);
         migrator.Migrate(cancellationToken);
     }
+
+    /// <summary>
+    /// Applies all pending migrations using an existing SQLite database context.
+    /// </summary>
+    /// <param name="migrations">The migrations in the order in which they must be applied.</param>
+    /// <param name="dbContext">The existing SQLite database context.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="migrations"/> or <paramref name="dbContext"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// The caller owns the database context and is responsible for committing or rolling back its transaction.
+    /// </remarks>
+    public static void Migrate(this IEnumerable<SQLiteDbMigration> migrations, SQLiteDbContext dbContext, CancellationToken cancellationToken = default)
+    {
+        Migrate(migrations, dbContext, null, cancellationToken);
+    }
+
+    /// <summary>
+    /// Applies all pending migrations using an existing SQLite database context.
+    /// </summary>
+    /// <param name="migrations">The migrations in the order in which they must be applied.</param>
+    /// <param name="dbContext">The existing SQLite database context.</param>
+    /// <param name="version">Optional version information to record for each applied migration.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="migrations"/> or <paramref name="dbContext"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// The caller owns the database context and is responsible for committing or rolling back its transaction.
+    /// </remarks>
+    public static void Migrate(this IEnumerable<SQLiteDbMigration> migrations, SQLiteDbContext dbContext, string? version, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(migrations);
+        ArgumentNullException.ThrowIfNull(dbContext);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var executor = new SQLiteDbContextMigrationExecutor(dbContext);
+        var history = new SQLiteMigrationHistory();
+        var migrator = new DbMigrator<SQLiteDbMigrationContext>(executor, history, migrations, version);
+        migrator.Migrate(cancellationToken);
+    }
 }