Quartz earns its extra moving parts in these situations:

If none of those apply, @Scheduled is the better choice; adding Quartz only adds moving parts to get wrong.

Annotate your Application class with @EnableScheduling:

Annotate any Spring bean method — a service is the natural home — with @Scheduled:

A @Scheduled method must take no arguments and return void. Spring 6.1 additionally supports reactive return types — a Publisher, an RxJava type, or a Kotlin suspending function — which Spring subscribes to on the configured schedule.

Each duration attribute has a String variant — fixedDelayString, fixedRateString, initialDelayString — that accepts a property placeholder, and cron accepts one directly. This is the cleanest way to make a schedule configurable per environment:

Spring Boot configures the scheduler with a single thread by default. Every @Scheduled method in the application shares it, so one long-running or blocked task delays every other scheduled task. This is the second most common surprise with @Scheduled, after clustering.

Increase the pool through configuration:

On Java 21 and above, setting spring.threads.virtual.enabled to true switches the scheduler to virtual threads, in which case the pool size no longer applies and spring.task.scheduling.simple.concurrency-limit bounds concurrency instead.

@Scheduled is about when work runs. To run work off the request thread on demand, use @Async together with @EnableAsync:

@Async methods use the spring.task.execution. pool, which is separate from the scheduling pool. As with any Spring proxy-based annotation, calling an @Async or @Scheduled method from another method on the *same bean bypasses the proxy and runs it synchronously.

See also Asynchronous Programming for the Grails-specific async APIs.

Nothing in @Scheduled is aware of other instances of your application. Each instance builds its own scheduler from the annotations it finds at startup, in memory, with no shared state — so there is no coordination point, and nowhere for one instance to discover that another has already claimed a firing. With three instances deployed, a @Scheduled(cron = '0 0 6 * * ?') method runs three times at 6:00am — concurrently, on three machines, against the same database.

Common workarounds — designating one instance "the scheduler" with a Spring profile, or taking an advisory lock inside the method — either forfeit high availability or reimplement, badly, what a clustered scheduler already does.

For anything that must run exactly once per schedule across a deployment, see Advanced Scheduling.

Adding the plugin does not make your schedules cluster-safe.

Out of the box Quartz uses its in-memory RAMJobStore: the schedule is rebuilt from your source at every startup and lives entirely inside a single process, with no knowledge of any other instance. In that default configuration Quartz duplicates work across instances exactly as @Scheduled does.

Clustering has to be turned on deliberately, and it has three requirements — a JDBC job store, a shared set of Quartz tables, and explicit clustering properties. All of it is covered in Clustering. If you adopted this plugin in order to run on several instances, that section is the part that actually solves your problem.

A job is an artefact: a class in grails-app/jobs whose name ends in Job and which declares an execute method. The plugin discovers those classes, builds the Quartz JobDetail and Trigger objects described by their triggers block, and registers them with a Scheduler bean named quartzScheduler.

Nothing prevents using Quartz and @Scheduled in the same application — they are independent schedulers — but a given piece of work should belong to exactly one of them.

Start with Installation.

Use the create-job command to generate a job under grails-app/jobs:

That produces:

Jobs are Spring beans and are autowired by name, so you can inject services and other beans into them:

Jobs can also be scheduled with a cron expression — for example "at 6:00am every day" or "at 1:30am on the last Friday of the month":

The fields of a cronExpression are:

See the Quartz CronExpression documentation for the full set of special characters.

execute may optionally accept the Quartz JobExecutionContext, which carries the merged job data map and the fire-time details:

A job that declares an interrupt() method can be interrupted mid-execution through the jobManagerService. The plugin discovers the method reflectively, so the job class does not need to implement any Quartz interface:

Calling interruptJob on a job that has no interrupt() method raises an UnableToInterruptJobException.

Executes repeatedly on a fixed interval.

Executes according to a cron expression. See Writing Jobs for the expression format.

Delegates the firing schedule to your own implementation of the Quartz Trigger interface. This is how you use any Quartz trigger type the DSL does not model directly, such as DailyTimeIntervalTriggerImpl or CalendarIntervalTriggerImpl.

Any further attributes are set as properties on the trigger instance, so you can configure the trigger with whatever its class exposes:

A trigger that can never fire — a cron expression whose last occurrence is in the past, or an end time that has already passed — is reported as an error in the log and left unscheduled, so it does not keep the application from starting. Configure quartz.failOnNeverFiringTriggers to have startup fail instead; see Configuration.

The triggers closure is given access to the grailsApplication object, so trigger attributes can be driven from configuration:

A JobDescriptor exposes the job’s name and group, the underlying Quartz jobDetail, and a triggerDescriptors list. Each TriggerDescriptor carries the trigger’s name and group, its current state as a Trigger.TriggerState, and the underlying Quartz trigger — from which the fire times and schedule details can be read.

The Quartz Scheduler itself is also available as the quartzScheduler bean if you need an operation the service does not wrap.

concurrent defaults to true, so every fire starts an execution whether or not the previous one has finished. A job that runs for hours on a trigger that fires every few minutes therefore stacks executions up, each holding one of the scheduler’s worker threads for its whole run. Once every thread is occupied nothing fires at all: the scheduler looks stuck, the log fills with misfires, and no work gets done.

Set concurrent = false on such a job, and the scheduler never runs two of its executions at the same time:

A fire that arrives while the job is still running is then held, and what becomes of it is the trigger’s misfire instruction.

Jobs run on a fixed pool of worker threads — ten of them unless configured otherwise. A long-running job holds one of those threads for its entire execution, so the pool has to be large enough for every execution that can be in flight at once, plus the short jobs that must keep firing meanwhile:

