Awesome

db-scheduler

Task-scheduler for Java that was inspired by the need for a clustered java.util.concurrent.ScheduledExecutorService simpler than Quartz.

As such, also appreciated by users (cbarbosa2, rafaelhofmann, BukhariH):

Your lib rocks! I'm so glad I got rid of Quartz and replaced it by yours which is way easier to handle!

cbarbosa2

See also why not Quartz?

Features

• Cluster-friendly. Guarantees execution by single scheduler instance.
• Persistent tasks. Requires a single database-table for persistence.
• Embeddable. Built to be embedded in existing applications.
• High throughput. Tested to handle 2k - 10k executions / second. Link.
• Simple.
• Minimal dependencies. (slf4j)

Table of contents

• Getting started
• Who uses db-scheduler?
• Examples
• Configuration
• Third-party extensions
• Spring Boot usage
• Interacting with scheduled executions using the SchedulerClient
• How it works
• Performance
• Versions / upgrading
• FAQ

Getting started

1. Add maven dependency

<dependency>
    <groupId>com.github.kagkarlsson</groupId>
    <artifactId>db-scheduler</artifactId>
    <version>15.0.0</version>
</dependency>

2. Create the scheduled_tasks table in your database-schema. See table definition for postgresql, oracle, mssql or mysql.

3. Instantiate and start the scheduler, which then will start any defined recurring tasks.

RecurringTask<Void> hourlyTask = Tasks.recurring("my-hourly-task", FixedDelay.ofHours(1))
        .execute((inst, ctx) -> {
            System.out.println("Executed!");
        });

final Scheduler scheduler = Scheduler
        .create(dataSource)
        .startTasks(hourlyTask)
        .threads(5)
        .build();

// hourlyTask is automatically scheduled on startup if not already started (i.e. exists in the db)
scheduler.start();

For more examples, continue reading. For details on the inner workings, see How it works. If you have a Spring Boot application, have a look at Spring Boot Usage.

Who uses db-scheduler?

List of organizations known to be running db-scheduler in production:

Feel free to open a PR to add your organization to the list.

Examples

See also runnable examples.

Recurring task (static)

Define a recurring task and schedule the task's first execution on start-up using the startTasks builder-method. Upon completion, the task will be re-scheduled according to the defined schedule (see pre-defined schedule-types).

RecurringTask<Void> hourlyTask = Tasks.recurring("my-hourly-task", FixedDelay.ofHours(1))
        .execute((inst, ctx) -> {
            System.out.println("Executed!");
        });

final Scheduler scheduler = Scheduler
        .create(dataSource)
        .startTasks(hourlyTask)
        .registerShutdownHook()
        .build();

// hourlyTask is automatically scheduled on startup if not already started (i.e. exists in the db)
scheduler.start();

For recurring tasks with multiple instances and schedules, see example RecurringTaskWithPersistentScheduleMain.java.

One-time task

An instance of a one-time task has a single execution-time some time in the future (i.e. non-recurring). The instance-id must be unique within this task, and may be used to encode some metadata (e.g. an id). For more complex state, custom serializable java objects are supported (as used in the example).

Define a one-time task and start the scheduler:

TaskDescriptor<MyTaskData> MY_TASK =
    TaskDescriptor.of("my-onetime-task", MyTaskData.class);

OneTimeTask<MyTaskData> myTaskImplementation =
    Tasks.oneTime(MY_TASK)
        .execute((inst, ctx) -> {
              System.out.println("Executed! Custom data, Id: " + inst.getData().id);
        });

final Scheduler scheduler = Scheduler
    .create(dataSource, myTaskImplementation)
    .registerShutdownHook()
    .build();

scheduler.start();

... and then at some point (at runtime), an execution is scheduled using the SchedulerClient:

// Schedule the task for execution a certain time in the future and optionally provide custom data for the execution
scheduler.schedule(
    MY_TASK
        .instanceWithId("1045")
        .data(new MyTaskData(1001L))
        .scheduledTo(Instant.now().plusSeconds(5)));

