additional best pratices

What was changed
SqliteConcurrencyServiceCollectionExtensions.cs

Added AddConcurrentSqliteDbContextFactory<TContext> — registers IDbContextFactory<TContext> with concurrency settings and auto-injected ILoggerFactory. Factory lifetime defaults to Singleton (appropriate since the factory holds no per-request state).
Updated AddConcurrentSqliteDbContext XML doc to point users toward the factory overload for concurrent workloads.
SqliteConnectionEnhancer.cs

ComputeOptimizedConnectionString now throws ArgumentException when Cache=Shared is detected, with a clear message explaining the WAL incompatibility and pointing to connection pooling as the correct alternative.
Added TryReleaseMigrationLockAsync — checks for a stale __EFMigrationsLock row and optionally deletes it. Accepts a release: false flag for diagnostic-only checks. Includes full XML docs covering when and why stale locks occur.
QUICKSTART.md

"Configure" section now shows both registration paths with guidance on when to use each.
"Real-World Scenario" corrected: the bad pattern now shows the EF thread-safety violation explicitly, and the good pattern uses IDbContextFactory + CreateDbContext() per task.
New "Multi-Instance Deployments and Migration Locks" section with TryReleaseMigrationLockAsync usage and network filesystem warning.
Best Practices list updated to 7 items covering factory pattern, Cache=Shared, migration lock, and single-host constraint.

Author: CornerstoneCode

EntityFrameworkCore.Sqlite.Concurrency/doc/QUICKSTART.md

@@ -34,29 +34,62 @@ public class BlogDbContext : DbContext
 }
 ```
 
-### 2. Configure with One Line of Code
+### 2. Configure in Program.cs
 
-In your `Program.cs` or startup configuration:
+#### Single-threaded / request-scoped use (ASP.NET Core controllers, Razor Pages, Blazor Server)
+
+One context is created per HTTP request through the DI scope. ASP.NET Core processes requests one thread at a time per scope, so sharing a context here is safe.
 
 ```csharp
-// Simple configuration
-builder.Services.AddDbContext<BlogDbContext>(options =>
-    options.UseSqliteWithConcurrency("Data Source=blog.db"));
+builder.Services.AddConcurrentSqliteDbContext<BlogDbContext>("Data Source=blog.db");
 ```
 
 Or with custom options:
 
 ```csharp
-builder.Services.AddDbContext<BlogDbContext>(options =>
-    options.UseSqliteWithConcurrency(
-        "Data Source=blog.db",
-        sqliteOptions =>
+builder.Services.AddConcurrentSqliteDbContext<BlogDbContext>(
+    "Data Source=blog.db",
+    options =>
+    {
+        options.BusyTimeout = TimeSpan.FromSeconds(30);
+        options.MaxRetryAttempts = 5;
+    });
+```
+
+#### Concurrent use (background workers, Task.WhenAll, channels, hosted services)
+
+A `DbContext` is **not thread-safe** — it must not be shared across concurrent operations. Use `IDbContextFactory<T>` instead. Each concurrent flow calls `CreateDbContext()` to get its own independent instance.
+
+```csharp
+builder.Services.AddConcurrentSqliteDbContextFactory<BlogDbContext>("Data Source=blog.db");
+```
+
+Then inject and use the factory:
+
+```csharp
+public class PostImportService
+{
+    private readonly IDbContextFactory<BlogDbContext> _factory;
+
+    public PostImportService(IDbContextFactory<BlogDbContext> factory)
+        => _factory = factory;
+
+    public async Task ImportPostsAsync(IEnumerable<Post> posts, CancellationToken ct)
+    {
+        var tasks = posts.Select(async post =>
         {
-            sqliteOptions.BusyTimeout = TimeSpan.FromSeconds(30);
-            sqliteOptions.MaxRetryAttempts = 5;
-        }));
+            await using var db = _factory.CreateDbContext();
+            db.Posts.Add(post);
+            await db.SaveChangesAsync(ct);
+        });
+
+        await Task.WhenAll(tasks); // ✅ Each task has its own context — no EF thread-safety violation
+    }
+}
 ```
 
+> **Note:** `Cache=Shared` in the connection string is incompatible with WAL mode and will throw an `ArgumentException` at startup. Use the default connection string format (`Data Source=blog.db`) — connection pooling is enabled automatically.
+
 ## Basic Usage Examples
 
 ### Writing Data (Automatically Thread-Safe)
@@ -167,45 +200,60 @@ public class ImportService
 Imagine a scenario where multiple background workers are processing tasks:
 
 ```csharp