A trigger misfires when the scheduler cannot fire it when it was due — because the previous execution is still running and the job is not concurrent, or because no worker thread is free. What happens to the fires that were missed is the trigger’s misfireInstruction, set like any other trigger attribute. Left unset, a trigger uses Quartz’s smart policy, which depends on the trigger type: an indefinitely repeating simple trigger drops the fires it missed and carries on at its next scheduled time, while a cron trigger fires once immediately.

So to have an hourly report skip the run it missed instead of starting it the moment the long execution finishes:

The instructions to choose from are the constants of the Quartz trigger type — SimpleTrigger and CronTrigger. How late a fire may be before the scheduler counts it as a misfire is quartz.jobStore.misfireThreshold, in milliseconds; it is passed straight through to Quartz, so set it explicitly if the tolerance matters to your schedule.

jobManagerService.runningJobs returns the JobExecutionContext of every execution in flight. Each one carries the job it belongs to as jobDetail.key and the moment its execution began as fireTime, which is all that is needed to find work that has been running for too long:

There is no timeout setting. Nothing can safely stop a thread in the middle of arbitrary work, so a job is asked to stop itself instead: declare an interrupt() method on the job, and the plugin routes interruption requests to it. It is up to the job to notice and return from execute.

A field is enough to carry the flag: every execution is given its own instance of the job class, so nothing is shared between executions.

Ask for the interruption from anywhere in the application, by job group and job name:

A job that does not declare interrupt() cannot be stopped; the request raises an UnableToInterruptJobException saying so. Code that interrupts jobs it does not own — a watchdog job which interrupts whatever it finds running past a limit, for instance — has to allow for that.

A Hibernate Session is bound to the job’s thread for the whole execution unless the job sets sessionRequired = false. A session that lives for hours keeps every entity it has loaded in its first-level cache, so memory grows with the work done and the entities it holds drift further from the database.

Process the work of a long job in chunks, each in a session of its own, so neither grows without bound:

Note that the session is bound regardless of sessionRequired when quartz.jdbcStore is enabled, because the job store needs it.

Every key beneath quartz is flattened and handed to Quartz itself with an org.quartz. prefix, so any Quartz configuration property can be set the same way. For example, this configures the thread pool:

which Quartz receives as org.quartz.threadPool.threadCount and org.quartz.threadPool.threadPriority. The plugin options in the table above are read from the same flattened set, which is why they share the quartz prefix.

A logger is injected into every job class, so no setup is required to use log from within execute. To change the level, configure the grails.app.jobs logger — for example in grails-app/conf/logback.groovy:

Any exception thrown from a job is logged by a global job listener registered by the plugin, so failures are never silently swallowed.

When a Hibernate plugin is on the classpath, the plugin binds a Hibernate Session to the thread for the duration of each job execution. This is what allows a job to use GORM — lazy-loading collections, or applying unique constraints — exactly as a service would.

Set sessionRequired to false on a job to opt out of this behaviour. This is rarely useful; note that the session is bound regardless when jdbcStore is enabled, because the job store needs it.

The binding covers the job’s execute method only. Job listeners run outside it and must manage their own session — see Job listeners.

To run code around every job — binding a security context, populating a logging context, or any other setup a job inherits rather than repeats — register a Quartz JobListener with the scheduler. This is the supported way to share behaviour across all jobs; the plugin uses the same mechanism internally for its own exception logging.

Implement JobListener (or extend Quartz’s JobListenerSupport, which no-ops the callbacks you do not need):

Register it against the quartzScheduler bean, typically from BootStrap:

A listener registered with no matcher observes every job. To restrict it to particular jobs, pass a Matcher — KeyMatcher.keyEquals(…​) for a single job, or GroupMatcher.jobGroupEquals(…​) for a whole job group.

By default Quartz keeps jobs and triggers in memory, so they are rebuilt from your source every time the application starts. Setting jdbcStore to true switches Quartz to its JDBC job store, which persists them in the database:

Two things are required for this to work:

Persistent storage interacts with the durability and requestsRecovery job properties described in Job Properties.

Quartz can coordinate a schedule across several instances of your application, so a given trigger fires exactly once no matter how many instances are deployed. This requires jdbcStore, a shared set of Quartz tables, and a handful of additional properties.

Clustering is covered in full — including the requirements and the pitfalls — in the Clustering section.

Quartz clusters through the database. Every instance is configured with the same scheduler name and points at the same set of Quartz tables. When a trigger’s firing time arrives, each instance races to acquire a row lock on it; the first to take the lock is the one that fires it, and the others move on. The result is load balancing across the cluster with exactly-once firing per trigger.

Failover works from the same mechanism. Instances check in on an interval; when one stops checking in, another detects the failure and recovers its work — re-firing the jobs that declared requestsRecovery.

Three things are required.

1. A JDBC job store. Clustering works only with the JDBC job store — the default in-memory RAMJobStore cannot cluster, because there is nothing shared to coordinate through.

2. The Quartz tables. Quartz ships a schema script for each supported database with its distribution; create the QRTZ_* tables before starting the application.

3. Clustering configuration. Every key under quartz is passed through to Quartz with an org.quartz. prefix, so the standard clustering properties are set the same way:

Every instance must use the same instanceName and the same tables. Only instanceId and the thread-pool size should differ.

A single-instance deployment does not need any of this, and quartz.jdbcStore should be left at its default of false — the in-memory store is simpler and faster, and the schedule is rebuilt from your source at every startup.

If you have a single instance but need the schedule itself to survive restarts — because it is modified at runtime — enable jdbcStore without isClustered.