Skip to content
notes.vinhnq.com

Search

SpringMid20 min read

Cron jobs: cron expressions and @Scheduled in Spring Boot

Review 22 cards
On this page

Cron jobs series: 1. Cron expressions and @Scheduled · 2. Deleting old data safely

A lot of backend work has to run on a schedule: cleaning up old data, a summary email every morning, end-of-day payment reconciliation, refreshing caches. After this post you can write correct cron expressions for Unix, Spring and Quartz, and you’ll know the traps @Scheduled springs on you in production. Part 2 solves the cleanup problem end to end: deleting millions of rows in batches, backing up before deleting, partitioning, and the full exercise.

1. The problem

Key idea: soft-deleted rows stay in the database forever, so we need a periodic job that backs up and then hard-deletes rows that have been INACTIVE for more than X months.

A soft delete means that when a user deletes something, we only set status to INACTIVE instead of removing the row. Tables keep growing: bigger indexes, slower queries, longer backups, more storage.

2. What a cron job is

Key idea: a cron job is a task scheduled to run periodically or at a specific time. The name comes from cron, the Unix scheduling daemon (a background process).

  • Automates repetitive work (backups, emails, data syncs, cleanup): nobody has to remember to run it by hand. Two cleanup examples elsewhere: removing files orphaned when the transaction rolls back after the write (file upload in Spring MVC) and purging expired refresh tokens nightly (rotating refresh tokens).
  • On time and consistent, as long as you handle the failure modes in section 5.

3. Cron expressions

Key idea: there’s no single cron standard. Unix, Spring and Quartz differ in the number of fields, how they number weekdays and how they combine day-of-month with day-of-week, so an expression can’t be copied between them as is.

Three different “dialects”

Unix crontab / Kubernetes CronJob Spring CronExpression (5.3+) Quartz
Number of fields 5 6 6 or 7
Order min hour day month weekday sec min hour day month weekday sec min hour day month weekday [year]
Year field No No Yes (optional)
Numeric day-of-week 0-7 (0 and 7 = Sun) 0-7 (0 and 7 = Sun), 1 = MON 1-7 (1 = Sun), 2 = MON
? No Yes (treated like *) Required in exactly one of the two day fields
L, W, # No (standard cron) Yes (since Spring 5.3) Yes
Both day-of-month and day-of-week set OR (either matches) AND (both must match) Not allowed
Macros like @daily, @hourly Yes (+ @reboot) Yes (@yearly, @monthly, @weekly, @daily, @midnight, @hourly) No

The fields (Spring)

Position Field Values
1 second 0-59
2 minute 0-59
3 hour 0-23
4 day-of-month 1-31
5 month 1-12 or JAN-DEC
6 day-of-week 0-7 (0 and 7 are Sunday) or SUN-SAT

A correction: the course material gives the format as [second] minute hour day-of-month month day-of-week [year] with day-of-week 0-6 (0 = Sunday), which mixes the three dialects. Spring: seconds are always there, no year, day-of-week takes 0-7. Quartz: 1-7, with 1 being Sunday.

Special characters

Character Meaning Example (Spring)
* every value * in the hour field: every hour
- range 9-17 in the hour field: 9 through 17, inclusive
, list MON,WED,FRI
/ increment: start/step 5/15 in the minute field: minutes 5, 20, 35, 50
? “don’t care”, only in the day fields 0 0 0 15 5 ?: midnight on May 15, any weekday
L, W, # last day, nearest weekday, nth weekday L, 10W, SAT#3 (details below)
The L, W and # characters and their edge cases
Character Meaning Example (Spring)
L in day-of-month last day of the month L: Jan 31, Feb 28 (non-leap year)…
L-n n days before the last day of the month L-3: the 28th in a 31-day month
nL in day-of-week the last given weekday of the month FRIL or 5L: last Friday of the month
nW nearest weekday (Mon-Fri) to day n, never crossing into another month 10W
LW last weekday of the month
d#n the nth occurrence of weekday d in the month SAT#3: third Saturday of the month

How # works: 6#3 (Spring) or SAT#3 is the third Saturday of the month. FRI#5 only fires in months that have five Fridays; other months are skipped.

