Add transactional SQLite migrations

- add SQLite-specific migration and execution context
- add synchronized transactional migration executor
- add SQLite migration history storage
- record migration identifiers, timestamps, and optional version metadata
- validate and apply pending migrations atomically
- add migration integration and concurrency tests
- migrate MoviesAppSample from converters to migrations
- remove the legacy converter mechanism
- update package description and README

Author: ivanvoyager

.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 name: CI
 
 on:
+  workflow_dispatch: {}
   push:
     branches: [ main ]
   pull_request:
@@ -33,8 +34,8 @@ jobs:
       - name: Restore
         run: dotnet restore --nologo
 
-      - name: Build (Release)
-        run: dotnet build --configuration Release --nologo -warnaserror
+      - name: Build
+        run: dotnet build -c Release --no-restore --nologo -warnaserror
 
-      - name: Test (Release)
-        run: dotnet test --configuration Release --nologo --no-build
+      - name: Test
+        run: dotnet test --configuration Release --no-build

Directory.Build.targets

@@ -3,14 +3,14 @@
     <CsFiles Include="**\*.*.cs" />
   </ItemGroup>
   <ItemGroup>
-    <Compile Update="@(CsFiles)">
-      <DependentUpon>$([System.Text.RegularExpressions.Regex]::Replace('%(Filename)', '\..*$', '.cs'))</DependentUpon>
-    </Compile>
     <Compile Update="**\*Extensions.cs">
       <DependentUpon>$([System.String]::Copy('%(Filename)').Replace('Extensions', '.cs'))</DependentUpon>
     </Compile>
     <Compile Update="**\*Factory.cs">
       <DependentUpon>$([System.String]::Copy('%(Filename)').Replace('Factory', '.cs'))</DependentUpon>
     </Compile>
+    <Compile Update="@(CsFiles)">
+      <DependentUpon>$([System.Text.RegularExpressions.Regex]::Replace('%(Filename)', '\..*$', '.cs'))</DependentUpon>
+    </Compile>
   </ItemGroup>
 </Project>

README.md

@@ -14,7 +14,7 @@
 - **Transaction Scope Management**: Provides explicit transaction state tracking, prevents nested transactions, and supports coordinated execution through reentrant connection locks.
 - **Database Context Management**: Manages connection state, transaction lifetime, commit, rollback, and deterministic resource cleanup.
 - **ADO.NET Utilities**: Provides helpers for commands, parameters, readers, data adapters, schema inspection, and common SQLite operations.
-- **Schema Versioning**: Supports controlled database schema updates through the existing converter-based mechanism.
+- **Database Migrations**: Applies ordered schema and data migrations transactionally, records migration history with optional version metadata, and validates that the applied history matches the configured migration sequence.
 
 ### Important Considerations
 
