parallel enhancements

Here's a summary of every change made:

New files
File	Purpose
src/SqliteErrorCodes.cs	Internal constants and classifiers for SQLITE_BUSY, SQLITE_BUSY_SNAPSHOT (517), SQLITE_BUSY_RECOVERY, SQLITE_LOCKED, etc.
src/Models/SqliteSynchronousMode.cs	Enum for PRAGMA synchronous (Off/Normal/Full/Extra) with full durability trade-off documentation
src/Models/WalCheckpointStatus.cs	Record returned by GetWalCheckpointStatusAsync — exposes busy flag, total frames, checkpointed frames, and progress %
Modified files
SqliteConcurrencyOptions.cs

Added SynchronousMode (default Normal), UpgradeTransactionsToImmediate (default true), LoggerFactory (excluded from equality)
Added Validate() with bounds checks on all numeric properties
Updated Equals/GetHashCode to include new behavior-affecting properties
SqliteConcurrencyInterceptor.cs

Creates ILogger<SqliteConcurrencyInterceptor> from options.LoggerFactory
Logs SQLITE_BUSY_SNAPSHOT (Warning), SQLITE_BUSY (Warning), and SQLITE_LOCKED (Error) in CommandFailed/CommandFailedAsync
Logs BEGIN IMMEDIATE upgrades at Debug level
Respects UpgradeTransactionsToImmediate = false; also now catches BEGIN DEFERRED
SqliteConnectionEnhancer.cs

Uses options.SynchronousMode.ToString().ToUpperInvariant() instead of hardcoded NORMAL
Added inline comments on every pragma explaining the reason, trade-off, and safe range
Added GetWalCheckpointStatusAsync() — runs PRAGMA wal_checkpoint(PASSIVE) and returns WalCheckpointStatus
SqliteConcurrencyExtensions.cs

Calls options.Validate() on startup
Retry now catches via SqliteErrorCodes.IsAnyBusy() (covers all extended codes); SQLITE_LOCKED propagates immediately
Backoff replaced with exponential + full jitter: sleep in [baseDelay, 2×baseDelay]
ThreadSafeSqliteContext.cs

Same SqliteErrorCodes-based retry; SQLITE_BUSY_SNAPSHOT restarts the full operation lambda (correct semantics — stale data is re-queried)
Jitter added to backoff
TimeoutException message now identifies whether it was a snapshot error and includes the extended error code
SqliteConcurrencyServiceCollectionExtensions.cs

Resolves ILoggerFactory from the DI container and injects it into options automatically
doc/QUICKSTART.md

Removed all UseWriteQueue references
Replaced the incorrect options table with the real six options, each with accurate defaults and descriptions

Author: CornerstoneCode

EntityFrameworkCore.Sqlite.Concurrency/EFCore.Sqlite.Concurrency.csproj

@@ -93,9 +93,9 @@ Get started in one line. Stop compromising on SQLite reliability and speed.
         <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="10.0.2" />
         <PackageReference Include="Microsoft.Data.Sqlite" Version="10.0.2" />
         <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.2" />
-        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.2" />
+        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.5" />
         <!-- SourceLink for debugging support -->
-        <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
+        <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.201" PrivateAssets="All" />
     </ItemGroup>
 
     <!-- Optional Dependencies (Conditional) -->

EntityFrameworkCore.Sqlite.Concurrency/doc/QUICKSTART.md

@@ -52,7 +52,6 @@ builder.Services.AddDbContext<BlogDbContext>(options =>
         "Data Source=blog.db",
         sqliteOptions =>
         {
-            sqliteOptions.UseWriteQueue = true;     // Enable write serialization
             sqliteOptions.BusyTimeout = TimeSpan.FromSeconds(30);
             sqliteOptions.MaxRetryAttempts = 5;
         }));
@@ -216,8 +215,7 @@ public class TaskProcessor
 ```csharp
 // Create contexts manually when needed
 var dbContext = ThreadSafeFactory.CreateContext<BlogDbContext>(
-    "Data Source=blog.db",
-    options => options.UseWriteQueue = true);
+    "Data Source=blog.db");
 
 // Use it
 await dbContext.Posts.AddAsync(new Post { Title = "Hello World" });
@@ -254,11 +252,12 @@ public async Task UpdatePostWithRetryAsync(int postId, string newContent)
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `UseWriteQueue` | `true` | Automatically queue write operations |
-| `BusyTimeout` | 30 seconds | How long to wait if database is busy |
-| `MaxRetryAttempts` | 3 | Number of retries for busy errors |
-| `CommandTimeout` | 300 seconds | SQL command timeout |
-| `EnableWalCheckpointManagement` | `true` | Automatically manage WAL checkpoints |
+| `BusyTimeout` | 30 seconds | Per-connection `PRAGMA busy_timeout`. First layer of busy handling; SQLite retries lock acquisition internally for up to this duration. |
+| `MaxRetryAttempts` | 3 | Application-level retry attempts for `SQLITE_BUSY*` errors, with exponential backoff and jitter. |
+| `CommandTimeout` | 300 seconds | EF Core SQL command timeout in seconds. |
+| `WalAutoCheckpoint` | 1000 pages | WAL auto-checkpoint interval (`PRAGMA wal_autocheckpoint`). Each page is 4 096 bytes by default (~4 MB). Set to `0` to disable. |
+| `SynchronousMode` | `Normal` | Durability vs. performance trade-off (`PRAGMA synchronous`). `Normal` is recommended for WAL mode: safe against application crashes; a power loss or OS crash may roll back the last commit(s) not yet checkpointed. Use `Full` or `Extra` for stronger durability guarantees. |
+| `UpgradeTransactionsToImmediate` | `true` | Rewrites `BEGIN`/`BEGIN TRANSACTION` to `BEGIN IMMEDIATE` to prevent `SQLITE_BUSY_SNAPSHOT` mid-transaction. Disable only if you manage write transactions explicitly yourself. |
 
 ## Best Practices
 

EntityFrameworkCore.Sqlite.Concurrency/doc/v10_0_0.md

@@ -19,7 +19,7 @@ options.UseSqlite("Data Source=app.db");
 // With this:
 options.UseSqliteWithConcurrency("Data Source=app.db");
 ```