On how trustworthy these tables are: I ran every expression through Spring 6.2’s CronExpression.parse(...).next(...).

Verified examples (Spring)

A few common ones: 0 0 0 * * * (midnight every day), 0 0/5 * * * * (every 5 minutes), 0 0 12 * * MON-FRI (12:00 Mon-Fri), 0 0 0 1 * * (midnight on the 1st of every month). The value - makes @Scheduled disable the job.

A few examples in the course material are wrong for Spring (a year field, or 7 fields); see the folded section below.

20 verified expressions and the broken ones from the course material
Expression Meaning
* * * * * * every second
0/30 * * * * * every 30 seconds (seconds 0 and 30)
0 0/5 * * * * every 5 minutes, starting at minute 0
0 0-5/2 * * * * minutes 0, 2 and 4 of every hour
0 0 0 * * * midnight every day
0 15 10 * * * 10:15 every day
0 0 0-6 * * * on the hour from 00:00 to 06:00 (7 runs)
0 0 6,18 * * * 06:00 and 18:00
0 0 12 * * MON-FRI 12:00 Monday to Friday
0 0 12 * * SUN 12:00 every Sunday
0 0 0 1 * * midnight on the 1st of every month
0 0 0 1-5 * * midnight on the 1st through the 5th of every month
0 0 0 15 3 * midnight on March 15 every year
0 0 0 1 1 * midnight on January 1 every year
0 0 0 * * MON#1 midnight on the first Monday of the month
0 0 0 * * TUE#2 midnight on the second Tuesday of the month
0 0 12 * * MON#3 12:00 on the third Monday of the month
0 0 0 10W * * midnight on the weekday nearest the 10th
0 0 0 L * * midnight on the last day of the month
0 0 18 * * FRIL 18:00 on the last Friday of the month
- a special value @Scheduled treats as disabled (handy via a property); CronExpression.parse itself rejects it

4. @Scheduled in Spring Boot

Key idea: turn on @EnableScheduling, then put @Scheduled on a void, no-argument method of a bean. Pick the schedule with fixedRate, fixedDelay or cron.

@SpringBootApplication
@EnableScheduling
public class ShopApplication { ... }

@Component
@Slf4j
public class ReportJobs {

    @Scheduled(fixedRate = 60_000)                       // every 60s measured from the previous START
    void refreshExchangeRates() { ... }

    @Scheduled(fixedDelay = 30, timeUnit = TimeUnit.SECONDS, initialDelay = 10)
    void pollOutbox() { ... }                            // 30s after the previous run FINISHES

    @Scheduled(cron = "0 0 7 * * MON-FRI", zone = "Asia/Ho_Chi_Minh")
    void sendDailySummary() { ... }

    @Scheduled(cron = "${jobs.cleanup.cron:-}")          // from config; defaults to "-" = disabled
    void cleanup() { ... }
}

initialDelay waits before the first run; zone sets the time zone the cron is evaluated in (the server’s by default).

All the @Scheduled attributes
Attribute Meaning
fixedRate Interval between run starts
fixedDelay Pause measured from when the previous run finished
initialDelay How long to wait before the first run
cron Schedule by cron expression (6 fields)
zone Time zone used to evaluate the cron; defaults to the server’s time zone
timeUnit Unit for numeric values (milliseconds by default)
fixedRateString, fixedDelayString… String variants supporting ${...} placeholders and ISO-8601 (PT30S)

A correction about fixedRate

5. @Scheduled traps

Key idea: @Scheduled is simple, but it keeps no state and knows nothing about clusters. You have to handle the thread pool, error monitoring, catch-up, duplicate runs across pods, idempotency and time zones yourself.

There’s only one thread

Exceptions don’t stop the job, but they’re easy to miss

No catch-up

If the app is being deployed, or is down, exactly at 00:00, that run is lost. For an every-minute job, who cares; for a job that runs once a year (like the exercise in part 2), you wait another year. Designing jobs as “run often + a data-driven condition” makes them self-healing (see part 2).

Running on several instances

ShedLock is a library that uses a row in the database (or Redis, ZooKeeper) as a lock: the pod that manages to update the row runs the job, the others skip this run.