More examples

Plain Java

Spring Boot

Configuration

Scheduler configuration

The scheduler is created using the Scheduler.create(...) builder. The builder has sensible defaults, but the following options are configurable.

Consider tuning

:gear: .threads(int)<br/> Number of threads. Default 10.

:gear: .pollingInterval(Duration)<br/> How often the scheduler checks the database for due executions. Default 10s.<br/>

:gear: .alwaysPersistTimestampInUTC()<br/> The Scheduler assumes that columns for persisting timestamps persist Instants, not LocalDateTimes, i.e. somehow tie the timestamp to a zone. However, some databases have limited support for such types (which has no zone information) or other quirks, making "always store in UTC" a better alternative. For such cases, use this setting to always store Instants in UTC. PostgreSQL and Oracle-schemas is tested to preserve zone-information. MySQL and MariaDB-schemas does not and should use this setting. NB: For backwards compatibility, the default behavior for "unknown" databases is to assume the database preserves time zone. For "known" databases, see the class AutodetectJdbcCustomization.

:gear: .enableImmediateExecution()<br/> If this is enabled, the scheduler will attempt to hint to the local Scheduler that there are executions to be executed after they are scheduled to run now(), or a time in the past. NB: If the call to schedule(..)/reschedule(..) occur from within a transaction, the scheduler might attempt to run it before the update is visible (transaction has not committed). It is still persisted though, so even if it is a miss, it will run before the next polling-interval. You may also programmatically trigger an early check for due executions using the Scheduler-method scheduler.triggerCheckForDueExecutions()). Default false.

:gear: .registerShutdownHook()<br/> Registers a shutdown-hook that will call Scheduler.stop() on shutdown. Stop should always be called for a graceful shutdown and to avoid dead executions.

:gear: .shutdownMaxWait(Duration)<br/> How long the scheduler will wait before interrupting executor-service threads. If you find yourself using this, consider if it is possible to instead regularly check executionContext.getSchedulerState().isShuttingDown() in the ExecutionHandler and abort long-running task. Default 30min.

:gear: .enablePriority()<br/> It is possible to define a priority for executions which determines the order in which due executions are fetched from the database. An execution with a higher value for priority will run before an execution with a lower value (technically, the ordering will be order by priority desc, execution_time asc). Consider using priorities in the range 0-32000 as the field is defined as a SMALLINT. If you need a larger value, modify the schema. For now, this feature is opt-in, and column priority is only needed by users who choose to enable priority via this config setting.

Set the priority per instance using the TaskInstance.Builder:

    scheduler.schedule(
        MY_TASK
            .instance("1")
            .priority(100)
            .scheduledTo(Instant.now()));

Note:

• When enabling this feature, make sure you have the new necessary indexes defined. If you regularly have a state with large amounts of executions both due and future, it might be beneficial to add an index on (execution_time asc, priority desc) (replacing the old execution_time asc).
• This feature is not recommended for users of MySQL and MariaDB below version 8.x, as they do not support descending indexes.
• Value null for priority may be interpreted differently depending on database (low or high).

Polling strategy

If you are running >1000 executions/s you might want to use the lock-and-fetch polling-strategy for lower overhead and higher throughput (read more). If not, the default fetch-and-lock-on-execute will be fine.

:gear: .pollUsingFetchAndLockOnExecute(double, double)<br/> Use default polling strategy fetch-and-lock-on-execute.<br/> If the last fetch from the database was a full batch (executionsPerBatchFractionOfThreads), a new fetch will be triggered when the number of executions left are less than or equal to lowerLimitFractionOfThreads * nr-of-threads. Fetched executions are not locked/picked, so the scheduler will compete with other instances for the lock when it is executed. Supported by all databases. <br/>Defaults: 0,5, 3.0

