tessl/golang-github-com-go-co-op-gocron-v2
A Golang job scheduling library that lets you run Go functions at pre-determined intervals using cron expressions, fixed durations, daily, weekly, monthly, or one-time schedules with support for distributed deployments.
cron.mddocs/api/jobs/
Cron Jobs
Jobs scheduled with cron expressions.
CronJob
func CronJob(crontab string, withSeconds bool) JobDefinitionRuns according to a cron expression. Supports standard 5-field and extended 6-field (with seconds) formats.
Parameters:
crontab: Cron expression or expression with TZ prefixwithSeconds: true for 6-field format (with seconds), false for 5-field format
Errors:
ErrCronJobParse: Cron expression syntax errorErrCronJobInvalid: Invalid field values
Cron Format
5-field (withSeconds=false):
minute hour day month weekday6-field (withSeconds=true):
second minute hour day month weekdayField Values
- second: 0-59
- minute: 0-59
- hour: 0-23
- day: 1-31
- month: 1-12 (or JAN-DEC)
- weekday: 0-6 (0=Sunday) or SUN-SAT
Special Characters
*: any value,: value list (1,3,5)-: range (1-5)/: step (*/5 = every 5)?: no specific value (day or weekday only)
Examples
// Every 5 minutes
gocron.CronJob("*/5 * * * *", false)
// Every day at 9:30 AM
gocron.CronJob("30 9 * * *", false)
// Every Monday at 10 AM
gocron.CronJob("0 10 * * 1", false) // 0=Sunday, 1=Monday
// Every 30 seconds (6-field)
gocron.CronJob("*/30 * * * * *", true)
// First day of every month at midnight
gocron.CronJob("0 0 1 * *", false)
// Weekdays at 9 AM (Monday-Friday)
gocron.CronJob("0 9 * * 1-5", false)
// Every quarter hour (0, 15, 30, 45 minutes)
gocron.CronJob("0,15,30,45 * * * *", false)Timezone Prefix
Override scheduler timezone for specific job:
// Chicago time (TZ prefix)
gocron.CronJob("TZ=America/Chicago 0 9 * * *", false)
// Or CRON_TZ prefix (equivalent)
gocron.CronJob("CRON_TZ=America/Chicago 0 9 * * *", false)
// Without prefix, uses scheduler's location
gocron.CronJob("0 9 * * *", false) // uses WithLocation from schedulerDST Handling
During DST transitions:
- Spring forward: Jobs during skipped hour run at next valid time
- Fall back: Jobs during repeated hour may run once or twice (implementation-dependent)
For critical timing, use UTC or test thoroughly.
Usage Examples
Basic Cron Job
// Run every hour
j, err := s.NewJob(
gocron.CronJob("0 * * * *", false),
gocron.NewTask(func() {
fmt.Println("Hourly task")
}),
)With Timezone
// Run at 9 AM New York time, regardless of scheduler timezone
j, err := s.NewJob(
gocron.CronJob("TZ=America/New_York 0 9 * * *", false),
gocron.NewTask(func() {
sendMorningReport()
}),
)With Seconds
// Run every 30 seconds
j, err := s.NewJob(
gocron.CronJob("*/30 * * * * *", true),
gocron.NewTask(func() {
checkHealth()
}),
)Complex Schedule
// Run at 9 AM and 5 PM on weekdays
j, err := s.NewJob(
gocron.CronJob("0 9,17 * * 1-5", false),
gocron.NewTask(func() {
syncData()
}),
)Common Patterns
// Every minute
"* * * * *"
// Every hour
"0 * * * *"
// Every day at midnight
"0 0 * * *"
// Every day at noon
"0 12 * * *"
// Every Monday at 9 AM
"0 9 * * 1"
// Every first day of month
"0 0 1 * *"
// Every 15 minutes
"*/15 * * * *"
// Every hour between 9 AM and 5 PM on weekdays
"0 9-17 * * 1-5"
// At 9:30 AM on weekdays
"30 9 * * 1-5"
// Every 5 minutes during business hours
"*/5 9-17 * * 1-5"See Also
- Duration Jobs - Fixed intervals
- Time-Based Jobs - Daily, weekly, monthly
- Creating Schedulers - WithLocation
- Advanced Scheduling Guide - Edge cases
Install with Tessl CLI
npx tessl i tessl/golang-github-com-go-co-op-gocron-v2docs
api
examples
guides