-Guaranteed 100% write reliability and up to 10x faster bulk operations.
+Eliminates write contention errors and provides up to 10x faster bulk operations.
 
 ---
 
@@ -70,7 +70,7 @@ Next, explore high-performance bulk inserts or fine-tune the configuration.
 | **Mixed Read/Write Workload** | ~15.3 seconds | ~3.8 seconds | **4.0x faster** |
 | **Memory Usage (100k operations)** | ~425 MB | ~285 MB | **33% less memory** |
 
-*Benchmark environment: .NET 10, Windows 11, Intel i7-13700K, 32GB RAM*
+**Benchmark environment:** .NET 10, Windows 11, Intel i7-13700K, 32GB RAM*
 
 ---
 
@@ -82,13 +82,7 @@ public async Task PerformDataMigrationAsync(List<LegacyData> legacyRecords)
 {
     var modernRecords = legacyRecords.Select(ConvertToModernFormat);
 
-    await _context.BulkInsertSafeAsync(modernRecords, new BulkConfig
-    {
-        BatchSize = 5000,
-        PreserveInsertOrder = true,
-        EnableStreaming = true,
-        UseOptimalTransactionSize = true
-    });
+    await _context.BulkInsertSafeAsyncmodernRecords);
 }
 ```
 
@@ -114,8 +108,7 @@ public async Task<TResult> ExecuteHighPerformanceOperationAsync<TResult>(
     Func<DbContext, Task<TResult>> operation)
 {
     using var context = ThreadSafeFactory.CreateContext<AppDbContext>(
-        "Data Source=app.db",
-        options => options.EnablePerformanceOptimizations = true);
+        "Data Source=app.db");
 
     return await context.ExecuteWithRetryAsync(operation, maxRetries: 2);
 }
@@ -136,7 +129,6 @@ services.AddDbContext<AppDbContext>(options =>
             concurrencyOptions.BusyTimeout = TimeSpan.FromSeconds(30);
             concurrencyOptions.MaxRetryAttempts = 3;          // Performance-focused retry logic
             concurrencyOptions.CommandTimeout = 180;          // 3-minute timeout for large operations
-            concurrencyOptions.EnablePerformanceOptimizations = true; // Additional speed boosts
         }));
 ```
 

EntityFrameworkCore.Sqlite.Concurrency/packages.lock.json