-// WITHOUT ThreadSafeEFCore.SQLite - This would fail with "database is locked"
+// ❌ WRONG — sharing one DbContext across concurrent tasks
+//    EF Core will throw InvalidOperationException about concurrent usage,
+//    and SQLite returns "database is locked" for simultaneous writers.
 public class TaskProcessor
 {
+    private readonly AppDbContext _context; // shared — unsafe for concurrent use
+
     public async Task ProcessTasksConcurrently()
     {
         var tasks = Enumerable.Range(1, 10)
             .Select(i => ProcessSingleTaskAsync(i));
-            
-        await Task.WhenAll(tasks); // 💥 Database locked errors!
+
+        await Task.WhenAll(tasks); // 💥 EF thread-safety violation + database locked
+    }
+
+    private async Task ProcessSingleTaskAsync(int taskId)
+    {
+        _context.TaskResults.Add(new TaskResult { TaskId = taskId });
+        await _context.SaveChangesAsync(); // 💥 concurrent SaveChanges on one context
     }
 }
 
-// WITH ThreadSafeEFCore.SQLite - Just works!
+// ✅ CORRECT — one context per concurrent flow via IDbContextFactory
+//    Register with: builder.Services.AddConcurrentSqliteDbContextFactory<AppDbContext>("Data Source=app.db");
 public class TaskProcessor
 {
-    private readonly AppDbContext _context;
-    
+    private readonly IDbContextFactory<AppDbContext> _factory;
+
+    public TaskProcessor(IDbContextFactory<AppDbContext> factory)
+        => _factory = factory;
+
     public async Task ProcessTasksConcurrently()
     {
         var tasks = Enumerable.Range(1, 10)
             .Select(i => ProcessSingleTaskAsync(i));
-            
+
         await Task.WhenAll(tasks); // ✅ All tasks complete successfully
     }
-    
+
     private async Task ProcessSingleTaskAsync(int taskId)
     {
-        // Each task writes to the database
         var result = await PerformWorkAsync(taskId);
-        
-        // The package automatically queues these writes
-        _context.TaskResults.Add(new TaskResult
+
+        // Each concurrent flow creates and disposes its own context.
+        // ThreadSafeEFCore.SQLite serializes the actual writes at the SQLite level.
+        await using var db = _factory.CreateDbContext();
+        db.TaskResults.Add(new TaskResult
         {
             TaskId = taskId,
             Result = result,
             CompletedAt = DateTime.UtcNow
         });
-        
-        await _context.SaveChangesAsync();
+
+        await db.SaveChangesAsync(); // ✅ Thread-safe — no shared context, writes queued automatically
     }
 }
 ```
@@ -259,13 +307,40 @@ public async Task UpdatePostWithRetryAsync(int postId, string newContent)
 | `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. |
 
+## Multi-Instance Deployments and Migration Locks
+
+EF Core uses a `__EFMigrationsLock` table to serialize concurrent migrations. If a migration process crashes after acquiring the lock but before releasing it, subsequent calls to `Database.Migrate()` will block indefinitely.
+
+**Recommended approach:** run migrations once as a controlled startup step rather than calling `Database.Migrate()` from every app instance simultaneously.
+
+If a stale lock does occur, use the built-in helper to detect and clear it:
+
+```csharp
+// In your startup or migration runner:
+using var db = factory.CreateDbContext();
+var connection = db.Database.GetDbConnection();
+await connection.OpenAsync();
+
+var wasStale = await SqliteConnectionEnhancer.TryReleaseMigrationLockAsync(connection);
+if (wasStale)
+    logger.LogWarning("Stale EF migration lock found and released. Proceeding with migration.");
+
+await db.Database.MigrateAsync();
+```
+
+Pass `release: false` to check for a stale lock without removing it (useful for diagnostics).
+
+> **Network filesystem warning:** SQLite WAL mode requires all connections to be on the **same physical host**. Do not point the database at an NFS, SMB, or other network-mounted path. If your app runs across multiple machines or containers, use a client/server database instead.
+
 ## Best Practices
 
-1. **Use Dependency Injection** when possible for automatic context management
-2. **Keep write transactions short** - queue your data and write quickly
-3. **Use `BulkInsertOptimizedAsync`** for importing large amounts of data
-4. **Enable WAL mode** (already done by default) for better concurrency
-5. **Monitor performance** with the built-in diagnostics when needed
+1. **Use `IDbContextFactory<T>` for concurrent workloads** — inject the factory and call `CreateDbContext()` per concurrent operation; never share a single `DbContext` instance across concurrent tasks
+2. **Use `AddConcurrentSqliteDbContext<T>` for request-scoped workloads** — standard ASP.NET Core controllers and Razor Pages where one request = one thread = one context
+3. **Keep write transactions short** — acquire the write slot, write, commit; long-held write transactions block all other writers
+4. **Use `BulkInsertOptimizedAsync`** for importing large amounts of data
+5. **WAL mode is enabled automatically** — do not add `Cache=Shared` to the connection string; it is incompatible with WAL
+6. **Run migrations from a single process** — avoid calling `Database.Migrate()` concurrently from multiple instances; use `TryReleaseMigrationLockAsync` if a stale lock occurs
+7. **Stay on local disk** — WAL mode does not work over network filesystems (NFS, SMB); use a client/server database for multi-host deployments
 
 ## What Makes It Different
 

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

@@ -20,10 +20,20 @@ public static class SqliteConcurrencyServiceCollectionExtensions
     /// <param name="contextLifetime">The lifetime of the DbContext.</param>
     /// <returns>The service collection.</returns>
     /// <remarks>
+    /// <para>
     /// 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.
+    /// </para>
+    /// <para>
+    /// A <see cref="DbContext"/> instance is <b>not thread-safe</b>. For workloads that
+    /// create concurrent database operations (e.g. <c>Task.WhenAll</c>, background queues,
+    /// hosted services), use
+    /// <see cref="AddConcurrentSqliteDbContextFactory{TContext}(IServiceCollection, string, Action{SqliteConcurrencyOptions}?, ServiceLifetime)"/>
+    /// instead and inject <see cref="Microsoft.EntityFrameworkCore.IDbContextFactory{TContext}"/>
+    /// to create a separate context per concurrent operation.
+    /// </para>
     /// </remarks>
     public static IServiceCollection AddConcurrentSqliteDbContext<TContext>(
         this IServiceCollection services,
@@ -47,4 +57,74 @@ public static IServiceCollection AddConcurrentSqliteDbContext<TContext>(
 
         return services;
     }
+
+    /// <summary>
+    /// Adds an <see cref="Microsoft.EntityFrameworkCore.IDbContextFactory{TContext}"/>
+    /// configured with optimized SQLite concurrency and performance settings.
+    /// </summary>
+    /// <typeparam name="TContext">The type of the DbContext.</typeparam>
+    /// <param name="services">The service collection.</param>
+    /// <param name="connectionString">The SQLite connection string.</param>
+    /// <param name="configure">An optional action to configure concurrency options.</param>
+    /// <param name="factoryLifetime">
+    /// The lifetime of the factory. Defaults to <see cref="ServiceLifetime.Singleton"/>
+    /// because the factory itself holds no per-request state and is safe to share.
+    /// </param>
+    /// <returns>The service collection.</returns>
+    /// <remarks>
+    /// <para>
+    /// Prefer this overload whenever operations execute concurrently — for example inside
+    /// <c>Task.WhenAll</c>, <c>Channel&lt;T&gt;</c> consumers,
+    /// <c>IHostedService</c> workers, or
+    /// <c>Parallel.ForEachAsync</c>. Each concurrent flow should call
+    /// <see cref="Microsoft.EntityFrameworkCore.IDbContextFactory{TContext}.CreateDbContext"/>
+    /// to obtain its own independent context instance, which eliminates EF Core's
+    /// object-level thread-safety restriction entirely.
+    /// </para>
+    /// <para>
+    /// This overload automatically resolves <see cref="ILoggerFactory"/> from the DI
+    /// container so that <c>SQLITE_BUSY*</c> events and <c>BEGIN IMMEDIATE</c> upgrades
+    /// are logged through the application's normal logging pipeline.
+    /// </para>
+    /// <example>
+    /// <code>
+    /// // Registration
+    /// builder.Services.AddConcurrentSqliteDbContextFactory&lt;AppDbContext&gt;(
+    ///     "Data Source=app.db");
+    ///
+    /// // Concurrent use — each task gets its own context
+    /// public async Task ProcessAllAsync(IEnumerable&lt;int&gt; ids, CancellationToken ct)
+    /// {
+    ///     var tasks = ids.Select(async id =>
+    ///     {
+    ///         await using var db = _factory.CreateDbContext();
+    ///         // ... read and write with db
+    ///     });
+    ///     await Task.WhenAll(tasks);
+    /// }
+    /// </code>
+    /// </example>
+    /// </remarks>
+    public static IServiceCollection AddConcurrentSqliteDbContextFactory<TContext>(
+        this IServiceCollection services,
+        string connectionString,
+        Action<SqliteConcurrencyOptions>? configure = null,
+        ServiceLifetime factoryLifetime = ServiceLifetime.Singleton)
+        where TContext : DbContext
+    {
+        services.AddDbContextFactory<TContext>((provider, options) =>
+        {
+            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>();
+            });
+        }, factoryLifetime);
+
+        return services;
+    }
 }