Shedlock Jdbc Provider

Shedlock Jdbc provider give the ability to apply distributed locks using a jdbc database.

Installation

If you want to use this extension, you need to add the io.quarkiverse.shedlock:quarkus-shedlock-provider-jdbc extension first to your build file with a jdbc datasource.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.shedlock</groupId>
    <artifactId>quarkus-shedlock-provider-jdbc</artifactId>
    <version>0.0.3</version>
</dependency>

and a jdbc datasource likes postgresql

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

Configuring

The quarkus.shedlock.defaults-lock-at-most-for application property is mandatory. The table name is defined to shedlock and can be overridden for the default datasource or another named jdbc datasource.

src/main/resources/application.properties
quarkus.shedlock.defaults-lock-at-most-for=PT30S
quarkus.datasource.db-kind=postgresql

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.shedlock.defaults-lock-at-most-for

how long the lock should be kept in case the executing node dies

Environment variable: QUARKUS_SHEDLOCK_DEFAULTS_LOCK_AT_MOST_FOR

string

required

quarkus.shedlock.defaults-lock-at-least-for

value which is much longer than normal execution time

Environment variable: QUARKUS_SHEDLOCK_DEFAULTS_LOCK_AT_LEAST_FOR

string

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

data sources configuration

Type

Default

quarkus.shedlock.jdbc.enable-table-creation

quarkus.shedlock.jdbc."datasource-name".enable-table-creation

enable table creation

Environment variable: QUARKUS_SHEDLOCK_JDBC_ENABLE_TABLE_CREATION

boolean

true

quarkus.shedlock.jdbc.table-name

quarkus.shedlock.jdbc."datasource-name".table-name

table name for datasource (default to shedLock)

Environment variable: QUARKUS_SHEDLOCK_JDBC_TABLE_NAME

string

shedLock

How to use it

To activate the lock on a method just annotate it with @JdbcSchedulerLock.

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkiverse.shedlock.providers.jdbc.runtime.JdbcSchedulerLock;

@ApplicationScoped
public class JdbcSchedulerLockService {
    @JdbcSchedulerLock
    public void runUsingLock() {
        // do something
    }
}

Multiple data sources

By default, the lock is bound to the default datasource.

The lock duration and dataSourceName can be defined on the annotation directly likes this way:

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkiverse.shedlock.common.runtime.LockDuration;
import io.quarkiverse.shedlock.providers.jdbc.runtime.JdbcSchedulerLock;

@ApplicationScoped
public class JdbcSchedulerLockServiceOptions {
    @JdbcSchedulerLock(dataSourceName = "master", lockDuration = @LockDuration(lockAtMostFor = "PT30S", lockAtLeastFor = "PT10S"))
    public void runUsingLock() {
        // do something
    }
}

Regarding this sample a master datasource must be defined has well.

src/main/resources/application.properties
quarkus.shedlock.defaults-lock-at-most-for=PT30S
quarkus.datasource.master.db-kind=postgresql

if the datasource does not exist the application will refuse to start and a message will be produce to help configuring the application.

Table storage

By default, the table is created using shedLock naming.

The name can be overridden by specifying another table name using this property table-name:

src/main/resources/application.properties
quarkus.shedlock.jdbc.table-name=myShedlockTable

or for a custom named source:

src/main/resources/application.properties
quarkus.shedlock.jdbc.customDataSource.table-name=myCustomDataSourceShedlockTable

However, following some enterprise organizations, it is not allowed to create a table due to missing admin right for security purpose.

It is possible to disable the table creation by setting enable-table-creation to false like this way:

src/main/resources/application.properties
quarkus.shedlock.jdbc.enable-table-creation=false

or for a custom named source:

src/main/resources/application.properties
quarkus.shedlock.jdbc.customDataSource.enable-table-creation=false

The table create script is defined this way:

CREATE TABLE IF NOT EXISTS shedlock (
  name VARCHAR(255),
  lock_until TIMESTAMP(3) NULL,
  locked_at TIMESTAMP(3) NULL,
  locked_by VARCHAR(255),
  PRIMARY KEY (name)
)