Persist Quartz Scheduler in Database

1. Introduction

When building a Spring web application, we often need to schedule recurring tasks or jobs, such as sending emails, generating reports, or processing data at specific intervals. The Quartz Scheduler is a popular choice for handling such tasks due to its robust and flexible scheduling capabilities.

A key challenge in Spring web applications is ensuring that scheduled Quartz jobs remain persistent across application restarts, maintaining their state and schedule seamlessly. There are generally two ways to achieve this:

• Let Quartz itself handle persistence using its JDBC JobStore.
• Maintain job definitions in a custom business table and load them into Quartz at startup.

In this tutorial, we’ll explore both approaches.

2. The Problem

In a Spring web application, developers may integrate Quartz to manage scheduled jobs. A key requirement is to store job and trigger details in a database so that they’re not lost when the application shuts down or restarts.

In a production environment, application restarts are common due to maintenance, updates, or unexpected crashes. If Quartz jobs are stored only in memory (the default behavior), they’re lost during a restart, leading to missed executions or the need for manual rescheduling.

Persisting jobs in a database ensures continuity, allowing the scheduler to pick up where it left off. This is particularly critical for tasks that must run on precise schedules, such as daily reports or time-sensitive notifications.

3. Maven Dependencies

Let’s start by importing the spring-boot-starter-quartz, spring-boot-starter-data-jdbc, spring-boot-starter-data-jpa, and h2 dependencies to our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-quartz</artifactId>
    <version>3.3.2</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jdbc</artifactId>
    <version>3.3.2</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
    <version>3.3.2</version>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.2.224</version>
</dependency>

4. Using Quartz’s JDBC JobStore

Quartz provides built-in persistence via its own schema (QRTZ_* tables). When configured with JDBC, Quartz automatically stores all jobs, triggers, and scheduling metadata in the database:

spring.quartz.job-store-type=jdbc

For development, we can use an H2 file-based database to simulate persistence across restarts. The recommended approach is to let Spring Boot create the schema once, and then disable schema initialization so that our job data is preserved:

spring.datasource.url=jdbc:h2:file:~/quartz-db;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE

# First run: let Spring create the Quartz schema
spring.quartz.jdbc.initialize-schema=always

# Restart runs: disable schema initialization to preserve existing data
# spring.quartz.jdbc.initialize-schema=never

With this setup, on the first run, Quartz will create the required QRTZ_* tables in the ~/quartz-db.mv.db. On subsequent restarts, we switch the setting to “never” so that the existing tables and job data aren’t dropped or re-initialized, allowing Quartz to reload scheduled jobs automatically. This way, jobs survive application restarts, and we can safely test recovery behavior with a simple H2 file-based database.

4.1. Defining a Quartz Job

Let’s create a job by implementing the Job interface:

public class SampleJob implements Job {
    @Override
    public void execute(JobExecutionContext context) {
        System.out.println("Executing SampleJob at " + System.currentTimeMillis());
    }
}

Then, we define an instance of the SampleJob using the JobDetail class:

@Bean
public JobDetail sampleJobDetail() {
    return JobBuilder.newJob(SampleJob.class)
      .withIdentity("sampleJob", "group1")
      .storeDurably()
      .requestRecovery(true)
      .build();
}

We use storeDurably() to persist the job in Quartz’s database. Additionally, we set requestRecovery(true) to ensure it will be retried if the application crashes during execution.

Now, we need to define a trigger:

@Bean
public Trigger sampleTrigger(JobDetail sampleJobDetail) {
    return TriggerBuilder.newTrigger()
      .forJob(sampleJobDetail)
      .withIdentity("sampleTrigger", "group1")
      .withSchedule(CronScheduleBuilder.cronSchedule("0/30 * * * * ?")) // every 30s
      .build();
}

We define the trigger with a cron expression (0/30 * * * * ?), scheduling the job to run every 30 seconds.

4.2. Re-Initializing Jobs on Restart

When using Quartz with a JDBC job store, both the JobDetail and its associated Trigger are persisted in Quartz’s schema. On application restart, Quartz automatically reloads them from the database, so there is no need for custom initialization logic.

Let’s create a unit test:

