ShedLock: a time-based lock for scheduled tasks that must not run twice
Distributed lock for your scheduled tasks
At a glance
- What is it?
- ShedLock is a Java library that keeps a @Scheduled method from running on several nodes at once by taking a lock in an external store. It is a lock, not a scheduler, and that distinction decides whether it fits your job.
- Who is it for?
- Adopt ShedLock when you already have @Scheduled methods, a shared store such as a JDBC database, and tasks that are safe to run repeatedly but not in parallel; the README's own example is a 15-minute cron job with lockAtMostFor and lockAtLeastFor both set to 14m. Do not adopt it for retries, one-off jobs, or anything that needs a queue, because a held lock causes the other nodes to skip rather than wait.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- lukas-krecan/ShedLock4,235 ★ · +14
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| lukas-krecan/ShedLock | 4.2k | 4.2k |
14 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The duplicate-execution problem ShedLock is built around
A Spring application with @Scheduled methods is easy to scale horizontally except for one detail: every instance runs the same cron. Three replicas mean three copies of the nightly cleanup, the invoice roll-up, the cache warm-up. Most of the time nothing breaks, which is exactly why the bug survives to production. Then the job touches a shared resource and the duplicates collide.
ShedLock targets that situation specifically. The README states its promise plainly: scheduled tasks are executed at most once at the same time. It is aimed at Java teams that already have scheduled methods and a store they can reach from every node, and who want a lock rather than a rewrite. The README is equally direct about who should look elsewhere. It says ShedLock is not and will never be a full-fledged scheduler, and points to db-scheduler and JobRunr for that need. The intended case is tasks that are not ready to be executed in parallel but can be safely executed repeatedly.
How the lock is taken, held and released
ShedLock has three parts: core, which holds the locking mechanism; an integration layer that wires it into your application through Spring AOP, Micronaut AOP or manual code; and a lock provider that stores the lock in an external process such as a SQL database, Mongo or Redis. Coordination never happens between nodes directly. Every node writes to the same external store, and that store is the arbiter.
The behaviour is documented step by step. Only methods annotated with @SchedulerLock are locked; every other scheduled task is ignored. Only one task with a given name can run at a time. When a lock is held, other tasks protected by the same lock are not blocked, they are simply skipped. The lock is released when the task finishes, unless lockAtLeastFor says otherwise. If the JVM dies mid-task, lockAtMostFor is the backstop: the lock is always released after that interval.
Two attributes carry most of the operational weight. lockAtMostFor is a safety net for a dead node, so the README says to set it much longer than normal execution time and warns that a task outrunning it makes behaviour unpredictable, with more than one process effectively holding the lock. lockAtLeastFor sets a floor on how long the lock is kept, mainly to stop short tasks from running on several nodes when clocks differ. The README's example joins both: a cron of 0 */15 * * * * with lockAtMostFor and lockAtLeastFor both at 14m, so the task runs at most once per fifteen minutes. Annotations accept Spring Expression Language, and the lock applies even when the method is called directly rather than through the scheduler. LockAssert.assertLocked() exists to fail loudly on a misconfiguration.
Installing ShedLock with Maven and locking a first task
The README's Spring path starts with one Maven dependency, net.javacrumbs.shedlock:shedlock-spring at version 7.10.1, and a configuration class that enables both Spring scheduling and scheduler locking. The defaultLockAtMostFor value set here becomes the fallback for every @SchedulerLock that does not declare its own.
<dependency>
<groupId>net.javacrumbs.shedlock</groupId>
<artifactId>shedlock-spring</artifactId>
<version>7.10.1</version>
</dependency>@Configuration
@EnableScheduling
@EnableSchedulerLock(defaultLockAtMostFor = "10m")
class MySpringConfiguration {
}Next, annotate the method you want protected. The name in @SchedulerLock is the lock identity, so two methods sharing a name will exclude each other.
import net.javacrumbs.shedlock.spring.annotation.SchedulerLock;
@Scheduled(cron = "0 */15 * * * *")
@SchedulerLock(name = "scheduledTaskName", lockAtMostFor = "14m", lockAtLeastFor = "14m")
public void scheduledTask() {
LockAssert.assertLocked();
}The third step is the LockProvider, and it is the step that decides your deployment. The README lists JdbcTemplate, R2DBC, jOOQ, Micronaut Data Jdbc, Mongo, DynamoDB 2, ZooKeeper via Curator, three Redis variants, Hazelcast, Couchbase, ElasticSearch, OpenSearch, CosmosDB, Cassandra, ArangoDB, Neo4j, Etcd, Apache Ignite, an in-memory provider, Memcached via Spymemcached, Datastore, Firestore, GCS, S3 and NATS Jetstream. The JdbcTemplate section begins by telling you to create the lock table first, with `name` as the primary key, and gives the schema; copy it rather than guessing column names. Until a provider is configured, the annotation has nothing to coordinate through.
Skipping instead of queueing, and the clock assumption
The most consequential design choice is what happens to the node that loses the race. It does not wait. Its execution is skipped. For an idempotent job that runs every few minutes, skipping is fine and keeps latency low. For a job that must run exactly once per day, skipping is a silent failure: the node that held the lock crashed at 23:59, and the next tick on another node has no memory of the missed run. ShedLock does not record that the work never happened.
The second constraint is time. The README states that locks are time-based and that ShedLock assumes clocks on the nodes are synchronized. Everything downstream inherits that assumption. If a node's clock drifts past lockAtMostFor, the lock can expire while the original task is still running, and two processes hold it. If clocks differ by more than the gap between a short task's start and finish, lockAtLeastFor is the documented mitigation. Neither attribute repairs a broken NTP setup.
A third limit is scope. The lock protects a method name, not a unit of work. Two different jobs that both mutate the same table are not serialized by ShedLock unless they share a lock name, and sharing a name means one of them is skipped, which is usually not what you want. ShedLock coordinates identical tasks across nodes; it does not coordinate different tasks against each other.
ShedLock against Quartz and db-scheduler
The obvious comparison is Quartz, which is a scheduler with a job store, misfire policies, clustering and trigger state. Quartz decides when work runs and remembers what it owes you; it can fire a missed execution according to a misfire instruction. ShedLock does none of that. It sits on top of the scheduling you already have and adds one guarantee: at most one instance of a named task at a time. If your requirement is "run this every night, and if the cluster was down, run it when it comes back", Quartz is the right shape and ShedLock is the wrong one, because ShedLock's losing node skips and forgets.
The README itself names db-scheduler and JobRunr as the projects to use when a distributed scheduler is what you need. Both keep state about executions, which is the capability ShedLock deliberately omits. The trade-off is honest: ShedLock is a small library that adds an annotation and a table, while a scheduler brings its own persistence model, its own operational surface and its own failure modes. Teams that already run Spring's @Scheduled and only need to stop duplicate execution get a much smaller change from ShedLock.
Maintenance, licence and what an upgrade touches
The repository is not archived, and the last push was on 2026-11-02, so the project is being worked on. The README's example pins shedlock-spring at 7.10.1, and a shedlock-bom directory exists at the top level, which is the mechanism for aligning provider versions with the core rather than pinning each artifact by hand. The repository has no published GitHub releases, so the upgrade surface has to be read from RELEASES.md in the repository.
The upgrade cost is dominated by your lock provider, not by the annotation. The annotation surface is small: name, lockAtMostFor, lockAtLeastFor, plus SpEL support. The providers are many and each one ships separately, so a version bump can move the core and a provider independently. The README has a compatibility matrix section; check it before changing a pom.
ShedLock is licensed under Apache-2.0, and the README carries the ASF2 badge. That is a permissive licence, but it governs the library only. Your lock table lives in your database, and the provider you pick may pull in a client with its own licence. Check that dependency tree yourself; this is not legal advice.
Editorial conclusion
Adopt ShedLock when you already have @Scheduled methods, a shared store such as a JDBC database, and tasks that are safe to run repeatedly but not in parallel; the README's own example is a 15-minute cron job with lockAtMostFor and lockAtLeastFor both set to 14m. Do not adopt it for retries, one-off jobs, or anything that needs a queue, because a held lock causes the other nodes to skip rather than wait. Before writing the annotation, verify that NTP keeps the nodes' clocks close, that the lock table exists with the expected columns, and that lockAtMostFor is much larger than the worst-case execution time of the task.
Frequently asked questions
What does ShedLock do?
It makes sure that scheduled tasks annotated with @SchedulerLock are executed at most once at the same time. A task running on one node holds a lock in an external store, and the same task on another node is skipped rather than queued.
How do you use ShedLock in a Spring Boot application?
Add the shedlock-spring dependency, put @EnableSchedulerLock with a defaultLockAtMostFor on a configuration class alongside @EnableScheduling, annotate the scheduled method with @SchedulerLock, and configure a LockProvider such as JdbcTemplate.
What is the ShedLock table?
It is the storage the JDBC lock provider uses to coordinate nodes. The README's JdbcTemplate section says to create the lock table first and gives the schema, noting that `name` has to be primary key.
Is ShedLock a distributed scheduler?
No. The README states that ShedLock is not and will never be a full-fledged scheduler, and recommends db-scheduler or JobRunr if that is what you need. ShedLock is only a lock.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/lukas-krecan-shedlock)Star history chart for your README
[](https://hysenlabs.com/projects/lukas-krecan-shedlock)Was this useful?