sequenceDiagram
  participant A as Pod A
  participant B as Pod B
  participant L as shedlock table (DB)
  Note over A,B: 00:00:00 both pods fire the job
  A->>L: UPDATE ... SET lock_until = now()+6h WHERE name='purge' AND lock_until has passed
  L-->>A: 1 row updated: lock acquired
  B->>L: same UPDATE
  L-->>B: 0 rows: skip this run
  A->>A: run the job
  A->>L: release (lock_until = max(now, locked_at + lockAtLeastFor))
  • lockAtMostFor: the lock expires after this long if the pod dies mid-run. It must be longer than the job’s real runtime, or another pod starts a parallel run.
  • lockAtLeastFor: hold the lock at least this long, so a very fast job isn’t rerun for the same fire time by a pod whose clock is a few seconds off.
ShedLock configuration with JDBC
@Configuration
@EnableScheduling
@EnableSchedulerLock(defaultLockAtMostFor = "PT30M")
class SchedulingConfig {
    @Bean
    LockProvider lockProvider(DataSource dataSource) {
        return new JdbcTemplateLockProvider(
                JdbcTemplateLockProvider.Configuration.builder()
                        .withJdbcTemplate(new JdbcTemplate(dataSource))
                        .usingDbTime()          // use the DB clock, avoiding clock skew between pods
                        .build());
    }
}
CREATE TABLE shedlock (
    name       VARCHAR(64)  PRIMARY KEY,
    lock_until TIMESTAMP    NOT NULL,
    locked_at  TIMESTAMP    NOT NULL,
    locked_by  VARCHAR(255) NOT NULL
);

ShedLock only handles “one pod runs the job”. When you need to share thousands of small tasks across workers, retry each one, or deliver one event to several consumers, use a queue: a job table with FOR UPDATE SKIP LOCKED or a message broker. Message brokers and how to choose one compares the two and has the full table-as-queue version (leases, a sweeper, a dead-letter state).

Idempotency

Idempotent: running it twice gives the same result as running it once. A lock doesn’t eliminate duplicate runs (locks expire, retries, manual runs), so the job still needs this property:

  • Delete by condition (status = 'INACTIVE' AND updated_at < cutoff), not by “the list of IDs computed yesterday”.
  • Write results keyed by a natural key (report_date) with a UNIQUE constraint or an upsert.
  • For notifications, record a “sent” row keyed by (user, type, date) so later runs skip it.
A full example: releasing expired seat holds on 4 pods

Exercise 2 of Airline booking: holding seats correctly when many people book at once. A job releases expired seat holds every minute on 4 pods, in batches of 1,000 rows with FOR UPDATE SKIP LOCKED, so the pods split the work instead of blocking each other. The status = 'HELD' condition is re-checked after locking, so no seat is released twice.

Time zones and daylight saving time

Cron is evaluated in zone, which defaults to the JVM’s time zone (often UTC in containers). 0 0 0 1 6 * on a UTC server fires at 7 a.m. Vietnam time. Always declare zone = "Asia/Ho_Chi_Minh" (or "UTC"); don’t rely on the JVM.

Why the JVM, the OS and the container can each carry a different time zone, and how DST makes a day 23 or 25 hours long: Dates and times in the backend.

Make it testable

  • Don’t wait for the clock: move the logic into a service and test it normally.
  • Inject a Clock instead of calling LocalDateTime.now(), so you can test the “older than 6 months” condition.
  • Unit test the cron expression itself:
@Test
void purgeRunsAtMidnightOnJuneFirst() {
    CronExpression cron = CronExpression.parse("0 0 0 1 6 *");
    LocalDateTime next = cron.next(LocalDateTime.of(2026, 6, 1, 0, 0, 1));
    assertThat(next).isEqualTo(LocalDateTime.of(2027, 6, 1, 0, 0));
}

