fix: honour CRON starts_at in pg_cron materialization

[knutties]

Summary

This change adds a cron_starts_at guard to the SQL command that pg_cron executes for scheduled jobs, ensuring jobs don't fire before their intended start time.

Key Changes

• Updated build_cron_command function: Added AND (j.cron_starts_at IS NULL OR j.cron_starts_at <= now()) condition to the WHERE clause to prevent job execution before the scheduled start time
• Enhanced documentation: Clarified in the function's doc comment that both cron_starts_at and cron_ends_at guards are necessary to properly bound the job's active window
• Added test coverage: New cron_command_enforces_starts_at_window() test verifies that the generated SQL command includes the cron_starts_at guard

Implementation Details

The fix addresses a timing issue where pg_cron registers with only the cron expression and begins ticking immediately. Without the cron_starts_at guard, a job scheduled to start in the future would fire on the next matching cron tick instead of waiting until its starts_at time. The guard works in conjunction with the existing cron_ends_at guard to fully bound the job's execution window.

https://claude.ai/code/session_01LFK9KdT41HPV497BcNJWbZ

Summary by CodeRabbit

• Bug Fixes
  • Scheduled jobs now properly respect their configured start time and won't execute before reaching it.

[coderabbitai]

Walkthrough

The PR adds a start-time activation guard to pg_cron job execution. The build_cron_command function's SQL WHERE clause now includes a cron_starts_at predicate that blocks job materialization until the configured start time has arrived. Documentation clarifying the guard purpose and schema-qualification requirements, along with a new test validating the guard's presence, are included.

Changes

Cron Job Start-Time Guard

Layer / File(s)	Summary
Cron start-time activation guard crates/common/src/db/jobs.rs	Updated documentation explains cron_starts_at and cron_ends_at guard behavior and why schema-qualified names are required. SQL WHERE clause adds cron_starts_at predicate to prevent execution before the job's start time. New test asserts the guard condition is present in the generated pg_cron command.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• juspay/kronos#21: Both PRs modify crates/common/src/db/jobs.rs's pg_cron command generation (build_cron_command) to add/adjust time-window guard predicates—this PR adds a cron_starts_at guard while the related PR adds a cron_ends_at guard (plus related retirement/reap wiring).

Poem

🐰 A rabbit hops through time's long door,
With guards that block till start-time's near,
Cron jobs now wait—no more too soon—
The schedule blooms this sweet June tune. 🌙✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main change: adding a cron_starts_at guard to pg_cron job materialization to prevent execution before the configured start time.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/tender-lovelace-5x79fe

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}