How to Use ShedLock with Spring to Ensure Single-Instance Scheduled Tasks

Overview

Spring provides a simple API for scheduled tasks, but by default it cannot synchronize jobs across multiple application instances, causing each node to execute the job simultaneously. ShedLock is a Java library that ensures a scheduled task runs only once across all instances, serving as an alternative to Quartz.

Maven Dependency

<dependency>
    <groupId>net.javacrumbs.shedlock</groupId>
    <artifactId>shedlock-spring</artifactId>
    <version>2.2.0</version>
</dependency>

Configuration

ShedLock works in environments that share a database. It creates a table to store lock information and supports Mongo, Redis, Hazelcast, ZooKeeper, or any JDBC‑compatible store. The example below uses PostgreSQL.

<dependency>
    <groupId>net.javacrumbs.shedlock</groupId>
    <artifactId>shedlock-provider-jdbc-template</artifactId>
    <version>2.1.0</version>
</dependency>

Create the required table:

CREATE TABLE shedlock (
    name VARCHAR(64),
    lock_until TIMESTAMP(3) NULL,
    locked_at TIMESTAMP(3) NULL,
    locked_by VARCHAR(255),
    PRIMARY KEY (name)
);

Add the necessary Spring annotations:

@SpringBootApplication
@EnableScheduling
@EnableSchedulerLock(defaultLockAtMostFor = "PT30S")
public class SpringApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringApplication.class, args);
    }
}

The defaultLockAtMostFor parameter defines how long the lock is kept after the node finishes execution, using ISO‑8601 duration format.

Create Task

Define a scheduled method and protect it with @SchedulerLock:

@Component
class TaskScheduler {
    @Scheduled(cron = "*/15 * * * * *")
    @SchedulerLock(name = "TaskScheduler_scheduledTask",
        lockAtLeastForString = "PT5M",
        lockAtMostForString = "PT14M")
    public void scheduledTask() {
        // ... task logic ...
    }
}

The cron expression runs the method every 15 seconds. The name must be unique; typically ClassName_methodName suffices. lockAtLeastForString ensures the lock persists for at least 5 minutes, preventing the method from being triggered more frequently, while lockAtMostForString caps the lock duration at 14 minutes.

Summary

This article demonstrated how to use ShedLock with Spring to create and synchronize scheduled tasks, ensuring only one instance runs a given job at any time. All source code is available on GitHub.