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.
identity.mddocs/api/options/
Identity Options
Options for naming and identifying jobs.
WithName
func WithName(name string) JobOptionSets a human-readable name. Defaults to qualified function name (e.g., pkg.myFunc).
Parameters:
name: Must not be empty
Errors:
ErrWithNameEmpty: name is empty string
Uses:
- Distributed locking lock key
- Monitoring/logging callbacks
- Human readability
j, _ := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(myFunc),
gocron.WithName("database-cleanup"),
)
fmt.Println(j.Name()) // "database-cleanup"Important: Use stable names for distributed locks so the same job across instances uses the same key.
WithTags
func WithTags(tags ...string) JobOptionAssigns string tags for grouping and bulk operations.
Uses:
Scheduler.RemoveByTags()for bulk removal- Passed to monitoring callbacks
- Arbitrary categorization (environment, priority, function, system)
j, _ := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(myFunc),
gocron.WithTags("worker", "cleanup", "database"),
)
// Remove all cleanup jobs
s.RemoveByTags("cleanup")Tag Merging
When both global and per-job tags are set, they are merged.
s, _ := gocron.NewScheduler(
gocron.WithGlobalJobOptions(
gocron.WithTags("production"),
),
)
j, _ := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(myFunc),
gocron.WithTags("critical"), // job has both "production" and "critical"
)WithIdentifier
func WithIdentifier(id uuid.UUID) JobOptionSets a specific UUID instead of random generation.
Parameters:
id: Must not beuuid.Nil
Errors:
ErrWithIdentifierNil: id isuuid.Nil
Uses:
- Deterministic IDs for testing
- Persisting job IDs across restarts
- Cross-system job identification
id := uuid.MustParse("123e4567-e89b-12d3-a456-426614174000")
j, _ := s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(myFunc),
gocron.WithIdentifier(id),
)
// Later: update using known ID
s.Update(id, gocron.DurationJob(2*time.Minute), gocron.NewTask(myFunc))Warning: You must ensure ID uniqueness. Reusing during updates is fine; creating multiple jobs with same ID is undefined.
Usage Examples
Named Job with Tags
j, _ := s.NewJob(
gocron.DurationJob(5*time.Minute),
gocron.NewTask(func() {
cleanupOldRecords()
}),
gocron.WithName("cleanup-old-records"),
gocron.WithTags("cleanup", "database", "maintenance"),
)Remove Jobs by Tag
// Create multiple jobs with tags
s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(task1),
gocron.WithTags("worker", "high-priority"),
)
s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(task2),
gocron.WithTags("worker", "low-priority"),
)
s.NewJob(
gocron.DurationJob(time.Minute),
gocron.NewTask(task3),
gocron.WithTags("cleanup"),
)
// Remove all worker jobs
s.RemoveByTags("worker")
// Remove only high-priority workers (requires ALL tags)
s.RemoveByTags("worker", "high-priority")Persistent Job IDs
// Save job ID to database
savedID := uuid.New()
j, _ := s.NewJob(
gocron.DurationJob(time.Hour),
gocron.NewTask(myFunc),
gocron.WithIdentifier(savedID),
)
saveToDatabase(savedID)
// Later: retrieve and update
id := loadFromDatabase()
s.Update(
id,
gocron.DurationJob(2*time.Hour),
gocron.NewTask(myFunc),
)See Also
- Concurrency Options - Control execution
- Timing Options - Start/stop times
- Event Listeners - Callbacks and monitoring
- Managing Jobs - RemoveByTags
Install with Tessl CLI
npx tessl i tessl/golang-github-com-go-co-op-gocron-v2@2.19.1docs
api
examples
guides