:gear: .pollUsingLockAndFetch(double, double)<br/> Use polling strategy lock-and-fetch which uses select for update .. skip locked for less overhead.<br/> If the last fetch from the database was a full batch, a new fetch will be triggered when the number of executions left are less than or equal to lowerLimitFractionOfThreads * nr-of-threads. The number of executions fetched each time is equal to (upperLimitFractionOfThreads * nr-of-threads) - nr-executions-left. Fetched executions are already locked/picked for this scheduler-instance thus saving one UPDATE statement. <br/>For normal usage, set to for example 0.5, 1.0. <br/>For high throughput (i.e. keep threads busy), set to for example 1.0, 4.0. Currently hearbeats are not updated for picked executions in queue (applicable if upperLimitFractionOfThreads > 1.0). If they stay there for more than 4 * heartbeat-interval (default 20m), not starting execution, they will be detected as dead and likely be unlocked again (determined by DeadExecutionHandler). Currently supported by postgres. sql-server also supports this, but testing has shown this is prone to deadlocks and thus not recommended until understood/resolved.

Less commonly tuned

:gear: .heartbeatInterval(Duration)<br/> How often to update the heartbeat timestamp for running executions. Default 5m.

:gear: .missedHeartbeatsLimit(int)<br/> How many heartbeats may be missed before the execution is considered dead. Default 6.

:gear: .addExecutionInterceptor(ExecutionInterceptor)<br/> Adds an ExecutionInterceptor which may inject logic around executions. For Spring Boot, simply register a Bean of type ExecutionInterceptor.

:gear: .addSchedulerListener(SchedulerListener)<br/> Adds an SchedulerListener which will receive Scheduler- and Execution-related events. For Spring Boot, simply register a Bean of type SchedulerListener.

:gear: .schedulerName(SchedulerName)<br/> Name of this scheduler-instance. The name is stored in the database when an execution is picked by a scheduler. Default <hostname>.

:gear: .tableName(String)<br/> Name of the table used to track task-executions. Change name in the table definitions accordingly when creating the table. Default scheduled_tasks.

:gear: .serializer(Serializer)<br/> Serializer implementation to use when serializing task data. Default to using standard Java serialization, but db-scheduler also bundles a GsonSerializer and JacksonSerializer. See examples for a KotlinSerializer. See also additional documentation under Serializers.

:gear: .executorService(ExecutorService)<br/> If specified, use this externally managed executor service to run executions. Ideally the number of threads it will use should still be supplied (for scheduler polling optimizations). Default null.

:gear: .deleteUnresolvedAfter(Duration)<br/> The time after which executions with unknown tasks are automatically deleted. These can typically be old recurring tasks that are not in use anymore. This is non-zero to prevent accidental removal of tasks through a configuration error (missing known-tasks) and problems during rolling upgrades. Default 14d.

:gear: .jdbcCustomization(JdbcCustomization)<br/> db-scheduler tries to auto-detect the database used to see if any jdbc-interactions need to be customized. This method is an escape-hatch to allow for setting JdbcCustomizations explicitly. Default auto-detect.

:gear: .commitWhenAutocommitDisabled(boolean)<br/> By default no commit is issued on DataSource Connections. If auto-commit is disabled, it is assumed that transactions are handled by an external transaction-manager. Set this property to true to override this behavior and have the Scheduler always issue commits. Default false.

:gear: .failureLogging(Level, boolean)<br/> Configures how to log task failures, i.e. Throwables thrown from a task execution handler. Use log level OFF to disable this kind of logging completely. Default WARN, true.

Task configuration

Tasks are created using one of the builder-classes in Tasks. The builders have sensible defaults, but the following options can be overridden.

Schedules

The library contains a number of Schedule-implementations for recurring tasks. See class Schedules.

Another option to configure schedules is reading string patterns with Schedules.parse(String).

The currently available patterns are:

More details on the time zone formats can be found here.

Disabled schedules

A Schedule can be marked as disabled. The scheduler will not schedule the initial executions for tasks with a disabled schedule, and it will remove any existing executions for that task.

