CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

Overview
Eval results
Files

time-based.mddocs/api/jobs/

Time-Based Jobs

Jobs scheduled at specific times of day, week, or month.

DailyJob

func DailyJob(interval uint, atTimes AtTimes) JobDefinition

Runs every N days at specified times of day.

Parameters:

  • interval: Number of days between runs, must be > 0
  • atTimes: Times during the day (created with NewAtTimes)

Errors:

  • ErrDailyJobZeroInterval: interval is 0
  • ErrDailyJobAtTimesNil: atTimes is nil
  • ErrDailyJobAtTimeNil: individual atTime within atTimes is nil
  • ErrDailyJobHours: hours not in 0-23
  • ErrDailyJobMinutesSeconds: minutes or seconds not in 0-59

Time Helpers

func NewAtTime(hours, minutes, seconds uint) AtTime
func NewAtTimes(atTime AtTime, atTimes ...AtTime) AtTimes

Examples

// Every day at 8 AM
gocron.DailyJob(1, gocron.NewAtTimes(
    gocron.NewAtTime(8, 0, 0),
))

// Every day at 8 AM and 8 PM
gocron.DailyJob(1, gocron.NewAtTimes(
    gocron.NewAtTime(8, 0, 0),
    gocron.NewAtTime(20, 0, 0),
))

// Every 2 days at noon
gocron.DailyJob(2, gocron.NewAtTimes(
    gocron.NewAtTime(12, 0, 0),
))

// Every day at 9:30:15
gocron.DailyJob(1, gocron.NewAtTimes(
    gocron.NewAtTime(9, 30, 15),
))

Behavior

  • Default start: Next available day
  • Use WithStartAt(WithStartImmediately()) to run today if time hasn't passed
  • Respects scheduler timezone (set via WithLocation)

WeeklyJob

func WeeklyJob(interval uint, daysOfTheWeek Weekdays, atTimes AtTimes) JobDefinition

Runs every N weeks on specified days at specified times.

Parameters:

  • interval: Number of weeks between runs, must be > 0
  • daysOfTheWeek: Days to run (created with NewWeekdays)
  • atTimes: Times during the day (created with NewAtTimes)

Errors:

  • ErrWeeklyJobZeroInterval: interval is 0
  • ErrWeeklyJobDaysOfTheWeekNil: daysOfTheWeek is nil
  • ErrWeeklyJobAtTimesNil: atTimes is nil
  • ErrWeeklyJobAtTimeNil: individual atTime is nil
  • ErrWeeklyJobHours: hours not in 0-23
  • ErrWeeklyJobMinutesSeconds: minutes or seconds not in 0-59

Helpers

func NewWeekdays(weekday time.Weekday, weekdays ...time.Weekday) Weekdays

Weekdays: time.Sunday, time.Monday, time.Tuesday, time.Wednesday, time.Thursday, time.Friday, time.Saturday

Examples

// Every Monday at 9 AM
gocron.WeeklyJob(
    1,
    gocron.NewWeekdays(time.Monday),
    gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)),
)

// Every Monday and Wednesday at 9 AM
gocron.WeeklyJob(
    1,
    gocron.NewWeekdays(time.Monday, time.Wednesday),
    gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)),
)

// Every 2 weeks on Friday at 5 PM
gocron.WeeklyJob(
    2,
    gocron.NewWeekdays(time.Friday),
    gocron.NewAtTimes(gocron.NewAtTime(17, 0, 0)),
)

// Monday and Friday at 9 AM and 5 PM
gocron.WeeklyJob(
    1,
    gocron.NewWeekdays(time.Monday, time.Friday),
    gocron.NewAtTimes(
        gocron.NewAtTime(9, 0, 0),
        gocron.NewAtTime(17, 0, 0),
    ),
)

