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.
jobs.mddocs/guides/api/
API Reference: Jobs
Quick reference for job definitions and operations.
Job Definitions
Specify when a job runs.
Duration-Based
// Fixed interval
gocron.DurationJob(5*time.Minute)
// Random interval (jittered)
gocron.DurationRandomJob(time.Minute, 5*time.Minute)Cron-Based
// Standard cron
gocron.CronJob("*/5 * * * *", false)
// With seconds
gocron.CronJob("*/30 * * * * *", true)
// With timezone
gocron.CronJob("TZ=America/New_York 0 9 * * *", false)See Cron Jobs API
Time-Based
// Daily at specific times
gocron.DailyJob(
1, // every day
gocron.NewAtTimes(
gocron.NewAtTime(9, 0, 0),
gocron.NewAtTime(17, 0, 0),
),
)
// Weekly on specific days
gocron.WeeklyJob(
1, // every week
gocron.NewWeekdays(time.Monday, time.Friday),
gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)),
)
// Monthly on specific days
gocron.MonthlyJob(
1, // every month
gocron.NewDaysOfTheMonth(1, 15),
gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
)One-Time
gocron.OneTimeJob(
gocron.OneTimeJobStartDateTime(
time.Now().Add(time.Hour),
),
)Tasks
Specify what to run.
Basic Task
task := gocron.NewTask(func() {
doWork()
})Task with Parameters
task := gocron.NewTask(func(msg string, count int) {
fmt.Printf("%s: %d\n", msg, count)
}, "hello", 42)Task with Context
task := gocron.NewTask(func(ctx context.Context) {
select {
case <-ctx.Done():
log.Println("Cancelled")
return
default:
doWork()
}
})Task with Error
task := gocron.NewTask(func() error {
if err := doWork(); err != nil {
return fmt.Errorf("work failed: %w", err)
}
return nil
})See Tasks API
Job Operations
Create Job
j, err := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(myFunc),
gocron.WithName("my-job"),
gocron.WithTags("worker"),
)Job Information
id := j.ID()
name := j.Name()
tags := j.Tags()
nextRun, err := j.NextRun()
lastRun, err := j.LastRun()Run Job Manually
err := j.RunNow()Triggers immediate execution outside of schedule.
Update Job
newJob, err := s.Update(
j.ID(),
gocron.DurationJob(5*time.Minute), // New interval
gocron.NewTask(myFunc),
)Remove Job
err := s.RemoveJob(j.ID())Job Options
Identity
gocron.WithName("job-name")
gocron.WithTags("tag1", "tag2")Concurrency
gocron.WithSingletonMode(gocron.LimitModeReschedule)
gocron.WithIntervalFromCompletion()Timing
gocron.WithStartAt(gocron.WithStartImmediately())
gocron.WithLimitRunsTo(100)Events
gocron.WithEventListeners(
gocron.BeforeJobRuns(func(jobID uuid.UUID, jobName string) {
log.Printf("Starting: %s", jobName)
}),
gocron.AfterJobRuns(func(jobID uuid.UUID, jobName string) {
log.Printf("Completed: %s", jobName)
}),
gocron.AfterJobRunsWithError(func(jobID uuid.UUID, jobName string, err error) {
log.Printf("Failed: %s - %v", jobName, err)
}),
)Distributed
gocron.WithDistributedJobLocker(locker)Example: Complete Job Setup
j, err := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(func(ctx context.Context) error {
select {
case <-ctx.Done():
return ctx.Err()
default:
if err := doWork(); err != nil {
return fmt.Errorf("work failed: %w", err)
}
return nil
}
}),
gocron.WithName("worker"),
gocron.WithTags("background", "worker"),
gocron.WithSingletonMode(gocron.LimitModeReschedule),
gocron.WithEventListeners(
gocron.AfterJobRunsWithError(func(jobID uuid.UUID, jobName string, err error) {
log.Printf("Job %s failed: %v", jobName, err)
}),
),
)
if err != nil {
log.Fatal(err)
}
log.Printf("Job created: %s (next run: %v)", j.Name(), j.NextRun())See Also
Install with Tessl CLI
npx tessl i tessl/golang-github-com-go-co-op-gocron-v2docs
api
examples
guides