Serializers

A task-instance may have some associated data in the field task_data. The scheduler uses a Serializer to read and write this data to the database. By default, standard Java serialization is used, but a number of options is provided:

• GsonSerializer
• JacksonSerializer
• KotlinSerializer

For Java serialization it is recommended to specify a serialVersionUID to be able to evolve the class representing the data. If not specified, and the class changes, deserialization will likely fail with a InvalidClassException. Should this happen, find and set the current auto-generated serialVersionUID explicitly. It will then be possible to do non-breaking changes to the class.

If you need to migrate from Java serialization to a GsonSerializer, configure the scheduler to use a SerializerWithFallbackDeserializers:

.serializer(new SerializerWithFallbackDeserializers(new GsonSerializer(), new JavaSerializer()))

Third-party extensions

• bekk/db-scheduler-ui is admin-ui for the scheduler. It shows scheduled executions and supplies simple admin-operations such as "rerun failed execution now" and "delete execution".
• rocketbase-io/db-scheduler-log is an extension providing a history of executions, including failures and exceptions.
• piemjean/db-scheduler-mongo is an extension for running db-scheduler with a MongoDB database.
• osoykan/db-scheduler-additions adds MongoDB & Couchbase support on top of Kotlin and Coroutines. It also provides a Ktor plugin for db-scheduler-ui.

Spring Boot usage

For Spring Boot applications, there is a starter db-scheduler-spring-boot-starter making the scheduler-wiring very simple. (See full example project).

Prerequisites

• An existing Spring Boot application
• A working DataSource with schema initialized. (In the example HSQLDB is used and schema is automatically applied.)

Getting started

1. Add the following Maven dependency

   <dependency>
       <groupId>com.github.kagkarlsson</groupId>
       <artifactId>db-scheduler-spring-boot-starter</artifactId>
       <version>15.0.0</version>
   </dependency>
   

   NOTE: This includes the db-scheduler dependency itself.
2. In your configuration, expose your Task's as Spring beans. If they are recurring, they will automatically be picked up and started.
3. If you want to expose Scheduler state into actuator health information you need to enable db-scheduler health indicator. Spring Health Information.
4. Run the app.

Configuration options

Configuration is mainly done via application.properties. Configuration of scheduler-name, serializer and executor-service is done by adding a bean of type DbSchedulerCustomizer to your Spring context.

# application.properties example showing default values

db-scheduler.enabled=true
db-scheduler.heartbeat-interval=5m
db-scheduler.polling-interval=10s
db-scheduler.polling-limit=
db-scheduler.table-name=scheduled_tasks
db-scheduler.immediate-execution-enabled=false
db-scheduler.scheduler-name=
db-scheduler.threads=10
db-scheduler.priority-enabled=false

# Ignored if a custom DbSchedulerStarter bean is defined
db-scheduler.delay-startup-until-context-ready=false

db-scheduler.polling-strategy=fetch
db-scheduler.polling-strategy-lower-limit-fraction-of-threads=0.5
db-scheduler.polling-strategy-upper-limit-fraction-of-threads=3.0

db-scheduler.shutdown-max-wait=30m

Interacting with scheduled executions using the SchedulerClient

It is possible to use the Scheduler to interact with the persisted future executions. For situations where a full Scheduler-instance is not needed, a simpler SchedulerClient can be created using its builder:

SchedulerClient.Builder.create(dataSource, taskDefinitions).build()

It will allow for operations such as:

• List scheduled executions
• Reschedule a specific execution
• Remove an old executions that have been retrying for too long
• ...

How it works

A single database table is used to track future task-executions. When a task-execution is due, db-scheduler picks it and executes it. When the execution is done, the Task is consulted to see what should be done. For example, a RecurringTask is typically rescheduled in the future based on its Schedule.

The scheduler uses optimistic locking or select-for-update (depending on polling strategy) to guarantee that one and only one scheduler-instance gets to pick and run a task-execution.

