Immediate.Jobs.LinqToDB

Immediate.Jobs.LinqToDB

LinqToDB storage for Immediate.Jobs, validated with PostgreSQL, SQLite, and SQL Server. The adapter supports durable jobs, recurring schedules, batches, continuations, execution history, multiple worker processes, and fair queues between tenant groups.

PostgreSQL storage requires PostgreSQL 15 or later. Definition reconciliation uses SQL MERGE; configure LinqToDB with a PostgreSQL 15+ dialect. The adapter assumes this requirement is met and does not validate the PostgreSQL version at runtime.

Installation

Install the core scheduler, this adapter, and the ADO.NET driver for your database:

dotnet add package Immediate.Jobs --prerelease
dotnet add package Immediate.Jobs.LinqToDB --prerelease
dotnet add package Npgsql

Use Microsoft.Data.Sqlite or Microsoft.Data.SqlClient instead of Npgsql when appropriate. This adapter deliberately does not carry a database driver.

Configuration

Define a DataConnection for the jobs database, register it with LinqToDB, and select that connection type when configuring job storage:

var dataOptions = new DataOptions().UsePostgreSQL(connectionString);
// new DataOptions().UseSQLite(connectionString);
// new DataOptions().UseSqlServer(connectionString);

await using (var connection = new JobsDataConnection(dataOptions))
{
	await connection.CreateImmediateJobsSchemaAsync(
		schema: "background", // must be null for SQLite
		CancellationToken.None);
}

builder.Services.AddLinqToDBContext<JobsDataConnection>(() => dataOptions);
builder.Services.AddMyAppHandlers();
builder.Services.AddMyAppJobs()
	.ConfigureStorage(storage => storage
		.UseLinqToDB<JobsDataConnection>(schema: "background")
		.UseSingleServer());

public sealed class JobsDataConnection(DataOptions options) : DataConnection(options);

AddMyAppJobs is the generated registration method for an assembly named MyApp.

SQLite uses NOCASE for job-name lookups, so case-insensitive matching is limited to ASCII letters. Invoice and invoice match; Résumé and RÉSUMÉ do not. Supply non-ASCII characters in their registered case.

CreateImmediateJobsSchemaAsync creates the current tables and indexes for a fresh database. It runs only when the application calls it; worker startup does not create the schema.

Named schemas are supported on PostgreSQL and SQL Server. SQLite has no server schemas and is normally embedded or file-backed.

Run one or several application instances

The example above uses UseSingleServer() and is valid only when exactly one application instance runs the Immediate.Jobs worker. Jobs are selected from an in-process queue, while every change is also written to SQL so pending work can be restored after a restart. Do not run two instances against the same database in this mode.

If the application runs multiple replicas, use UseDistributed() instead:

builder.Services.AddMyAppJobs()
	.ConfigureStorage(storage => storage
		.UseLinqToDB<JobsDataConnection>(schema: "background")
		.UseDistributed());

In this mode every replica claims due jobs directly from the database. A claim expires after the configured lease period (30 seconds by default), allowing another replica to claim and run the job again if the first process stops.

Fair queues

Supply a reusable tenant or customer ID when enqueueing work, then enable fair queues:

await scheduler.EnqueueAsync(payload, groupId: tenantId, cancellationToken);

builder.Services.AddMyAppJobs()
	.UseFairQueues()
	.ConfigureStorage(storage => storage
		.UseLinqToDB<JobsDataConnection>(schema: "background")
		.UseDistributed());

Fair queues rotate due jobs between tenant or customer groups so a large backlog from one group does not crowd out quieter groups. They are supported in both single-server and distributed SQL modes. See the queues and fairness documentation for the available settings.

More information

• Immediate.Jobs core package
• Storage-provider configuration
• GitHub repository

SQL Server storage requires SQL Server 2016 or later with database compatibility level 130 or higher. Tag-scoped definition reconciliation uses OPENJSON to compare the dedicated Tags JSON array column in the database. Other definition settings are relational columns.