Centralize SQLite context execution

- add a synchronized SQLite database context executor
- centralize connection, lock, transaction, commit, and rollback handling
- simplify SQLiteDalBase
- update sample DAL implementations
- add integration tests for owned and borrowed contexts

Author: ivanvoyager

README.md

@@ -8,47 +8,49 @@
 [![License](https://img.shields.io/github/license/nu-ext/NuExt.System.Data.SQLite?label=license)](https://github.com/nu-ext/NuExt.System.Data.SQLite/blob/main/LICENSE)
 [![Downloads](https://img.shields.io/nuget/dt/NuExt.System.Data.SQLite.svg)](https://www.nuget.org/packages/NuExt.System.Data.SQLite)
 
-### Features
+## Features
 
 - **Synchronized Database Access**: Coordinates operations through reentrant process-local locks, including shared locks for multiple connections targeting the same database.
 - **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.
 - **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
+## Important Considerations
 
 SQLite allows multiple readers but serializes writes according to the configured journal mode and transaction state. Long-running write transactions can delay other operations and increase the likelihood of lock timeouts.
 
 The library's shared lock is intentionally process-local. Applications that access the same database from multiple processes must still rely on SQLite locking, timeouts, and appropriate journal configuration.
 
-### Concurrency and Locking
+## Concurrency and Locking
 
 `SQLiteDbConnection` uses a reentrant process-local lock to coordinate database operations. When shared locking is enabled, connections targeting the same database use the same lock. When shared locking is disabled, each wrapper connection uses its own lock.
 
 This coordination helps reduce competing write operations and `"database is locked"` errors originating within the same process. It does not replace SQLite file locking and cannot coordinate access from other processes or external database tools.
 
 Transactions can be used directly when the caller guarantees exclusive connection access. Concurrent or reentrant scenarios should execute the entire transaction lifetime within `AcquireLock` or use `ExecuteInTransaction`.
 
-#### Transaction Example
+## Quick Examples
+
+### Transaction Example
 
 ```csharp
 connection.ExecuteInTransaction(transaction =>
 {
     connection.ExecuteNonQuery(
-        "UPDATE movies SET title = @title WHERE id = @id",
+        "UPDATE Movies SET Title = @Title WHERE Id = @Id",
         CommandBehavior.Default,
         cancellationToken,
-        DbType.String.CreateInputParam("@title", title),
-        DbType.Int64.CreateInputParam("@id", id));
+        DbType.String.CreateInputParam("@Title", title),
+        DbType.Int64.CreateInputParam("@Id", id));
 
     transaction.Commit();
 }, cancellationToken);
 ```
 
 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
+### Migration Example
 
 ```csharp
 internal sealed class CreateMoviesSchema_0001 : SQLiteDbMigration
@@ -75,18 +77,18 @@ SQLiteDbMigration[] migrations =
 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.
+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. When a connection factory is used, the complete migration batch is executed within a synchronized transaction and is rolled back if any migration fails. Migrations can also use an existing `SQLiteDbContext`, allowing the caller to include migrations and application operations in the same transaction and retain responsibility for committing or rolling it back.
 
-### Commonly Used Types
+## Commonly Used Types
 
-- **`System.Data.SQLite.SQLiteDbConnection`**: Wraps SQLite connections with synchronized process-local access, transaction coordination, and utilities for common database operations.
-- **`System.Data.SQLite.SQLiteDbTransaction`**: Wraps SQLite transactions with explicit state tracking, commit and rollback operations, and transaction lifetime diagnostics.
+- **`System.Data.SQLite.SQLiteDalBase`**: Base class for SQLite DAL implementations with synchronized provider-managed context execution and access to connection creation for custom scenarios.
+- **`System.Data.SQLite.SQLiteDbConnection`**: Wraps SQLite connections with process-local synchronization, transaction coordination, command execution, schema inspection, and common data access utilities.
 - **`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.
+- **`System.Data.SQLite.SQLiteDbTransaction`**: Wraps SQLite transactions with explicit state tracking, commit and rollback operations, and transaction lifetime diagnostics.
 
-### Installation
+## Installation
 
 Via [NuGet](https://www.nuget.org/):
 
@@ -100,7 +102,11 @@ Or via Visual Studio:
 2. Search for `NuExt.System.Data.SQLite`.
 3. Click "Install".
 
-### Usage Examples
+### Compatibility
+
+**.NET Standard 2.0+, .NET 8/9/10 and .NET Framework 4.6.2+**
+
+## Usage Examples
 
 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.
 

samples/MoviesAppSample/DataAccess/MovieDal.cs

@@ -11,21 +11,15 @@ internal sealed class MovieDal(Func<SQLiteDbConnection> createConnection) : SQLi
 
     private static readonly string[] s_updateColumns = ["Title", "Description", "DateReleased"];
 
-    #region Properties
-
-    protected override string[] Columns => s_columns;
-
-    protected override string TableName => "Movies";
-
-    #endregion
+    private const string TableName = "Movies";
 
     #region Methods
 
     public ValueTask<bool> DeleteMovieAsync(SQLiteDbContext? context, long id, CancellationToken cancellationToken)
     {
         Debug.Assert(id > 0);
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, async ctx =>
+        return ExecuteInDbContextAsync(context, async ctx =>
         {
             using var personDal = new PersonDal(CreateConnection);
             bool result = await personDal.DeleteMoviePersonsAsync(ctx, id, cancellationToken);
@@ -35,8 +29,8 @@ public ValueTask<bool> DeleteMovieAsync(SQLiteDbContext? context, long id, Cance
             await
 #endif
 
-                using var command = ctx.Connection.CreateCommandDelete(TableName, "WHERE Id=@Id",
-                DbType.Int64.CreateInputParam("@Id", id));
+            using var command = ctx.Connection.CreateCommandDelete(TableName, "WHERE Id=@Id",
+            DbType.Int64.CreateInputParam("@Id", id));
             int affected = ctx.Connection.ExecuteNonQuery(command, cancellationToken: cancellationToken);
             return affected == 1;
         }, cancellationToken);
@@ -45,7 +39,7 @@ public ValueTask<bool> DeleteMovieAsync(SQLiteDbContext? context, long id, Cance
     public ValueTask<bool> DeleteMoviesAsync(SQLiteDbContext? context, IEnumerable<long> ids, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, async ctx =>
+        return ExecuteInDbContextAsync(context, async ctx =>
         {
             using var personDal = new PersonDal(CreateConnection);
 
@@ -54,8 +48,8 @@ public ValueTask<bool> DeleteMoviesAsync(SQLiteDbContext? context, IEnumerable<l
             await
 #endif
 
-                using var command = ctx.Connection.CreateCommandDelete(TableName, "WHERE Id=@Id",
-                    DbType.Int64.CreateInputParam("@Id", 0));
+            using var command = ctx.Connection.CreateCommandDelete(TableName, "WHERE Id=@Id",
+                DbType.Int64.CreateInputParam("@Id", 0));
             int affected = 0;
             foreach (var id in ids)
             {
@@ -71,9 +65,9 @@ public ValueTask<bool> DeleteMoviesAsync(SQLiteDbContext? context, IEnumerable<l
     {
         Debug.Assert(id > 0);
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, ctx =>
+        return ExecuteInDbContextAsync(context, ctx =>
         {
-            using var command = ctx.Connection.CreateCommandSelect(TableName, Columns, "WHERE Id=@Id LIMIT 1",
+            using var command = ctx.Connection.CreateCommandSelect(TableName, s_columns, "WHERE Id=@Id LIMIT 1",
                 DbType.Int64.CreateInputParam("@Id", id));
             MovieDto? dto = null;
             int count = ctx.Connection.ExecuteReader(command, Read, cancellationToken: cancellationToken);
@@ -90,9 +84,9 @@ void Read(SQLiteDataReader reader)
     public ValueTask<List<MovieDto>> LoadMoviesAsync(SQLiteDbContext? context, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, ctx =>
+        return ExecuteInDbContextAsync(context, ctx =>
         {
-            using var command = ctx.Connection.CreateCommandSelect(TableName, Columns, "ORDER BY DateReleased");
+            using var command = ctx.Connection.CreateCommandSelect(TableName, s_columns, "ORDER BY DateReleased");
             var list = new List<MovieDto>();
             int count = ctx.Connection.ExecuteReader(command, Read, cancellationToken: cancellationToken);
             Debug.Assert(list.Count == count);
@@ -118,7 +112,7 @@ private static MovieDto ReadMovie(DbDataReader reader)
     public ValueTask<(bool result, MovieDto dto)> SaveMovieAsync(SQLiteDbContext? context, MovieDto dto, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, ctx =>
+        return ExecuteInDbContextAsync(context, ctx =>
         {
             SQLiteCommand command;
             if (dto.Id <= 0)

samples/MoviesAppSample/DataAccess/PersonDal.cs

@@ -6,8 +6,6 @@ namespace MoviesAppSample.DataAccess;
 
 internal sealed class PersonDal(Func<SQLiteDbConnection> createConnection) : SQLiteDalBase(createConnection)
 {
-    private static readonly string[] s_columns = ["Id", "Name"];
-
     private static readonly string[] s_idColumns = ["Id"];
 
     private static readonly string[] s_updateColumns = ["Name"];
@@ -16,20 +14,15 @@ internal sealed class PersonDal(Func<SQLiteDbConnection> createConnection) : SQL
 
     private static readonly string[] s_relationshipTables = ["MovieCasts", "MovieDirectors", "MovieWriters"];
 
-    #region Properties
-
-    protected override string[] Columns => s_columns;
-    protected override string TableName => "Persons";
-
-    #endregion
+    private const string TableName = "Persons";
 
     #region Methods
 
     public ValueTask<bool> DeleteMoviePersonsAsync(SQLiteDbContext context, long movieId, CancellationToken cancellationToken)
     {
         Debug.Assert(movieId > 0);
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, ctx =>
+        return ExecuteInDbContextAsync(context, ctx =>
         {
             int affected = 0;
             foreach (var tableName in s_relationshipTables)
@@ -63,7 +56,7 @@ public ValueTask<List<PersonDto>> LoadMovieWritersAsync(SQLiteDbContext context,
     private ValueTask<List<PersonDto>> LoadMoviePersonsAsync(SQLiteDbContext context, string tableName, long movieId, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, ctx =>
+        return ExecuteInDbContextAsync(context, ctx =>
         {
             using var command = ctx.Connection.CreateCommand($"""
                 SELECT p.Id, p.Name
@@ -109,7 +102,7 @@ private ValueTask<bool> SaveMoviePersonsAsync(SQLiteDbContext context, string ta
         Debug.Assert(movieId > 0);
 
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, ctx =>
+        return ExecuteInDbContextAsync(context, ctx =>
         {
             var (adapter, table) = ctx.Connection.SelectForUpdate(tableName, s_relationshipColumns, "WHERE MovieId=@MovieId", true, cancellationToken,
                 DbType.Int64.CreateInputParam("@MovieId", movieId));
@@ -151,7 +144,7 @@ public ValueTask<bool> SavePersonsAsync(SQLiteDbContext context, List<PersonDto>
         ArgumentNullException.ThrowIfNull(dtos);
 
         cancellationToken.ThrowIfCancellationRequested();
-        return TryExecuteInDbContextAsync(context, ctx =>
+        return ExecuteInDbContextAsync(context, ctx =>
         {
             using var commandInsert = ctx.Connection.CreateCommandInsertOrIgnore(TableName, s_updateColumns,
                 "RETURNING Id",

samples/MoviesAppSample/Services/MoviesService.cs

@@ -1,9 +1,9 @@
-using MoviesAppSample.Migrations;
-using MoviesAppSample.DataAccess;
-using MoviesAppSample.Models;
-using System.Data;
+using System.Data;
 using System.Data.SQLite;
 using System.Reflection;
+using MoviesAppSample.DataAccess;
+using MoviesAppSample.Migrations;
+using MoviesAppSample.Models;
 
 namespace MoviesAppSample.Services;
 
@@ -67,9 +67,9 @@ public async ValueTask<List<Movie>> GetAllMoviesAsync(CancellationToken cancella
                 dbContext.Commit();
                 return movies;
             }
-            catch
+            catch (Exception ex)
             {
-                dbContext.Rollback();
+                dbContext.TryRollback(ex);
                 throw;
             }
         }, cancellationToken);
@@ -157,9 +157,9 @@ public async ValueTask<bool> SaveMovieAsync(Movie movie, CancellationToken cance
                 dbContext.Commit();
                 return true;
             }
-            catch
+            catch (Exception ex)
             {
-                dbContext.Rollback();
+                dbContext.TryRollback(ex);
                 throw;
             }
         }, cancellationToken);