Recurring tasks

The term recurring task is used for tasks that should be run regularly, according to some schedule.

When the execution of a recurring task has finished, a Schedule is consulted to determine what the next time for execution should be, and a future task-execution is created for that time (i.e. it is rescheduled). The time chosen will be the nearest time according to the Schedule, but still in the future.

There are two types of recurring tasks, the regular static recurring task, where the Schedule is defined statically in the code, and the dynamic recurring tasks, where the Schedule is defined at runtime and persisted in the database (still requiring only a single table).

Static recurring task

The static recurring task is the most common one and suitable for regular background jobs since the scheduler automatically schedules an instance of the task if it is not present and also updates the next execution-time if the Schedule is updated.

To create the initial execution for a static recurring task, the scheduler has a method startTasks(...) that takes a list of tasks that should be "started" if they do not already have an existing execution. The initial execution-time is determined by the Schedule. If the task already has a future execution (i.e. has been started at least once before), but an updated Schedule now indicates another execution-time, the existing execution will be rescheduled to the new execution-time (with the exception of non-deterministic schedules such as FixedDelay where new execution-time is further into the future).

Create using Tasks.recurring(..).

Dynamic recurring task

The dynamic recurring task is a later addition to db-scheduler and was added to support use-cases where there is need for multiple instances of the same type of task (i.e. same implementation) with different schedules. The Schedule is persisted in the task_data alongside any regular data. Unlike the static recurring task, the dynamic one will not automatically schedule instances of the task. It is up to the user to create instances and update the schedule for existing ones if necessary (using the SchedulerClient interface). See the example RecurringTaskWithPersistentScheduleMain.java for more details.

Create using Tasks.recurringWithPersistentSchedule(..).

One-time tasks

The term one-time task is used for tasks that have a single execution-time. In addition to encode data into the instanceIdof a task-execution, it is possible to store arbitrary binary data in a separate field for use at execution-time. By default, Java serialization is used to marshal/unmarshal the data.

Create using Tasks.oneTime(..).

Custom tasks

For tasks not fitting the above categories, it is possible to fully customize the behavior of the tasks using Tasks.custom(..).

Use-cases might be:

• Tasks that should be either rescheduled or removed based on output from the actual execution
• ..

Dead executions

During execution, the scheduler regularly updates a heartbeat-time for the task-execution. If an execution is marked as executing, but is not receiving updates to the heartbeat-time, it will be considered a dead execution after time X. That may for example happen if the JVM running the scheduler suddenly exits.

When a dead execution is found, the Taskis consulted to see what should be done. A dead RecurringTask is typically rescheduled to now().

Performance

While db-scheduler initially was targeted at low-to-medium throughput use-cases, it handles high-throughput use-cases (1000+ executions/second) quite well due to the fact that its data-model is very simple, consisting of a single table of executions. To understand how it will perform, it is useful to consider the SQL statements it runs per batch of executions.

Polling strategy fetch-and-lock-on-execute

The original and default polling strategy, fetch-and-lock-on-execute, will do the following:

1. select a batch of due executions
2. For every execution, on execute, try to update the execution to picked=true for this scheduler-instance. May miss due to competing schedulers.
3. If execution was picked, when execution is done, update or delete the record according to handlers.

In sum per batch: 1 select, 2 * batch-size updates (excluding misses)

Polling strategy lock-and-fetch

In v10, a new polling strategy (lock-and-fetch) was added. It utilizes the fact that most databases now have support for SKIP LOCKED in SELECT FOR UPDATE statements (see 2ndquadrant blog). Using such a strategy, it is possible to fetch executions pre-locked, and thus getting one statement less:

1. select for update .. skip locked a batch of due executions. These will already be picked by the scheduler-instance.
2. When execution is done, update or delete the record according to handlers.

In sum per batch: 1 select-and-update, 1 * batch-size updates (no misses)

Benchmark test

