Improve SQLite execution performance

- add state-aware connection lock and reader overloads
- add transaction execution overloads with explicit state and isolation level
- use static callbacks to avoid closure allocations
- optimize command, adapter, context, migration, and schema inspection paths
- preserve existing locking, transaction, cancellation, and rollback behavior
- update public API documentation

Author: ivanvoyager

README.md

@@ -14,11 +14,12 @@
 - **Transaction Scope Management**: Provides explicit transaction state tracking, prevents nested transactions, preserves original exceptions when rollback fails, 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.
+- **Allocation-Conscious APIs**: Provides span-based parameters, `ValueTask`-based coordination, and explicit-state callbacks that help avoid closure allocations.
 - **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.
 
 ## Why NuExt.System.Data.SQLite?
 
-`NuExt.System.Data.SQLite` is designed as a performance-oriented infrastructure layer over ADO.NET rather than an ORM. It keeps SQL, commands, parameters, readers, and transactions explicit while removing repetitive connection, transaction, and resource lifecycle code.
+`NuExt.System.Data.SQLite` is designed as a performance-oriented infrastructure layer over ADO.NET rather than an ORM. It keeps SQL, commands, parameters, readers, and transactions explicit while removing repetitive connection, transaction, and resource lifecycle code. It also preserves SQLite's synchronous execution model instead of wrapping database operations in artificial asynchronous work.
 
 The library supports both standalone DAL operations and coordinated units of work, protects complete database operation scopes during concurrent and reentrant execution, and provides forward-only migrations with deterministic ordering and strict history validation.
 

src/System/Data/SQLite/SQLiteDbConnection.Adapters.cs