@@ -30,11 +30,11 @@
       },
       "Microsoft.Extensions.DependencyInjection": {
         "type": "Direct",
-        "requested": "[10.0.2, )",
-        "resolved": "10.0.2",
-        "contentHash": "J/Zmp6fY93JbaiZ11ckWvcyxMPjD6XVwIHQXBjryTBgn7O6O20HYg9uVLFcZlNfgH78MnreE/7EH+hjfzn7VyA==",
+        "requested": "[10.0.5, )",
+        "resolved": "10.0.5",
+        "contentHash": "v1SVsowG6YE1YnHVGmLWz57YTRCQRx9pH5ebIESXfm5isI9gA3QaMyg/oMTzPpXYZwSAVDzYItGJKfmV+pqXkQ==",
         "dependencies": {
-          "Microsoft.Extensions.DependencyInjection.Abstractions": "10.0.2"
+          "Microsoft.Extensions.DependencyInjection.Abstractions": "10.0.5"
         }
       },
       "Microsoft.Extensions.Logging.Abstractions": {
@@ -48,18 +48,22 @@
       },
       "Microsoft.SourceLink.GitHub": {
         "type": "Direct",
-        "requested": "[8.0.0, )",
-        "resolved": "8.0.0",
-        "contentHash": "G5q7OqtwIyGTkeIOAc3u2ZuV/kicQaec5EaRnc0pIeSnh9LUjj+PYQrJYBURvDt7twGl2PKA7nSN0kz1Zw5bnQ==",
+        "requested": "[10.0.201, )",
+        "resolved": "10.0.201",
+        "contentHash": "qxYAmO4ktzd9L+HMdnqWucxpu7bI9undPyACXOMqPyhaiMtbpbYL/n0ACyWIJlbyEJrXFwxiOaBOSasLtDvsCg==",
         "dependencies": {
-          "Microsoft.Build.Tasks.Git": "8.0.0",
-          "Microsoft.SourceLink.Common": "8.0.0"
+          "Microsoft.Build.Tasks.Git": "10.0.201",
+          "Microsoft.SourceLink.Common": "10.0.201",
+          "System.IO.Hashing": "10.0.5"
         }
       },
       "Microsoft.Build.Tasks.Git": {
         "type": "Transitive",
-        "resolved": "8.0.0",
-        "contentHash": "bZKfSIKJRXLTuSzLudMFte/8CempWjVamNUR5eHJizsy+iuOuO/k2gnh7W0dHJmYY0tBf+gUErfluCv5mySAOQ=="
+        "resolved": "10.0.201",
+        "contentHash": "DMYBnrFZvLnBKn14VavEuuIr31CY6YY2i2L9P8DorS/Qp6ifRR8ZPLdJCFLFfjikNq8DykbYyLd/RP6lSqHcWw==",
+        "dependencies": {
+          "System.IO.Hashing": "10.0.5"
+        }
       },
       "Microsoft.Data.Sqlite.Core": {
         "type": "Transitive",
@@ -145,8 +149,8 @@
       },
       "Microsoft.Extensions.DependencyInjection.Abstractions": {
         "type": "Transitive",
-        "resolved": "10.0.2",
-        "contentHash": "zOIurr59+kUf9vNcsUkCvKWZv+fPosUZXURZesYkJCvl0EzTc9F7maAO4Cd2WEV7ZJJ0AZrFQvuH6Npph9wdBw=="
+        "resolved": "10.0.5",
+        "contentHash": "iVMtq9eRvzyhx8949EGT0OCYJfXi737SbRVzWXE5GrOgGj5AaZ9eUuxA/BSUfmOMALKn/g8KfFaNQw0eiB3lyA=="
       },
       "Microsoft.Extensions.DependencyModel": {
         "type": "Transitive",
@@ -179,8 +183,8 @@
       },
       "Microsoft.SourceLink.Common": {
         "type": "Transitive",
-        "resolved": "8.0.0",
-        "contentHash": "dk9JPxTCIevS75HyEQ0E4OVAFhB2N+V9ShCXf8Q6FkUQZDkgLI12y679Nym1YqsiSysuQskT7Z+6nUf3yab6Vw=="
+        "resolved": "10.0.201",
+        "contentHash": "QbBYhkjgL6rCnBfDbzsAJLlsad13TlBHqYCFDIw56OO2g6ix+9RsmY8uxiQGdWwFKbZXaXyAA6jDCzFYVGCZDw=="
       },
       "SQLitePCLRaw.bundle_e_sqlite3": {
         "type": "Transitive",
@@ -208,6 +212,11 @@
         "dependencies": {
           "SQLitePCLRaw.core": "2.1.11"
         }
+      },
+      "System.IO.Hashing": {
+        "type": "Transitive",
+        "resolved": "10.0.5",
+        "contentHash": "8IBJWcCT9+e4Bmevm4T7+fQEiAh133KGiz4oiVTgJckd3Q76OFdR1falgn9lpz7+C4HJvogCDJeAa2QmvbeVtg=="
       }
     }
   }

EntityFrameworkCore.Sqlite.Concurrency/src/ExtensionMethods/SqliteConcurrencyServiceCollectionExtensions.cs

@@ -1,6 +1,7 @@
 using EntityFrameworkCore.Sqlite.Concurrency.Models;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
 
 namespace EntityFrameworkCore.Sqlite.Concurrency.ExtensionMethods;
 
@@ -18,6 +19,12 @@ public static class SqliteConcurrencyServiceCollectionExtensions
     /// <param name="configure">An optional action to configure concurrency options.</param>
     /// <param name="contextLifetime">The lifetime of the DbContext.</param>
     /// <returns>The service collection.</returns>
+    /// <remarks>
+    /// This overload automatically resolves <see cref="ILoggerFactory"/> from the DI
+    /// container and injects it into the concurrency options so that <c>SQLITE_BUSY*</c>
+    /// events and <c>BEGIN IMMEDIATE</c> upgrades are logged through the application's
+    /// normal logging pipeline.
+    /// </remarks>
     public static IServiceCollection AddConcurrentSqliteDbContext<TContext>(
         this IServiceCollection services,
         string connectionString,
@@ -27,9 +34,17 @@ public static IServiceCollection AddConcurrentSqliteDbContext<TContext>(
     {
         services.AddDbContext<TContext>((provider, options) =>
         {
-            options.UseSqliteWithConcurrency(connectionString, configure);
+            options.UseSqliteWithConcurrency(connectionString, o =>
+            {
+                configure?.Invoke(o);
+
+                // Inject the singleton ILoggerFactory so the interceptor can emit
+                // structured logs without the caller having to wire it up manually.
+                if (o.LoggerFactory is null)
+                    o.LoggerFactory = provider.GetService<ILoggerFactory>();
+            });
         }, contextLifetime);
-            
+
         return services;
     }
-}
+}