Scheduled Jobs and Time Zones: The Midnight Bug I Keep Seeing

Description and use

Define the business day with an IANA time zone, compute the reporting window in that zone, convert to UTC for queries, schedule cron in UTC away from midnight, and run four frozen‑clock tests to eliminate DST‑related midnight bugs.

Problem

Cron jobs scheduled at midnight run in UTC, causing reports to use the wrong local day and month due to daylight saving and offset changes.

Outcome

Implementing explicit business‑zone windows and four edge‑case tests eliminates midnight‑related reporting bugs caused by UTC scheduling and DST shifts.

Workflow

• 1. Decide and record the business time zone as an IANA name (e.g., Europe/Berlin).
• 2. Store the zone string in configuration.
• 3. In job code, convert current UTC time to the business zone, subtract one day, snap to start of day, and compute end of day. 4. Convert start and end instants back to UTC for database queries.
• 5. Schedule the cron trigger in UTC, preferably after midnight local time (e.g., 03:00 local).
• 6. Write four unit tests with a frozen clock: midnight, month boundary, spring‑forward, fall‑back.
• 7. Run tests to ensure window boundaries are correct across DST transitions.
• 8. Deploy job with confidence that reporting windows are accurate.
• 9. Monitor for any future DST changes and re‑run tests if necessary.

Evidence

Cron runs in UTC by default, so a "midnight" job can fire on the wrong local day

Source

Define the business day explicitly with a timezone string, never a UTC offset

Source

Test the four edge cases: midnight, month boundary, spring-forward, fall-back

Source