EntityFrameworkCore.Sqlite.Concurrency
10.1.0
See the version list below for details.
dotnet add package EntityFrameworkCore.Sqlite.Concurrency --version 10.1.0
NuGet\Install-Package EntityFrameworkCore.Sqlite.Concurrency -Version 10.1.0
<PackageReference Include="EntityFrameworkCore.Sqlite.Concurrency" Version="10.1.0" />
<PackageVersion Include="EntityFrameworkCore.Sqlite.Concurrency" Version="10.1.0" />
<PackageReference Include="EntityFrameworkCore.Sqlite.Concurrency" />
paket add EntityFrameworkCore.Sqlite.Concurrency --version 10.1.0
#r "nuget: EntityFrameworkCore.Sqlite.Concurrency, 10.1.0"
#:package EntityFrameworkCore.Sqlite.Concurrency@10.1.0
#addin nuget:?package=EntityFrameworkCore.Sqlite.Concurrency&version=10.1.0
#tool nuget:?package=EntityFrameworkCore.Sqlite.Concurrency&version=10.1.0
EntityFrameworkCore.Sqlite.Concurrency
Getting this error?
Microsoft.Data.Sqlite.SqliteException: SQLite Error 5: 'database is locked'
This is the fix. One line change, no other modifications to your code:
// Before:
options.UseSqlite("Data Source=app.db");
// After — eliminates SQLITE_BUSY, serializes writes, enables WAL-mode parallel reads:
options.UseSqliteWithConcurrency("Data Source=app.db");
What Problems This Solves
| Error / Exception | Root Cause | Fix |
|---|---|---|
SQLite Error 5: 'database is locked' (SQLITE_BUSY) |
Multiple writers contending simultaneously | Channel-based write queue — one writer at a time, all others park efficiently in FIFO order |
SQLite Error 5: 'database is locked' (extended code 517, SQLITE_BUSY_SNAPSHOT) |
WAL read snapshot became stale mid-transaction | BEGIN IMMEDIATE upgrade + full operation restart on snapshot staleness |
InvalidOperationException: A second operation was started on this context instance |
DbContext shared across concurrent tasks |
IDbContextFactory<T> registration — one independent context per concurrent flow |
| Bulk inserts slow or running out of memory on large datasets | Linear SaveChanges(), unbounded ChangeTracker growth per batch |
BulkInsertOptimizedAsync — batched writes, ChangeTracker.Clear() per batch, WAL-optimized transactions |
See Troubleshooting SQLITE_BUSY errors for a deep-dive on each error code.
Why Choose This Package?
| Problem with Standard EF Core + SQLite | Solution |
|---|---|
SQLITE_BUSY / database is locked under concurrent writes |
Channel-based write queue serializes all writes — zero contention errors |
SQLITE_BUSY_SNAPSHOT mid-transaction |
Automatic BEGIN IMMEDIATE upgrade prevents stale read snapshots |
| Slow bulk inserts | BulkInsertOptimizedAsync — typically 5–10x faster via batching and PRAGMA tuning |
| Read contention during writes | WAL mode enabled automatically — reads never block behind writes |
| Manual retry logic | Built-in exponential backoff with full jitter for all SQLITE_BUSY* variants |
DbContext not thread-safe |
IDbContextFactory<T> wiring and ThreadSafeSqliteContext<T> base class |
Installation
# .NET CLI
dotnet add package EntityFrameworkCore.Sqlite.Concurrency
# Package Manager Console
Install-Package EntityFrameworkCore.Sqlite.Concurrency
Usage
Request-Scoped Apps (ASP.NET Core, Razor Pages, Blazor Server)
One DbContext per HTTP request. ASP.NET Core scopes handle thread safety at the request level.
// Program.cs
builder.Services.AddConcurrentSqliteDbContext<AppDbContext>("Data Source=app.db");
// Inject normally — concurrent writes across requests are serialized automatically
public class PostsController : ControllerBase
{
private readonly AppDbContext _db;
public PostsController(AppDbContext db) => _db = db;
[HttpPost]
public async Task<IActionResult> Create(Post post)
{
_db.Posts.Add(post);
await _db.SaveChangesAsync(); // thread-safe across concurrent requests
return Ok();
}
}
Concurrent Workloads (Background Services, Task.WhenAll, Channel Consumers)
DbContext is not thread-safe — never share one instance across concurrent tasks. Use IDbContextFactory<T> to give each concurrent flow its own independent context. Writes are still serialized at the SQLite level automatically.
// Program.cs
builder.Services.AddConcurrentSqliteDbContextFactory<AppDbContext>("Data Source=app.db");
// Background service — each task gets its own context
public class ReportService
{
private readonly IDbContextFactory<AppDbContext> _factory;
public ReportService(IDbContextFactory<AppDbContext> factory) => _factory = factory;
public async Task ProcessAllAsync(IEnumerable<int> ids, CancellationToken ct)
{
var tasks = ids.Select(async id =>
{
await using var db = _factory.CreateDbContext(); // one context per task
var item = await db.Items.FindAsync(id, ct);
item.ProcessedAt = DateTime.UtcNow;
await db.SaveChangesAsync(ct); // writes serialized — no "database is locked"
});
await Task.WhenAll(tasks); // all complete without SQLITE_BUSY
}
}
See Concurrent EF Core patterns for the full pattern guide.
High-Volume Batch Jobs
// 10,000 records — batched in chunks of 1,000, ChangeTracker cleared between batches
await context.BulkInsertOptimizedAsync(records);
// Or with explicit retry control
await context.ExecuteWithRetryAsync(async ctx =>
{
foreach (var record in records)
ctx.Records.Add(record);
}, maxRetries: 5);
Configuration
builder.Services.AddConcurrentSqliteDbContext<AppDbContext>(
"Data Source=app.db",
options =>
{
options.BusyTimeout = TimeSpan.FromSeconds(30);
options.MaxRetryAttempts = 3;
options.CommandTimeout = 300;
options.WalAutoCheckpoint = 1000;
options.SynchronousMode = SqliteSynchronousMode.Normal;
options.UpgradeTransactionsToImmediate = true;
options.WriteQueueCapacity = null; // null = unbounded
});
| Option | Default | Description |
|---|---|---|
BusyTimeout |
30 s | PRAGMA busy_timeout — SQLite retries lock acquisition internally before surfacing SQLITE_BUSY. |
MaxRetryAttempts |
3 | Application-level retries after SQLITE_BUSY*, with exponential backoff and full jitter. |
CommandTimeout |
300 s | EF Core SQL command timeout. |
WalAutoCheckpoint |
1000 pages | PRAGMA wal_autocheckpoint — triggers passive checkpoint after this many WAL frames (~4 MB). Set to 0 to disable. |
SynchronousMode |
Normal |
PRAGMA synchronous — durability vs. write-speed. Normal is recommended for WAL mode. |
UpgradeTransactionsToImmediate |
true |
Rewrites BEGIN to BEGIN IMMEDIATE to prevent SQLITE_BUSY_SNAPSHOT mid-transaction. |
WriteQueueCapacity |
null |
Maximum pending writes before callers block. null = accept without limit. Set a value for back-pressure on high-volume producers. |
Note:
Cache=Sharedin the connection string is incompatible with WAL mode and will throwArgumentExceptionat startup. Connection pooling (Pooling=true) is enabled automatically and is the correct alternative.
FAQ
Q: What is the Channel-based write queue?
A: Since v10.1.0, write serialization uses Channel<IWriteRequest> with a single background writer instead of SemaphoreSlim. Under high concurrency, SemaphoreSlim wakes all N waiters simultaneously when the lock releases — N-1 immediately re-sleep (CPU churn, unfair scheduling, thundering herd). A Channel<T> parks callers in FIFO order and drains them one at a time. No API change is needed — existing code gets the benefit automatically.
Q: What does SQLITE_BUSY_SNAPSHOT (error code 517) mean?
A: This is a specific variant of SQLITE_BUSY (extended code 5 | (2 << 8) = 517) that fires when a connection's WAL read snapshot became stale after another writer committed mid-transaction. Retrying the same statement produces the same error — the only correct fix is to roll back and restart the entire operation so all reads are re-queried against the current snapshot. This package implements that correctly.
Q: Does this work with netstandard 2.0?
A: The connection layer (SqliteConnectionEnhancer, SqliteWriteQueue, SqliteConcurrencyOptions) targets netstandard2.0. EF Core-dependent APIs (UseSqliteWithConcurrency, ThreadSafeSqliteContext<T>, AddConcurrentSqliteDbContext<T>) require net10.0 because EF Core 10 requires it.
Q: How much overhead does write serialization add?
A: Sub-millisecond. Enqueueing to a Channel and awaiting a TaskCompletionSource adds microseconds per write — negligible compared to actual SQLite I/O. WAL-mode PRAGMA tuning typically more than compensates on read-heavy workloads.
Q: Does this work with my existing DbContext, models, and LINQ queries?
A: Yes. Change UseSqlite to UseSqliteWithConcurrency. Everything else compiles and runs unchanged.
Q: Does this work on network filesystems? A: No. 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. Use a client/server database (PostgreSQL, SQL Server) for multi-host deployments.
Q: Why do I need IDbContextFactory for concurrent workloads?
A: EF Core's DbContext is not thread-safe by design — it tracks entity state per instance and cannot be shared across concurrent tasks. IDbContextFactory<T> creates an independent context per concurrent flow. Writes from all contexts are serialized at the SQLite level by the write queue.
Benchmark Results
Measured with BenchmarkDotNet v0.14.0 on .NET 10.0.2 / Windows 11 / Intel i7-13700K:
| Benchmark | Standard EF Core | This Package | Ratio |
|---|---|---|---|
BulkInsertOptimizedAsync — 1,000 entities |
4,500 ms | 28 ms | ~161x faster |
Concurrent writes (50 tasks, Task.WhenAll) |
throws SQLITE_BUSY |
completes cleanly | ∞ |
Bulk insert: baseline calls
SaveChangesAsync()per entity (1,000 individual transactions); package uses a single batched write. Full numbers and reproduce command:docs/performance-guide.md.Reproduce:
dotnet run -c Release --project EFCore.Sqlite.Concurrency.Benchmarks -- --job short
Documentation
- Troubleshooting SQLITE_BUSY errors
- Concurrent EF Core patterns
- Performance and WAL tuning guide
- Migration guide — from plain UseSqlite
- v10.1.0 Release Notes
System Requirements
- .NET 10.0+ (for EF Core APIs) or netstandard 2.0+ (for connection layer only)
- Entity Framework Core 10.0+
- Microsoft.Data.Sqlite 10.0+
- SQLite 3.35.0+ (WAL2 and
SQLITE_BUSY_SNAPSHOTrequire 3.37.0+)
License
MIT License — free for commercial use, open-source projects, and enterprise applications.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.Data.Sqlite (>= 7.0.20)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.3)
- System.Threading.Channels (>= 8.0.0)
-
net10.0
- Microsoft.Data.Sqlite (>= 10.0.9)
- Microsoft.EntityFrameworkCore.Sqlite (>= 10.0.9)
- Microsoft.Extensions.DependencyInjection (>= 10.0.9)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.9)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
v10.1.0 — Channel-Based Write Queue, netstandard 2.0, Bug Fixes
NEW FEATURES
• Channel-based write queue: replaces SemaphoreSlim with Channel<IWriteRequest> + single
background writer. SemaphoreSlim wakes all N waiters simultaneously (thundering herd);
Channel parks callers in FIFO order — no wakeup storm, fairer scheduling, lower CPU.
Zero API change — existing call sites benefit automatically.
• WriteQueueCapacity option: new int? on SqliteConcurrencyOptions (null = unbounded).
Set a value to create a bounded channel with back-pressure (BoundedChannelFullMode.Wait).
• netstandard 2.0 TFM: SqliteConnectionEnhancer, SqliteWriteQueue, SqliteConcurrencyOptions
now available on any runtime supporting netstandard 2.0. EF Core APIs remain net10.0-only.
BUG FIXES
• ThreadSafeSqliteContext always used default options: ExecuteWriteAsync was constructing
new SqliteConcurrencyOptions() instead of reading registered interceptor options. Fixed
via TryGetInterceptor lookup.
• BulkInsertSafeAsync O(n²) + unbounded ChangeTracker growth: Skip/Take loop replaced with
Chunk(1000); ChangeTracker.Clear() added after each batch SaveChangesAsync.
NO BREAKING CHANGES — all existing call sites compile and behave correctly without modification.