SqliteStorage.Hangfire 1.1.1

SqliteStorage.Hangfire

A lightweight, concurrency-safe SQLite storage for Hangfire, built on Microsoft.Data.Sqlite. No external database server required — point it at a file and go.

The package ships as SqliteStorage.Hangfire because the Hangfire.* ID prefix is reserved on nuget.org. The assembly and namespace carry the same name; the UseSqliteStorage() extension lives in the Hangfire namespace for discoverability.

GlobalConfiguration.Configuration.UseSqliteStorage("hangfire.db");

Why another SQLite storage?

The existing community SQLite storage keeps a shared, long-lived connection object that can be disposed while background timers (heartbeat, distributed lock cleanup, counters aggregator) still hold a reference to it. Under load — for example when the Hangfire.Console extension multiplies the number of storage writes per job — this use-after-dispose race surfaces as a stream of NullReferenceExceptions from HangfireDbContext, failed heartbeats and broken dashboard pages.

This storage is designed so that failure mode cannot exist:

• No shared connection. Every operation opens a short-lived connection from the Microsoft.Data.Sqlite pool and disposes it when done. There is no shared mutable state to race on.
• WAL mode + busy timeout. Readers never block the writer; write contention is absorbed by SQLite's busy handler plus a retry layer for the stragglers.
• Atomic job fetch. Dequeueing is a single UPDATE … RETURNING statement — no SELECT-then-UPDATE race between workers.
• Lease-based distributed locks. A PRIMARY KEY on the resource makes double-acquisition impossible; leases are extended by a heartbeat and expire on their own if the owner dies.
• Crash-safe processing. Fetched jobs send keep-alive updates; if the process dies, the invisibility timeout returns the job to the queue.
• Integer timestamps. All times are stored as Unix epoch milliseconds — no DateTime string parsing or timezone surprises.

Works with the dashboard, Hangfire.Console, recurring jobs, delayed jobs, retries, batches of parallel workers and multiple processes sharing the same database file.

Installation

dotnet add package SqliteStorage.Hangfire

Usage

ASP.NET Core

builder.Services.AddHangfire(configuration => configuration
    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
    .UseSimpleAssemblyNameTypeSerializer()
    .UseRecommendedSerializerSettings()
    .UseSqliteStorage("hangfire.db"));

builder.Services.AddHangfireServer();

You can pass either a plain file path or a full Microsoft.Data.Sqlite connection string:

.UseSqliteStorage("Data Source=C:\\data\\hangfire.db")

Options

.UseSqliteStorage("hangfire.db", new SqliteStorageOptions
{
    QueuePollInterval = TimeSpan.FromSeconds(5),        // cross-process polling fallback
    InvisibilityTimeout = TimeSpan.FromMinutes(30),     // re-queue window after a hard crash
    DistributedLockLifetime = TimeSpan.FromSeconds(30), // lock lease length
    JobExpirationCheckInterval = TimeSpan.FromMinutes(30),
    CountersAggregateInterval = TimeSpan.FromMinutes(5),
    BusyTimeout = TimeSpan.FromSeconds(15)
})

In-process enqueues wake waiting workers immediately; QueuePollInterval only matters for jobs enqueued by other processes sharing the database file.

When to use this (and when not to)

SQLite is a single-file, single-writer database. This storage is a great fit for:

• single-server applications, Windows services, desktop apps and IoT deployments;
• small-to-medium workloads where installing PostgreSQL/SQL Server/Redis is not justified;
• development and integration testing.

It is not a fit for multi-machine clusters — SQLite files should not be shared over network storage. If you outgrow a single machine, switch to one of the client-server storages; the Hangfire API stays the same.

Project layout

• src/SqliteStorage.Hangfire — the storage library (netstandard2.0 + net8.0)
• tests/SqliteStorage.Hangfire.Tests — unit tests plus an end-to-end test that runs a real BackgroundJobServer with Hangfire.Console under parallel load
• samples/WebSample — ASP.NET Core sample with the dashboard, console output, recurring and delayed jobs

License

MIT