@Test
void givenSampleJob_whenSchedulerRestart_thenSampleJobIsReloaded() throws Exception {
    // Given
    JobKey jobKey = new JobKey("sampleJob", "group1");
    TriggerKey triggerKey = new TriggerKey("sampleTrigger", "group1");

    JobDetail jobDetail = scheduler.getJobDetail(jobKey);
    assertNotNull(jobDetail, "SampleJob exists in running scheduler");

    Trigger trigger = scheduler.getTrigger(triggerKey);
    assertNotNull(trigger, "SampleTrigger exists in running scheduler");

    // When
    scheduler.standby();
    Scheduler restartedScheduler = applicationContext.getBean(Scheduler.class);
    restartedScheduler.start();

    // Then
    assertTrue(restartedScheduler.isStarted(), "Scheduler should be running after restart");

    JobDetail reloadedJob = restartedScheduler.getJobDetail(jobKey);
    assertNotNull(reloadedJob, "SampleJob should be reloaded from DB after restart");

    Trigger reloadedTrigger = restartedScheduler.getTrigger(triggerKey);
    assertNotNull(reloadedTrigger, "SampleTrigger should be reloaded from DB after restart");
}

This test ensures that Quartz correctly reloads jobs and triggers from its persistent store after a simulated restart. First, we verify that the sampleJob and its associated sampleTrigger exist in the running scheduler.

Next, we put the scheduler into standby mode and obtain a fresh Scheduler instance from the Spring context, simulating an application restart. After starting the new scheduler, we assert that both the job and the trigger are available again. This confirms that Quartz automatically restores scheduled tasks from the database, with no need for additional initialization logic.

5. Using a Custom Business Job Repository

While Quartz provides built-in persistence, sometimes this is not enough. In many applications, we need more control over the business lifecycle of jobs. For example, marking them as enabled, disabled, or completed. In these cases, Quartz’s job store doesn’t capture enough business context, so we introduce our own table to manage jobs explicitly.

5.1. Defining a Custom Job Table

We can start by creating a JPA entity to represent jobs in our business domain:

@Entity
public class ApplicationJob {
    @Id
    private Long id;

    private String name;
    private boolean enabled;
    private Boolean completed;
}

This table is separate from Quartz’s QRTZ_* schema and is fully under our control. It allows us to track job metadata that Quartz doesn’t handle, such as whether a job has been explicitly marked as completed.

5.2. Seeding Business Jobs

On the first startup, we can pre-populate the table with a job definition. For instance, a simple seeder might insert a record if the table is empty:

@Component
public class DataSeeder implements CommandLineRunner {

    private final ApplicationJobRepository repository;

    public DataSeeder(ApplicationJobRepository repository) {
        this.repository = repository;
    }

    @Override
    public void run(String... args) {
        if (repository.count() == 0) {
            ApplicationJob job = new ApplicationJob();
            job.setName("simpleJob");
            job.setEnabled(true);
            job.setCompleted(false);

            repository.save(job);
        }
    }
}

This step simulates a real system where jobs might be defined or managed through an admin UI or business workflow.

5.3. Re-Initializing Jobs on Startup

Next, we need to connect our business repository with Quartz. On application startup, a listener can query the ApplicationJob table and schedule jobs dynamically:

@Component
public class JobInitializer implements ApplicationListener<ContextRefreshedEvent> {

    @Autowired
    private ApplicationJobRepository jobRepository;

    @Autowired
    private Scheduler scheduler;

    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        for (ApplicationJob job : jobRepository.findAll()) {
            if (job.isEnabled() && (job.getCompleted() == null || !job.getCompleted())) {
                JobDetail detail = JobBuilder.newJob(SampleJob.class)
                  .withIdentity(job.getName(), "appJobs")
                  .storeDurably()
                  .build();

                Trigger trigger = TriggerBuilder.newTrigger()
                  .forJob(detail)
                  .withSchedule(SimpleScheduleBuilder.simpleSchedule()
                    .withIntervalInSeconds(30)
                    .repeatForever())
                  .build();

                try {
                    scheduler.scheduleJob(detail, trigger);
                } catch (SchedulerException e) {
                    throw new RuntimeException(e);
                }
            }
        }
    }
}

On restart, Quartz doesn’t reload these jobs automatically because they’re not stored in its own schema. Instead, the JobInitializer runs, queries the business table, and ensures that only jobs marked as enabled and not completed are scheduled in Quartz.

The JobInitializer reschedules the job using the scheduler.scheduleJob() method.

Compared to Quartz’s built-in persistence, this approach gives us fine-grained control at the expense of duplicating scheduling logic. It’s especially useful when job definitions are part of the business model and need to be managed alongside other domain data.

6. Conclusion

In this article, we explored two approaches to persisting and recovering Quartz jobs. Quartz’s built-in JDBC persistence offers a turnkey solution, automatically storing jobs and triggers in its own schema and seamlessly reloading them after application restarts.

On the other hand, a custom business job repository gives us finer control over the job lifecycle, allowing us to enable, disable, or mark jobs as completed in our own domain model.

The right choice depends on the requirements: if we only need reliable scheduling, Quartz’s persistence is sufficient; if job state is part of the business workflow, a custom repository may be more appropriate.