Behavior

  • Week starts on Sunday (Go's time.Weekday convention)
  • Default start: Next available week
  • Use WithStartAt(WithStartDateTimePast(...)) to align with specific week

MonthlyJob

func MonthlyJob(interval uint, daysOfTheMonth DaysOfTheMonth, atTimes AtTimes) JobDefinition

Runs every N months on specified days at specified times.

Parameters:

  • interval: Number of months between runs, must be > 0
  • daysOfTheMonth: Days to run (created with NewDaysOfTheMonth)
  • atTimes: Times during the day (created with NewAtTimes)

Errors:

  • ErrMonthlyJobZeroInterval: interval is 0
  • ErrMonthlyJobDaysNil: daysOfTheMonth is nil
  • ErrMonthlyJobAtTimesNil: atTimes is nil
  • ErrMonthlyJobAtTimeNil: individual atTime is nil
  • ErrMonthlyJobDays: day not in 1-31 or -1 to -31 (or is 0)
  • ErrMonthlyJobHours: hours not in 0-23
  • ErrMonthlyJobMinutesSeconds: minutes or seconds not in 0-59

Helpers

func NewDaysOfTheMonth(day int, moreDays ...int) DaysOfTheMonth

Day Numbering

  • Positive (1-31): Count from start of month. 1 = first day, 31 = 31st day.
  • Negative (-1 to -31): Count from end of month. -1 = last day, -5 = 5 days before end.
  • 0 is invalid.
  • Days that don't exist in a month (e.g., 31 in February) are skipped.

Examples

// On the 1st of every month at noon
gocron.MonthlyJob(
    1,
    gocron.NewDaysOfTheMonth(1),
    gocron.NewAtTimes(gocron.NewAtTime(12, 0, 0)),
)

// On the 1st and 15th at noon
gocron.MonthlyJob(
    1,
    gocron.NewDaysOfTheMonth(1, 15),
    gocron.NewAtTimes(gocron.NewAtTime(12, 0, 0)),
)

// Last day of every month at midnight
gocron.MonthlyJob(
    1,
    gocron.NewDaysOfTheMonth(-1),
    gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
)

// 5 days before end of month at 10 AM
gocron.MonthlyJob(
    1,
    gocron.NewDaysOfTheMonth(-5),
    gocron.NewAtTimes(gocron.NewAtTime(10, 0, 0)),
)

// Every 2 months on the 1st at midnight
gocron.MonthlyJob(
    2,
    gocron.NewDaysOfTheMonth(1),
    gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
)

// Multiple days and times: 1st and 15th at 9 AM and 5 PM
gocron.MonthlyJob(
    1,
    gocron.NewDaysOfTheMonth(1, 15),
    gocron.NewAtTimes(
        gocron.NewAtTime(9, 0, 0),
        gocron.NewAtTime(17, 0, 0),
    ),
)

Edge Cases

  • Day 31: Skipped in months with < 31 days (Feb, Apr, Jun, Sep, Nov)
  • Day 30: Skipped in February
  • Day 29: Skipped in non-leap-year February
  • Negative days: -1 in January (31 days) = Jan 31, -1 in February (28 days) = Feb 28

Usage Examples

Daily Report

j, err := s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(
        gocron.NewAtTime(9, 0, 0),
    )),
    gocron.NewTask(func() {
        generateDailyReport()
    }),
    gocron.WithName("daily-report"),
)

Weekly Cleanup

j, err := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Sunday),
        gocron.NewAtTimes(gocron.NewAtTime(2, 0, 0)),
    ),
    gocron.NewTask(func() {
        cleanupOldData()
    }),
    gocron.WithName("weekly-cleanup"),
)

Monthly Billing

j, err := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(1),
        gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
    ),
    gocron.NewTask(func() {
        processMonthlyBilling()
    }),
    gocron.WithName("monthly-billing"),
)

End of Month Report

j, err := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(-1), // last day of month
        gocron.NewAtTimes(gocron.NewAtTime(23, 0, 0)),
    ),
    gocron.NewTask(func() {
        generateMonthEndReport()
    }),
    gocron.WithName("month-end-report"),
)

Multiple Times Per Day

j, err := s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(
        gocron.NewAtTime(9, 0, 0),
        gocron.NewAtTime(12, 0, 0),
        gocron.NewAtTime(15, 0, 0),
        gocron.NewAtTime(18, 0, 0),
    )),
    gocron.NewTask(func() {
        syncData()
    }),
)

Timezone Handling

All time-based schedules respect the scheduler's location set via WithLocation. Default is time.Local.

// Scheduler in Chicago time
loc, _ := time.LoadLocation("America/Chicago")
s, _ := gocron.NewScheduler(gocron.WithLocation(loc))

// All jobs use Chicago time
j, _ := s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0))),
    gocron.NewTask(doTask),
) // Runs at 9 AM Chicago time

See Also

  • Duration Jobs - Fixed intervals
  • Cron Jobs - Cron expressions
  • One-Time Jobs - Run once
  • Creating Schedulers - WithLocation
  • Timing Options - Start/stop times
  • Advanced Scheduling Guide - Edge cases

Install with Tessl CLI

npx tessl i tessl/golang-github-com-go-co-op-gocron-v2

docs

api

jobs

cron.md

duration.md

one-time.md

time-based.md

errors.md

quick-reference.md

tasks.md

index.md

tile.json