Remember

  • Can you write the same schedule for Unix, Spring and Quartz, and explain why 5L is off by a day between Spring and Quartz?
  • Can you explain when fixedRate runs can overlap and when they can’t?
  • Can you list the four default traps of @Scheduled: one thread, swallowed exceptions, no catch-up, running on every instance?
  • Do you know how to pick ShedLock’s lockAtMostFor, and why the job must stay idempotent even with a lock?
  • Do you know how DST makes a 02:30 job skip or run twice, and how to avoid it?

Interview questions

Junior

What is a cron job? Give a few backend examples.

A task that runs on a recurring schedule or at a specific time.

Examples: cleaning up old data, sending summary emails, end-of-day payment reconciliation, refreshing caches, expiring unpaid orders.

How many fields does a Spring cron expression have?

Six: second, minute, hour, day of month, month, day of week.

No year field (unlike Quartz), and one more field (seconds) than the 5-field Unix crontab.

What’s the difference between fixedRate and fixedDelay?

fixedRate measures the interval between starts; fixedDelay measures from the end of one run to the start of the next.

With the default scheduler neither overlaps; a late fixed-rate run starts immediately after the previous one finishes.

What does 0 0/15 9-17 * * MON-FRI mean?

Every 15 minutes (minutes 0, 15, 30, 45) from 9:00 to 17:45, Monday through Friday.

Mid

Why can one slow job delay all the others?

Because Spring Boot’s default scheduler has a single thread shared by every @Scheduled method.

Increase spring.task.scheduling.pool.size, or have heavy jobs hand off work to their own executor.

Which day is day-of-week 1?

It depends: Monday in Spring and Unix, Sunday in Quartz.

That’s why you should use names (MON) instead of numbers.

What happens when a @Scheduled method throws?

For repeating tasks, the default ErrorHandler logs and swallows the exception, and the next run still happens.

You need your own logging, metrics and alerts, or the job can fail silently for a long time.

If the app is down when a job should fire, does Spring catch up?

No. @Scheduled keeps no state; a missed fire time is simply gone.

For catch-up, use Quartz (misfire policies), or design the job to run frequently with a data-driven condition so it catches up on its own.

Senior

You deploy 3 instances. How many times does a @Scheduled job run, and what do you do about it?

Three times, once per instance. Add a distributed lock and still keep the job idempotent.

Use ShedLock on a DB or Redis so only one instance runs it; or a Quartz cluster, a Kubernetes CronJob with concurrencyPolicy: Forbid, or a dedicated worker. Even with a lock, the job must be idempotent, because locks can expire and people run jobs by hand.

How do you choose ShedLock’s lockAtMostFor?

Longer than the job’s longest possible runtime, but not absurdly long.

Too short and the lock expires mid-run, so another instance starts in parallel. Too long and, if a pod dies, the job is blocked until the lock expires. Pair it with a time budget inside the job itself.

How do time zones and DST affect cron jobs?

Cron is evaluated in zone, which defaults to the JVM time zone (usually UTC in containers), so set it explicitly.

In DST time zones, a fire time inside the skipped hour doesn’t run, and one inside the repeated hour can run twice. Avoid the transition window, use UTC, and keep jobs idempotent.

When would you move off @Scheduled to something else?

When I need what @Scheduled lacks: catch-up runs, schedules that change at runtime, a history of each execution, controlled retries, work spread across workers, or multi-step workflows.

Then consider a Quartz cluster, db-scheduler/JobRunr, Kubernetes CronJobs, or Temporal/Airflow.

Useful phrases for interviews

  • “Spring’s cron has six fields starting with seconds, and unlike Quartz it has no year field.”
  • “I always use weekday names instead of numbers, because Quartz counts Sunday as one.”
  • “By default every scheduled method shares a single thread, so one slow job can starve the rest.”
  • “With multiple replicas, I put a ShedLock on the job and still make it idempotent.”
  • “Spring’s scheduler doesn’t catch up on missed runs, so I prefer jobs that run often with a data-driven condition.”
  • “I set the zone explicitly, because containers usually run in UTC.”
  • “fixedRate is measured from the start of each run and fixedDelay from the end, and with the default scheduler neither one overlaps.”
  • “I unit test the cron expression itself with CronExpression.next instead of waiting for the clock.”

Notes based on the Fundamentals of Backend course (Ronin Engineer), rewritten in my own words.