@@ -42,7 +42,7 @@ public SQLiteDataAdapter CreateAdapter(SQLiteCommand command)
     /// </summary>
     /// <param name="tableName">The name of the table.</param>
     /// <param name="fields">The fields to select.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <returns>A table containing the selected data.</returns>
     public DataTable Select(string tableName, IEnumerable<string> fields, CancellationToken cancellationToken = default)
     {
@@ -73,7 +73,7 @@ public DataTable Select(string tableName, IEnumerable<string> fields, string? ex
     /// <param name="tableName">The name of the table.</param>
     /// <param name="fields">The fields to select.</param>
     /// <param name="expr">An optional SQL expression appended to the command.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <param name="parameters">The parameters to add to the command.</param>
     /// <returns>A table containing the selected data.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -110,7 +110,7 @@ public DataTable Select(string sql, params SQLiteParameter[] parameters)
     /// Executes the specified query and returns the selected data.
     /// </summary>
     /// <param name="sql">The SQL statement to execute.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <param name="parameters">The parameters to add to the command.</param>
     /// <returns>A table containing the selected data.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -131,7 +131,7 @@ public DataTable Select(string sql, CancellationToken cancellationToken, params
     /// Executes the specified command and returns the selected data.
     /// </summary>
     /// <param name="command">The SQLite command to execute.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <returns>A table containing the selected data.</returns>
     public DataTable Select(SQLiteCommand command, CancellationToken cancellationToken = default)
     {
@@ -162,7 +162,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// </summary>
     /// <param name="tableName">The name of the table.</param>
     /// <param name="fields">The fields to select.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
     /// The caller is responsible for disposing the returned adapter.
@@ -178,7 +178,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// <param name="tableName">The name of the table.</param>
     /// <param name="fields">The fields to select.</param>
     /// <param name="generateCommands"><see langword="true"/> to generate insert, update, and delete commands; otherwise, <see langword="false"/>.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
     /// The caller is responsible for disposing the returned adapter.
@@ -215,7 +215,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// <param name="tableName">The name of the table.</param>
     /// <param name="fields">The fields to select.</param>
     /// <param name="expr">An optional SQL expression appended to the command.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <param name="parameters">The parameters to add to the command.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
@@ -260,7 +260,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// <param name="fields">The fields to select.</param>
     /// <param name="expr">An optional SQL expression appended to the command.</param>
     /// <param name="generateCommands"><see langword="true"/> to generate insert, update, and delete commands; otherwise, <see langword="false"/>.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <param name="parameters">The parameters to add to the command.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
@@ -302,7 +302,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// Executes the specified query and creates an adapter that can update the returned data.
     /// </summary>
     /// <param name="sql">The SQL statement to execute.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <param name="parameters">The parameters to add to the command.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
@@ -343,7 +343,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// </summary>
     /// <param name="sql">The SQL statement to execute.</param>
     /// <param name="generateCommands"><see langword="true"/> to generate insert, update, and delete commands; otherwise, <see langword="false"/>.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <param name="parameters">The parameters to add to the command.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
@@ -366,7 +366,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// Executes the specified command and creates an adapter that can update the returned data.
     /// </summary>
     /// <param name="command">The SQLite command to execute.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
     /// The caller is responsible for disposing the returned adapter.
@@ -382,7 +382,7 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// </summary>
     /// <param name="command">The SQLite command to execute.</param>
     /// <param name="generateCommands"><see langword="true"/> to generate insert, update, and delete commands; otherwise, <see langword="false"/>.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <returns>
     /// The configured data adapter and selected data table.
     /// The caller is responsible for disposing the returned adapter.
@@ -429,14 +429,14 @@ public DataTable Select(SQLiteCommand command, CancellationToken cancellationTok
     /// </summary>
     /// <param name="adapter">The data adapter used to retrieve data.</param>
     /// <param name="table">The data table to fill.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     public void Fill(SQLiteDataAdapter adapter, DataTable table, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(adapter);
         ArgumentNullException.ThrowIfNull(table);
         cancellationToken.ThrowIfCancellationRequested();
 
-        AcquireLock(() => adapter.Fill(table), cancellationToken);
+        AcquireLock(static state => state.Adapter.Fill(state.Table), (Adapter: adapter, Table: table), cancellationToken);
     }
 
     #endregion
@@ -448,7 +448,7 @@ public void Fill(SQLiteDataAdapter adapter, DataTable table, CancellationToken c
     /// </summary>
     /// <param name="adapter">The data adapter used to update the database.</param>
     /// <param name="table">The data table containing the changes.</param>
-    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <param name="cancellationToken">A token to observe while waiting to acquire the connection lock.</param>
     /// <returns>The number of rows successfully updated.</returns>
     public int Update(SQLiteDataAdapter adapter, DataTable table, CancellationToken cancellationToken = default)
     {
@@ -457,7 +457,7 @@ public int Update(SQLiteDataAdapter adapter, DataTable table, CancellationToken
         cancellationToken.ThrowIfCancellationRequested();
 
         // Update requires a valid UpdateCommand when passed a DataRow collection with modified rows.
-        return AcquireLock(() => adapter.Update(table), cancellationToken);
+        return AcquireLock(static state => state.Adapter.Update(state.Table), (Adapter: adapter, Table: table), cancellationToken);
     }
 
     #endregion

src/System/Data/SQLite/SQLiteDbConnection.AsyncLock.cs

@@ -16,6 +16,20 @@ public void AcquireLock(Action action, CancellationToken cancellationToken = def
         GetSyncRoot().Mutex.Acquire(action, cancellationToken);
     }
 
+    /// <summary>
+    /// Acquires a lock and executes the specified action with the provided state while holding the lock.
+    /// </summary>
+    /// <typeparam name="TState">The type of the state passed to the action.</typeparam>
+    /// <param name="action">The action to execute while holding the lock.</param>
+    /// <param name="state">The state to pass to the action.</param>
+    /// <param name="cancellationToken">A token to observe while waiting for the lock.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="action"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ObjectDisposedException">The connection has been disposed.</exception>
+    public void AcquireLock<TState>(Action<TState> action, TState state, CancellationToken cancellationToken = default)
+    {
+        GetSyncRoot().Mutex.Acquire(action, state, cancellationToken);
+    }
+
     /// <summary>
     /// Acquires a lock and executes the specified function while holding the lock.
     /// </summary>
@@ -30,6 +44,22 @@ public T AcquireLock<T>(Func<T> func, CancellationToken cancellationToken = defa
         return GetSyncRoot().Mutex.Acquire(func, cancellationToken);
     }
 
+    /// <summary>
+    /// Acquires a lock and executes the specified function with the provided state while holding the lock.
+    /// </summary>
+    /// <typeparam name="TState">The type of the state passed to the function.</typeparam>
+    /// <typeparam name="TResult">The type of the result returned by the function.</typeparam>
+    /// <param name="func">The function to execute while holding the lock.</param>
+    /// <param name="state">The state to pass to the function.</param>
+    /// <param name="cancellationToken">A token to observe while waiting for the lock.</param>
+    /// <returns>The result of the function executed while holding the lock.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="func"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ObjectDisposedException">The connection has been disposed.</exception>
+    public TResult AcquireLock<TState, TResult>(Func<TState, TResult> func, TState state, CancellationToken cancellationToken = default)
+    {
+        return GetSyncRoot().Mutex.Acquire(func, state, cancellationToken);
+    }
+
     /// <summary>
     /// Asynchronously acquires a lock and executes the specified asynchronous function while holding the lock.
     /// </summary>
@@ -43,6 +73,21 @@ public ValueTask AcquireLockAsync(Func<ValueTask> func, CancellationToken cancel
         return GetSyncRoot().Mutex.AcquireAsync(func, cancellationToken);
     }
 
+    /// <summary>
+    /// Asynchronously acquires a lock and executes the specified asynchronous function with the provided state while holding the lock.
+    /// </summary>
+    /// <typeparam name="TState">The type of the state passed to the function.</typeparam>
+    /// <param name="func">The asynchronous function to execute while holding the lock.</param>
+    /// <param name="state">The state to pass to the function.</param>
+    /// <param name="cancellationToken">A token to observe while waiting for the lock.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="func"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ObjectDisposedException">The connection has been disposed.</exception>
+    public ValueTask AcquireLockAsync<TState>(Func<TState, ValueTask> func, TState state, CancellationToken cancellationToken = default)
+    {
+        return GetSyncRoot().Mutex.AcquireAsync(func, state, cancellationToken);
+    }
+
     /// <summary>
     /// Asynchronously acquires a lock and executes the specified asynchronous function while holding the lock.
     /// </summary>
@@ -57,6 +102,22 @@ public ValueTask<T> AcquireLockAsync<T>(Func<ValueTask<T>> func, CancellationTok
         return GetSyncRoot().Mutex.AcquireAsync(func, cancellationToken);
     }
 
+    /// <summary>
+    /// Asynchronously acquires a lock and executes the specified asynchronous function with the provided state while holding the lock.
+    /// </summary>
+    /// <typeparam name="TState">The type of the state passed to the function.</typeparam>
+    /// <typeparam name="TResult">The type of the result returned by the function.</typeparam>
+    /// <param name="func">The asynchronous function to execute while holding the lock.</param>
+    /// <param name="state">The state to pass to the function.</param>
+    /// <param name="cancellationToken">A token to observe while waiting for the lock.</param>
+    /// <returns>A task that represents the asynchronous operation and contains the result of the function.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="func"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ObjectDisposedException">The connection has been disposed.</exception>
+    public ValueTask<TResult> AcquireLockAsync<TState, TResult>(Func<TState, ValueTask<TResult>> func, TState state, CancellationToken cancellationToken = default)
+    {
+        return GetSyncRoot().Mutex.AcquireAsync(func, state, cancellationToken);
+    }
+
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     private SQLiteDbConnectionFactory.AsyncLockCounter GetSyncRoot()
     {