To get an idea of what to expect from db-scheduler, see results from the tests run in GCP below. Tests were run with a few different configurations, but each using 4 competing scheduler-instances running on separate VMs. TPS is the approx. transactions per second as shown in GCP.

Observations for these tests:

• For fetch-and-lock-on-execute
  • TPS ≈ 4-5 * execution-throughput. A bit higher than the best-case 2 * execution-throughput, likely due the inefficiency of missed executions.
  • throughput did scale with postgres instance-size, from 2000 executions/s on 4core to 4000 executions/s on 8core
• For lock-and-fetch
  • TPS ≈ 1 * execution-throughput. As expected.
  • seem to consistently handle 10k executions/s for these configurations
  • throughput did not scale with postgres instance-size (4-8 core), so bottleneck is somewhere else

Currently, polling strategy lock-and-fetch is implemented only for Postgres. Contributions adding support for more databases are welcome.

User testimonial

There are a number of users that are using db-scheduler for high throughput use-cases. See for example:

• https://github.com/kagkarlsson/db-scheduler/issues/209#issuecomment-1026699872
• https://github.com/kagkarlsson/db-scheduler/issues/190#issuecomment-805867950

Things to note / gotchas

• There are no guarantees that all instants in a schedule for a RecurringTask will be executed. The Schedule is consulted after the previous task-execution finishes, and the closest time in the future will be selected for next execution-time. A new type of task may be added in the future to provide such functionality.

• The methods on SchedulerClient (schedule, cancel, reschedule) will run using a new Connectionfrom the DataSource provided. To have the action be a part of a transaction, it must be taken care of by the DataSource provided, for example using something like Spring's TransactionAwareDataSourceProxy.

• Currently, the precision of db-scheduler is depending on the pollingInterval (default 10s) which specifies how often to look in the table for due executions. If you know what you are doing, the scheduler may be instructed at runtime to "look early" via scheduler.triggerCheckForDueExecutions(). (See also enableImmediateExecution() on the Builder)

Versions / upgrading

See releases for release-notes.

Upgrading to 15.x

• Priority is a new opt-in feature. To be able to use it, column priority and index priority_execution_time_idx must be added to the database schema. See table definitions for postgresql, oracle or mysql. At some point, this column will be made mandatory. This will be made clear in future release/upgrade-notes.

Upgrading to 8.x

• Custom Schedules must implement a method boolean isDeterministic() to indicate whether they will always produce the same instants or not.

Upgrading to 4.x

• Add column consecutive_failures to the database schema. See table definitions for postgresql, oracle or mysql. null is handled as 0, so no need to update existing records.

Upgrading to 3.x

• No schema changes
• Task creation are preferably done through builders in Tasks class

Upgrading to 2.x

• Add column task_data to the database schema. See table definitions for postgresql, oracle or mysql.

Building the source

Prerequisites

• Java 8+
• Maven

Follow these steps:

1. Clone the repository.

   git clone https://github.com/kagkarlsson/db-scheduler
   cd db-scheduler
   

2. Build using Maven (skip tests by adding -DskipTests=true)

   mvn package
   

Recommended spec

Some users have experienced intermittent test failures when running on a single-core VMs. Therefore, it is recommended to use a minimum of:

• 2 cores
• 2GB RAM

FAQ

Why db-scheduler when there is Quartz?

The goal of db-scheduler is to be non-invasive and simple to use, but still solve the persistence problem, and the cluster-coordination problem. It was originally targeted at applications with modest database schemas, to which adding 11 tables would feel a bit overkill.. Update: Also, as of now (2024), Quartz does not seem to be actively maintained either.

Why use a RDBMS for persistence and coordination?

KISS. It's the most common type of shared state applications have.

I am missing feature X?

Please create an issue with the feature request and we can discuss it there. If you are impatient (or feel like contributing), pull requests are most welcome :)

Is anybody using it?

Yes. It is used in production at a number of companies, and have so far run smoothly.