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.
gocron v2
A Go job scheduling library that runs functions at pre-determined intervals using cron expressions, fixed durations, daily/weekly/monthly schedules, or one-time execution. Includes distributed deployment support.
Package: github.com/go-co-op/gocron/v2
Install: go get github.com/go-co-op/gocron/v2@v2.19.1
Min Go: 1.21.4
Import: import "github.com/go-co-op/gocron/v2"
Quick Start
s, err := gocron.NewScheduler()
if err != nil {
panic(err)
}
defer s.Shutdown()
// Add job
j, err := s.NewJob(
gocron.DurationJob(5*time.Second),
gocron.NewTask(func() {
fmt.Println("running")
}),
)
s.Start()
select {} // blockCommon Patterns
// Fixed interval
gocron.DurationJob(5 * time.Minute)
// Cron expression
gocron.CronJob("*/5 * * * *", false)
// Daily at specific times
gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)))
// Task with parameters
gocron.NewTask(func(msg string, n int) {
fmt.Println(msg, n)
}, "hello", 42)
// Job options
s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(myFunc),
gocron.WithName("my-job"),
gocron.WithTags("worker", "cleanup"),
gocron.WithSingletonMode(gocron.LimitModeReschedule),
)Decision Guides
I need to schedule a job...
...every N seconds/minutes/hours → DurationJob for fixed intervals → DurationRandomJob for jittered intervals
...at specific times (9 AM, every Monday, etc.) → CronJob for cron expressions → DailyJob for daily schedules → WeeklyJob for weekly schedules → MonthlyJob for monthly schedules
...just once → OneTimeJob
I need to prevent concurrent executions
→ Singleton Mode Guide — Prevent job from running with itself → Scheduler Limits Guide — Limit total concurrent jobs
I need to deploy across multiple instances
→ Leader Election Guide — Simple, all-or-nothing → Distributed Locking Guide — Per-job locking
I need observability
→ Logging Guide — Internal logging → Metrics Guide — Prometheus, StatsD integration → Lifecycle Monitoring Guide — Detailed events
Core Concepts
Scheduler
The main orchestrator. Create with NewScheduler, add jobs, call Start(), clean up with Shutdown().
Quick reference: Creating Schedulers | Managing Jobs | Lifecycle
Job Definition
Defines when a job runs: duration-based, cron-based, time-based, or one-time.
Quick reference: Duration Jobs | Cron Jobs | Time-Based Jobs | One-Time Jobs
Task
Defines what to run. Wrap any function with NewTask:
task := gocron.NewTask(func(ctx context.Context, msg string) {
fmt.Println(msg)
}, "hello")Context is auto-injected if first parameter is context.Context.
Quick reference: Tasks API
Job Options
Configure how a job runs: identity, concurrency, lifecycle, events, distributed settings.
Quick reference: Identity Options | Concurrency Options | Timing Options | Event Options | Distributed Options
Essential Patterns
Prevent Overlapping Runs
j, _ := s.NewJob(
gocron.DurationJob(30*time.Second),
gocron.NewTask(func() {
time.Sleep(time.Minute) // takes longer than interval
}),
gocron.WithSingletonMode(gocron.LimitModeReschedule),
)Learn more: Singleton Mode Guide
Graceful Shutdown
s, _ := gocron.NewScheduler(
gocron.WithStopTimeout(30*time.Second),
)
defer s.Shutdown()
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
defer cancel()
go func() {
<-ctx.Done()
if err := s.Shutdown(); err != nil {
log.Printf("Shutdown error: %v", err)
}
}()
s.Start()
select {} // block until shutdownLearn more: Graceful Shutdown Guide
Distributed Deployment
// Leader election (simple)
s, _ := gocron.NewScheduler(
gocron.WithDistributedElector(myElector),
)
// OR distributed locking (per-job)
s, _ := gocron.NewScheduler(
gocron.WithDistributedLocker(myLocker),
)Learn more: Leader Election | Distributed Locking
Event Handling
j, _ := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(myFunc),
gocron.WithEventListeners(
gocron.BeforeJobRuns(func(jobID uuid.UUID, jobName string) {
log.Printf("Starting %s", jobName)
}),
gocron.AfterJobRunsWithError(func(jobID uuid.UUID, jobName string, err error) {
log.Printf("Failed %s: %v", jobName, err)
}),
),
)Learn more: Event Options
Timezone-Aware Scheduling
// Scheduler timezone
loc, _ := time.LoadLocation("America/Chicago")
s, _ := gocron.NewScheduler(gocron.WithLocation(loc))
// Per-job timezone (cron only)
j, _ := s.NewJob(
gocron.CronJob("TZ=America/New_York 0 9 * * *", false),
gocron.NewTask(doWork),
)Learn more: Time-Based Scheduling Guide
Error Handling
All errors are sentinel values; use errors.Is:
j, err := s.NewJob(
gocron.CronJob("invalid", false),
gocron.NewTask(myFunc),
)
if err != nil {
if errors.Is(err, gocron.ErrCronJobParse) {
// handle invalid cron
}
return err
}Complete reference: Errors
Documentation Organization
Quick References
- API Quick Reference — Common operations cheat sheet
- Common Patterns — Frequently used code patterns
API Documentation
Complete API reference organized by category:
- Scheduler API — Creating, configuring, managing
- Job Definitions — When to run jobs
- Job Options — How to configure jobs
- Tasks — What to run
- Types & Interfaces — Core types, monitors, distributed interfaces
- Errors — All error codes
Guides
Task-oriented guides for common scenarios:
Getting Started
Jobs
Concurrency
Distributed
Observability
Advanced
Examples
Practical code examples organized by use case:
By Task
By Feature
By Scenario
Next Steps
- New to gocron? Start with Quick Start Guide
- Migrating code? See Common Patterns
- Need specific API? Check API Quick Reference
- Complex scheduling? See Time-Based Scheduling
- Going distributed? Read Leader Election or Distributed Locking
- Troubleshooting? Check Error Reference or Troubleshooting Guide
Install with Tessl CLI
npx tessl i tessl/golang-github-com-go-co-op-gocron-v2@2.19.1- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
