A Lock Handler of Your Own

A clustered ADO job store serializes its work with a lock so two nodes cannot acquire the same trigger. By default it is a row in QRTZ_LOCKS. Implement ILockHandler to use anything that grants one holder at a time: Redis, ZooKeeper, a cloud lease.

The contract

public interface ILockHandler
{
    bool RequiresConnection { get; }

    void Initialize(LockHandlerContext context) { }

    ValueTask<bool> AcquireLock(Guid requestorId, ConnectionAndTransactionHolder? conn,
        SchedulerLock lockKind, CancellationToken cancellationToken = default);

    ValueTask ReleaseLock(Guid requestorId, SchedulerLock lockKind,
        CancellationToken cancellationToken = default);
}

Initialize defaults to empty; skip it if your locks are not keyed by scheduler identity.

There are exactly two locks

SchedulerLock has two members, so no caller can invent a lock that protects nothing:

A firing whose job allows concurrent execution and whose trigger asks for nothing at the end (NoInstruction or DeleteTrigger) completes with no lock: it writes only its own rows. A handler sees a TriggerAccess acquisition for a completion only when it has to read what the lock keeps still:

Re-entry returns false

The most important rule: AcquireLock called again with the same requestorId and lockKind returns false and takes no second lock.

false is not an error. The store releases only a lock its own call took, so a nested operation re-enters without re-locking or releasing early. Returning true would let the inner operation release the outer one's lock.

That is for a handler that records whether a requestor holds a lock (the row-lock handlers, InProcessLockHandler). A handler that counts holds, like the shipped SqliteLockHandler, may return true, because the inner release only decrements. Either way: the caller releases exactly when it was told true, and never otherwise.

ReleaseLock from a non-owner should warn, not throw.

And false means nothing else

An acquire that did not take the lock throws: LockException when refused, OperationCanceledException when the token fired.

A handler that gives up leaves nothing behind: an abandoned wait must not consume a handover meant for the next waiter, and anything taken before the failure (a local gate in front of a remote lock) is released before the exception escapes.

Deriving from DbLockHandler

For a database row lock, DbLockHandler handles ownership, re-entry and prefix substitution, and leaves one method:

protected abstract ValueTask ExecuteSql(
    Guid requestorId,
    ConnectionAndTransactionHolder conn,
    string lockName,
    string expandedSql,
    string expandedInsertSql,
    CancellationToken cancellationToken = default);

Take the row lock and return normally on success, or throw; ownership is recorded after it returns. Both statements arrive prefix-expanded; the insert covers a missing row. If a failure ended the transaction (conn.Transaction.Connection is null — a deadlock victim, a write conflict on a memory-optimized row), throw rather than retry: SQL Server runs a retried statement outside any transaction, and the store retries the whole operation on a fresh one. Issue the statements through:

protected DbCommand PrepareCommand(ConnectionAndTransactionHolder conn, string commandText);
protected void AddCommandParameter(DbCommand command, string paramName, object? paramValue);

No overload takes a provider-specific type or size: lock statements bind two strings.

Shipped implementations, both public and unsealed, waiting on the TimeProvider so retries are testable:

• UpdateRowLockHandler — UPDATE {0}LOCKS SET LOCK_NAME = LOCK_NAME WHERE SCHED_NAME = @schedulerName AND LOCK_NAME = @lockName, retried RetryCount times (protected virtual, 2 by default) with RetryPeriod between attempts, inserting the row if none was updated. SqlServerMemoryOptimizedUpdateRowLockHandler adds the WITH (SNAPSHOT) hint and raises the retry count to 5; it is the handler for tables_sqlServerMOT.sql, whose memory-optimized QRTZ_LOCKS refuses the UPDLOCK,ROWLOCK hints the store's own SQL Server handler locks with.
• SelectForUpdateLockHandler — SELECT * FROM {0}LOCKS … FOR UPDATE, with PostgreSqlSelectForUpdateLockHandler as its dialect variant.

DbLockHandler fixes RequiresConnection to true, so conn is never null.

Implementing ILockHandler directly

For a lock outside the database, implement the interface with RequiresConnection false:

public sealed class LeaseLockHandler : ILockHandler
{
    private string schedulerName = "";

    public bool RequiresConnection => false;

    public void Initialize(LockHandlerContext context) => schedulerName = context.SchedulerName;

    public async ValueTask<bool> AcquireLock(
        Guid requestorId,
        ConnectionAndTransactionHolder? conn,
        SchedulerLock lockKind,
        CancellationToken cancellationToken = default)
    {
        // ... acquire, honouring the re-entry rule ...
        return true;
    }

    public ValueTask ReleaseLock(
        Guid requestorId,
        SchedulerLock lockKind,
        CancellationToken cancellationToken = default)
    {
        // ...
        return default;
    }
}

RequiresConnection = false lets the store open its connection only after the lock is taken, which is the point of an external lock.

LockHandlerContext

The job store calls Initialize once, after choosing the handler and before schema validation, on both construction paths (otherwise a container-supplied handler would query QRTZ_LOCKS with a null scheduler name):

• CommandTimeout bounds a node stuck on QRTZ_LOCKS behind a peer that stopped without releasing the row.
• LockWaitWarningThreshold: a DbLockHandler subclass logs warning 3716 once per slow acquisition, unasked; your own handler may ignore it or report its own way.
• The store times every acquisition on quartz.jobstore.lock.wait.duration; handlers owe nothing for it.

Registering it

builder.Services.AddQuartz(q =>
{
    q.UsePersistentStore(s =>
    {
        s.UseLockHandler<LeaseLockHandler>();
        s.UseSqlServer(connectionString);
        s.UseClustering();
    });
});

UseLockHandler(Func<IServiceProvider, ILockHandler>) is for a handler needing values rather than services; it registers under the scheduler's key, unlike a registration on Services. Quartz.Extensions.Redis uses this same public overload:

s.UseRedisLockHandler(o =>
{
    o.RedisConfiguration = "localhost:6379";
    o.KeyPrefix = "quartz:";
    o.LockTimeToLive = TimeSpan.FromSeconds(30);
});

The legacy key is quartz.jobStore.lockHandler.type. Its 3.x sub-keys .tablePrefix and .schedName (from ITablePrefixAware) are rejected as obsolete, since Initialize supplies both, and so is .schedulerName, the key the 4.x property name suggests.

A handler is always used

AdoJobStoreOptions.UseDbLocks picks which handler the store builds, not whether it locks:

A non-clustered scheduler locks in memory, which is correct for a single node.

The store logs the handler it ends up with at startup: event 3006 or 3007 for one it built, 3048 for one you registered. On SQL Server's memory-optimized schema, register UseLockHandler<SqlServerMemoryOptimizedUpdateRowLockHandler>(); the handler the store would build fails its first lock with The table option 'rowlock' is not supported with memory optimized tables.

Testing one

No scheduler needed:

• Call AcquireLock twice with the same requestorId; assert the second returns false.
• Acquire with an already-fired token; assert OperationCanceledException, not false. Then acquire from another requestorId and assert it succeeds, catching a lock left held by the abandoned attempt.
• Pass a FakeTimeProvider through LockHandlerContext and advance it to drive the retry loop.

See also

• Clustering — what the locks are protecting
• Redis — the shipped external lock handler
• A Driver Delegate for a New Database — the other ADO seam