@@ -48,23 +48,53 @@ connection.ExecuteInTransaction(transaction =>
 
 The callback is responsible for committing the transaction or explicitly rolling it back when the operation completes normally. If the callback throws while the transaction is still active, the transaction is rolled back automatically without replacing the original exception with a rollback error.
 
+#### Migration Example
+
+```csharp
+internal sealed class CreateMoviesSchema_0001 : SQLiteDbMigration
+{
+    public override string Id => "0001_CreateMoviesSchema";
+
+    public override void Up(SQLiteDbMigrationContext context)
+    {
+        context.ExecuteNonQuery(
+            """
+            CREATE TABLE Movies (
+                Id INTEGER PRIMARY KEY,
+                Title TEXT NOT NULL
+            );
+            """);
+    }
+}
+
+SQLiteDbMigration[] migrations =
+[
+    new CreateMoviesSchema_0001()
+];
+
+migrations.Migrate(CreateConnection, "1.0.0", cancellationToken);
+```
+
+Migrations are applied in the order in which they are registered. Applied migrations are recorded in the `__nuext_migrations` table together with their application time and optional version information. The complete migration batch is executed within a synchronized transaction and is rolled back if any migration fails.
+
 ### Commonly Used Types
 
-- **`System.Data.SQLite.SQLiteDalBase`**: Base class for SQLite-specific Data Access Layer (DAL) operations.
 - **`System.Data.SQLite.SQLiteDbConnection`**: Wraps SQLite connections with synchronized process-local access, transaction coordination, and utilities for common database operations.
-- **`System.Data.SQLite.SQLiteDbContext`**: Manages connection state and transaction lifetime, with optional validation that the connection lock remains held for the lifetime of the context.
-- **`System.Data.SQLite.SQLiteDbConverter`**: Base class for applying updates to the SQLite database schema.
 - **`System.Data.SQLite.SQLiteDbTransaction`**: Wraps SQLite transactions with explicit state tracking, commit and rollback operations, and transaction lifetime diagnostics.
+- **`System.Data.SQLite.SQLiteDbContext`**: Manages connection state and transaction lifetime, with optional validation that the connection lock remains held for the lifetime of the context.
+- **`System.Data.SQLite.SQLiteDalBase`**: Base class for SQLite-specific Data Access Layer (DAL) operations.
+- **`System.Data.SQLite.SQLiteDbMigration`**: Base class for defining ordered SQLite schema and data migrations.
+- **`System.Data.SQLite.SQLiteDbMigrationContext`**: Provides the execution context used by SQLite migrations.
 
 ### Installation
 
-You can install `NuExt.System.Data.SQLite` via [NuGet](https://www.nuget.org/):
+Via [NuGet](https://www.nuget.org/):
 
 ```sh
 dotnet add package NuExt.System.Data.SQLite
 ```
 
-Or through the Visual Studio package manager:
+Or via Visual Studio:
 
 1. Go to `Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution...`.
 2. Search for `NuExt.System.Data.SQLite`.
@@ -74,10 +104,20 @@ Or through the Visual Studio package manager:
 
 For examples of how to use these classes, see the [samples](samples). These samples provide practical guidance on implementing the library's features in real-world scenarios.
 
-### Contributing
+## Ecosystem
+
+- [NuExt.Minimal.Mvvm](https://github.com/nu-ext/NuExt.Minimal.Mvvm)
+- [NuExt.Minimal.Mvvm.SourceGenerator](https://github.com/nu-ext/NuExt.Minimal.Mvvm.SourceGenerator)
+- [NuExt.Minimal.Behaviors.Wpf](https://github.com/nu-ext/NuExt.Minimal.Behaviors.Wpf)
+- [NuExt.Minimal.Mvvm.Wpf](https://github.com/nu-ext/NuExt.Minimal.Mvvm.Wpf)
+- [NuExt.Minimal.Mvvm.MahApps.Metro](https://github.com/nu-ext/NuExt.Minimal.Mvvm.MahApps.Metro)
+- [NuExt.System](https://github.com/nu-ext/NuExt.System)
+- [NuExt.System.Data](https://github.com/nu-ext/NuExt.System.Data)
+
+## Contributing
 
-Contributions are welcome! Feel free to submit issues, fork the repository, and send pull requests. Your feedback and suggestions for improvement are highly appreciated.
+Issues and PRs are welcome. Keep changes minimal and performance-conscious.
 
-### License
+## License
 
-Licensed under the MIT License. See the LICENSE file for details.
+MIT. See LICENSE.

samples/MoviesAppSample/Converters/MoviesConverter10.cs

@@ -0,0 +1,26 @@
+using System.Data.SQLite;
+
+namespace MoviesAppSample.Migrations;
+
+internal sealed class CreateMoviesSchema_0001 : SQLiteDbMigration
+{
+    public override string Id => "0001_CreateMoviesSchema";
+
+    public override void Up(SQLiteDbMigrationContext context)
+    {
+        context.ExecuteNonQuery(
+            """
+            CREATE TABLE Movies (
+                Id INTEGER PRIMARY KEY,
+                Title TEXT NOT NULL,
+                Description TEXT,
+                DateReleased INTEGER NOT NULL
+            );
+
+            CREATE TABLE Persons (
+                Id INTEGER PRIMARY KEY,
+                Name TEXT NOT NULL UNIQUE
+            );
+            """);
+    }
+}

samples/MoviesAppSample/Converters/MoviesConverter11.cs

@@ -0,0 +1,38 @@
+using System.Data.SQLite;
+
+namespace MoviesAppSample.Migrations;
+
+internal sealed class CreateMovieRelationships_0002 : SQLiteDbMigration
+{
+    public override string Id => "0002_CreateMovieRelationships";
+
+    public override void Up(SQLiteDbMigrationContext context)
+    {
+        context.ExecuteNonQuery(
+            """
+            CREATE TABLE MovieCasts (
+                MovieId INTEGER NOT NULL,
+                PersonId INTEGER NOT NULL,
+                FOREIGN KEY (MovieId) REFERENCES Movies(Id),
+                FOREIGN KEY (PersonId) REFERENCES Persons(Id),
+                PRIMARY KEY (MovieId, PersonId)
+            );
+
+            CREATE TABLE MovieDirectors (
+                MovieId INTEGER NOT NULL,
+                PersonId INTEGER NOT NULL,
+                FOREIGN KEY (MovieId) REFERENCES Movies(Id),
+                FOREIGN KEY (PersonId) REFERENCES Persons(Id),
+                PRIMARY KEY (MovieId, PersonId)
+            );
+
+            CREATE TABLE MovieWriters (
+                MovieId INTEGER NOT NULL,
+                PersonId INTEGER NOT NULL,
+                FOREIGN KEY (MovieId) REFERENCES Movies(Id),
+                FOREIGN KEY (PersonId) REFERENCES Persons(Id),
+                PRIMARY KEY (MovieId, PersonId)
+            );
+            """);
+    }
+}

samples/MoviesAppSample/Migrations/0001_CreateMoviesSchema.cs

@@ -1,14 +1,18 @@
-using MoviesAppSample.Converters;
+using MoviesAppSample.Migrations;
 using MoviesAppSample.DataAccess;
 using MoviesAppSample.Models;
 using System.Data;
 using System.Data.SQLite;
+using System.Reflection;
 
 namespace MoviesAppSample.Services;
 
 internal class MoviesService(string dataBasePath)
 {
-    private static readonly SQLiteDbConverter[] s_moviesConverters = [new MoviesConverter10(), new MoviesConverter11()
+    private static readonly SQLiteDbMigration[] s_migrations =
+    [
+        new CreateMoviesSchema_0001(),
+        new CreateMovieRelationships_0002()
     ];
 
     #region Properties
@@ -42,7 +46,6 @@ public async ValueTask<List<Movie>> GetAllMoviesAsync(CancellationToken cancella
             using var dbContext = new SQLiteDbContext(connection);
             try
             {
-                s_moviesConverters.Initialize(dbContext, cancellationToken);
                 using var movieDal = new MovieDal(CreateConnection);
                 using var personDal = new PersonDal(CreateConnection);
                 var movieDtos = await movieDal.LoadMoviesAsync(dbContext, cancellationToken);
@@ -86,7 +89,8 @@ private string GetMoviesConnectionString()
 
     public ValueTask InitializeAsync(CancellationToken cancellationToken)
     {
-        s_moviesConverters.Initialize(CreateConnection, cancellationToken);
+        var info = new AssemblyInfo();
+        s_migrations.Migrate(CreateConnection, info.Version?.ToString(), cancellationToken);
         return default;
     }
 
@@ -99,7 +103,6 @@ public async ValueTask<bool> SaveMovieAsync(Movie movie, CancellationToken cance
             using var dbContext = new SQLiteDbContext(connection);
             try
             {
-                s_moviesConverters.Initialize(dbContext, cancellationToken);
                 using var movieDal = new MovieDal(CreateConnection);
                 using var personDal = new PersonDal(CreateConnection);
 

samples/MoviesAppSample/Migrations/0002_CreateMovieRelationships.cs

@@ -4,7 +4,7 @@
     <TargetFrameworks>netstandard2.1;netstandard2.0;net10.0;net9.0;net8.0;net471;net462</TargetFrameworks>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
-    <Description>High‑performance SQLite data access utilities for .NET, providing thread‑safe connection handling, reliable transaction management, and a consistent DAL foundation. Includes context and converter abstractions to simplify schema updates, coordinate concurrent operations, and ensure predictable behavior across SQLite’s locking model.</Description>
+    <Description>High-performance SQLite data access utilities for .NET, providing synchronized process-local connection access, explicit transaction management, a consistent DAL foundation, and transactional database migrations with validated history tracking.</Description>
     <RootNamespace />
     <GenerateDocumentationFile>True</GenerateDocumentationFile>
     <NoWarn>$(NoWarn);1591;NETSDK1233</NoWarn>
@@ -23,4 +23,4 @@
     <ProjectReference Include="..\..\NuExt.System.Data\src\NuExt.System.Data.csproj" />
   </ItemGroup>
 
-</Project>
+</Project>

samples/MoviesAppSample/Services/MoviesService.cs

@@ -1,5 +1,4 @@
 using System.ComponentModel;
-using System.Diagnostics;
 
 namespace System.Data.SQLite;
 
@@ -24,7 +23,7 @@ public void Dispose()
             if (connection is not null)
             {
                 int count = Interlocked.Decrement(ref connection._assertsSuspendCount);
-                Debug.Assert(count >= 0, $"{nameof(AssertsSuspender)} was disposed without a matching suspension.");
+                System.Diagnostics.Debug.Assert(count >= 0, $"{nameof(AssertsSuspender)} was disposed without a matching suspension.");
             }
         }
     }
@@ -50,19 +49,6 @@ public void Dispose()
 
     #region Methods
 
-    [Conditional("DEBUG")]
-    internal void DisableAsserts()
-    {
-        Interlocked.Increment(ref _assertsSuspendCount);
-    }
-
-    [Conditional("DEBUG")]
-    internal void RestoreAsserts()
-    {
-        int count = Interlocked.Decrement(ref _assertsSuspendCount);
-        Debug.Assert(count >= 0, $"{nameof(RestoreAsserts)} called without a matching {nameof(DisableAsserts)}.");
-    }
-
     /// <summary>
     /// Temporarily disables diagnostic assertions until the returned object is disposed.
     /// </summary>