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-scheduling.mddocs/examples/by-task/

Time-Based Scheduling Examples

Schedule jobs at specific times using DailyJob, WeeklyJob, and MonthlyJob.

DailyJob Examples

Every Day at 9 AM

j, _ := s.NewJob(
    gocron.DailyJob(
        1,
        gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)),
    ),
    gocron.NewTask(doMorningTask),
)

Every Day at Multiple Times

// Every day at 9 AM and 5 PM
j, _ := s.NewJob(
    gocron.DailyJob(
        1,
        gocron.NewAtTimes(
            gocron.NewAtTime(9, 0, 0),
            gocron.NewAtTime(17, 0, 0),
        ),
    ),
    gocron.NewTask(doReport),
)

Every 2 Days at Noon

j, _ := s.NewJob(
    gocron.DailyJob(2, gocron.NewAtTimes(gocron.NewAtTime(12, 0, 0))),
    gocron.NewTask(doBiDailyTask),
)

Midnight Task

j, _ := s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0))),
    gocron.NewTask(doMidnightRollover),
)

Precise Time with Seconds

// 9:30:15 AM
j, _ := s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(9, 30, 15))),
    gocron.NewTask(doPreciseTask),
)

Start Immediately if Time Hasn't Passed

// If created before 9 AM, runs today at 9 AM
// If created after 9 AM, runs tomorrow at 9 AM
j, _ := s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0))),
    gocron.NewTask(doMorningTask),
    gocron.WithStartAt(gocron.WithStartImmediately()),
)

Morning and Evening Reports

// 8 AM and 8 PM daily
j, _ := s.NewJob(
    gocron.DailyJob(
        1,
        gocron.NewAtTimes(
            gocron.NewAtTime(8, 0, 0),
            gocron.NewAtTime(20, 0, 0),
        ),
    ),
    gocron.NewTask(func() {
        hour := time.Now().Hour()
        if hour < 12 {
            fmt.Println("Morning report")
        } else {
            fmt.Println("Evening report")
        }
        generateReport()
    }),
    gocron.WithName("daily-reports"),
)

WeeklyJob Examples

Every Monday at 9 AM

j, _ := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Monday),
        gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)),
    ),
    gocron.NewTask(doMondayTask),
)

Multiple Days Per Week

// Monday and Wednesday at 9 AM
j, _ := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Monday, time.Wednesday),
        gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)),
    ),
    gocron.NewTask(doWeekdayTask),
)

Multiple Days and Times

// Monday and Friday at 9 AM and 5 PM
j, _ := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Monday, time.Friday),
        gocron.NewAtTimes(
            gocron.NewAtTime(9, 0, 0),
            gocron.NewAtTime(17, 0, 0),
        ),
    ),
    gocron.NewTask(doTask),
)
// Runs 4 times per week

Every 2 Weeks on Friday

j, _ := s.NewJob(
    gocron.WeeklyJob(
        2,
        gocron.NewWeekdays(time.Friday),
        gocron.NewAtTimes(gocron.NewAtTime(17, 0, 0)),
    ),
    gocron.NewTask(doBiWeeklyTask),
)

Weekday Morning Standup

j, _ := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(
            time.Monday,
            time.Tuesday,
            time.Wednesday,
            time.Thursday,
            time.Friday,
        ),
        gocron.NewAtTimes(gocron.NewAtTime(9, 30, 0)),
    ),
    gocron.NewTask(sendStandupReminder),
)

Weekend Task

j, _ := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Saturday, time.Sunday),
        gocron.NewAtTimes(gocron.NewAtTime(10, 0, 0)),
    ),
    gocron.NewTask(doWeekendMaintenance),
)

Align to Specific Week

// Align to last Monday
lastMonday := time.Now()
for lastMonday.Weekday() != time.Monday {
    lastMonday = lastMonday.AddDate(0, 0, -1)
}

j, _ := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Monday),
        gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0)),
    ),
    gocron.NewTask(doWeeklyReport),
    gocron.WithStartAt(gocron.WithStartDateTimePast(lastMonday)),
)

Team Meeting Schedule

// Monday standup, Wednesday sync, Friday retrospective
j, _ := s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Monday, time.Wednesday, time.Friday),
        gocron.NewAtTimes(gocron.NewAtTime(10, 0, 0)),
    ),
    gocron.NewTask(func() {
        day := time.Now().Weekday()
        switch day {
        case time.Monday:
            sendMeetingReminder("standup")
        case time.Wednesday:
            sendMeetingReminder("sync")
        case time.Friday:
            sendMeetingReminder("retrospective")
        }
    }),
    gocron.WithName("team-meetings"),
)

MonthlyJob Examples

First Day of Month at Noon

j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(1),
        gocron.NewAtTimes(gocron.NewAtTime(12, 0, 0)),
    ),
    gocron.NewTask(doMonthlyTask),
)

Multiple Days Per Month

// 1st and 15th at noon
j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(1, 15),
        gocron.NewAtTimes(gocron.NewAtTime(12, 0, 0)),
    ),
    gocron.NewTask(doTwiceMonthly),
)

Last Day of Month

// -1 = last day (adjusts for month length)
j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(-1),
        gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
    ),
    gocron.NewTask(doEndOfMonth),
)
// Runs: Jan 31, Feb 28/29, Mar 31, Apr 30, May 31, etc.

Days Before End of Month

// 5 days before end of month
j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(-5),
        gocron.NewAtTimes(gocron.NewAtTime(10, 0, 0)),
    ),
    gocron.NewTask(sendReminder),
)
// Runs: Jan 27, Feb 24/25, Mar 27, Apr 26, etc.

Quarterly Task

// Every 3 months on the 1st at midnight
j, _ := s.NewJob(
    gocron.MonthlyJob(
        3,
        gocron.NewDaysOfTheMonth(1),
        gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
    ),
    gocron.NewTask(doQuarterlyTask),
)

Fiscal Quarter End

// Last day of Mar, Jun, Sep, Dec
startDate := time.Date(time.Now().Year(), 3, 31, 23, 59, 0, 0, time.Local)

j, _ := s.NewJob(
    gocron.MonthlyJob(
        3,
        gocron.NewDaysOfTheMonth(-1),
        gocron.NewAtTimes(gocron.NewAtTime(23, 59, 0)),
    ),
    gocron.NewTask(doQuarterEndReport),
    gocron.WithStartAt(gocron.WithStartDateTime(startDate)),
)

Mid-Month Report

// 15th of every month at 3 PM
j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(15),
        gocron.NewAtTimes(gocron.NewAtTime(15, 0, 0)),
    ),
    gocron.NewTask(doMidMonthReport),
)

Payroll Schedule

// 25th and last day of month at 6 AM
j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(25, -1),
        gocron.NewAtTimes(gocron.NewAtTime(6, 0, 0)),
    ),
    gocron.NewTask(processPayroll),
)

Handle Short Months

// 31st of every month (skips Feb, Apr, Jun, Sep, Nov)
j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(31),
        gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
    ),
    gocron.NewTask(doTask),
)
// Only runs in Jan, Mar, May, Jul, Aug, Oct, Dec

Billing Cycle

// First day of month for billing
j, _ := s.NewJob(
    gocron.MonthlyJob(
        1,
        gocron.NewDaysOfTheMonth(1),
        gocron.NewAtTimes(gocron.NewAtTime(2, 0, 0)),
    ),
    gocron.NewTask(func() {
        fmt.Println("Processing monthly billing")
        processBilling()
        sendInvoices()
    }),
    gocron.WithName("monthly-billing"),
)

Complex Time Patterns

Business Hours Only

// Weekdays 9 AM to 5 PM every hour
for hour := 9; hour <= 17; hour++ {
    h := hour // capture for closure
    s.NewJob(
        gocron.WeeklyJob(
            1,
            gocron.NewWeekdays(
                time.Monday, time.Tuesday, time.Wednesday,
                time.Thursday, time.Friday,
            ),
            gocron.NewAtTimes(gocron.NewAtTime(uint(h), 0, 0)),
        ),
        gocron.NewTask(func() {
            fmt.Printf("Business hours check at %d:00\n", h)
        }),
    )
}

Seasonal Schedule

// Summer hours (May-Aug): daily at 8 AM
summerStart := time.Date(time.Now().Year(), 5, 1, 8, 0, 0, 0, time.Local)
summerEnd := time.Date(time.Now().Year(), 9, 1, 0, 0, 0, 0, time.Local)

j, _ := s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(8, 0, 0))),
    gocron.NewTask(doSummerTask),
    gocron.WithStartAt(gocron.WithStartDateTime(summerStart)),
    gocron.WithStopAt(gocron.WithStopDateTime(summerEnd)),
)

// Winter hours (Nov-Feb): daily at 9 AM
winterStart := time.Date(time.Now().Year(), 11, 1, 9, 0, 0, 0, time.Local)
winterEnd := time.Date(time.Now().Year()+1, 3, 1, 0, 0, 0, 0, time.Local)

j, _ = s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0))),
    gocron.NewTask(doWinterTask),
    gocron.WithStartAt(gocron.WithStartDateTime(winterStart)),
    gocron.WithStopAt(gocron.WithStopDateTime(winterEnd)),
)

Backup Schedule

// Incremental: every 6 hours
j, _ := s.NewJob(
    gocron.DurationJob(6*time.Hour),
    gocron.NewTask(doIncrementalBackup),
    gocron.WithName("incremental-backup"),
    gocron.WithTags("backup"),
)

// Daily full backup at 2 AM
j, _ = s.NewJob(
    gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(2, 0, 0))),
    gocron.NewTask(doFullBackup),
    gocron.WithName("daily-backup"),
    gocron.WithTags("backup"),
)

// Weekly verification on Sunday at 3 AM
j, _ = s.NewJob(
    gocron.WeeklyJob(
        1,
        gocron.NewWeekdays(time.Sunday),
        gocron.NewAtTimes(gocron.NewAtTime(3, 0, 0)),
    ),
    gocron.NewTask(verifyBackups),
    gocron.WithName("backup-verification"),
    gocron.WithTags("backup"),
)

Timezone Examples

Scheduler Timezone

// All jobs use New York time
loc, _ := time.LoadLocation("America/New_York")
s, _ := gocron.NewScheduler(gocron.WithLocation(loc))

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

Multi-Region Schedule

// Create regional schedulers
regions := map[string]string{
    "us-east":    "America/New_York",
    "us-west":    "America/Los_Angeles",
    "eu-central": "Europe/Berlin",
    "asia-east":  "Asia/Tokyo",
}

for region, tz := range regions {
    loc, _ := time.LoadLocation(tz)
    s, _ := gocron.NewScheduler(gocron.WithLocation(loc))

    s.NewJob(
        gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0))),
        gocron.NewTask(func(r string) {
            fmt.Printf("Morning task for %s\n", r)
            doRegionalTask(r)
        }, region),
        gocron.WithName(fmt.Sprintf("morning-%s", region)),
    )

    s.Start()
}

Complete Time-Based Example

package main

import (
    "fmt"
    "os"
    "os/signal"
    "syscall"
    "time"

    "github.com/go-co-op/gocron/v2"
)

func main() {
    // Create scheduler with timezone
    loc, _ := time.LoadLocation("America/New_York")
    s, err := gocron.NewScheduler(gocron.WithLocation(loc))
    if err != nil {
        panic(err)
    }
    defer s.Shutdown()

    // Daily morning report at 9 AM
    s.NewJob(
        gocron.DailyJob(1, gocron.NewAtTimes(gocron.NewAtTime(9, 0, 0))),
        gocron.NewTask(func() {
            fmt.Println("Morning report at 9 AM")
        }),
        gocron.WithName("morning-report"),
    )

    // Weekly team meeting: Monday at 10 AM
    s.NewJob(
        gocron.WeeklyJob(
            1,
            gocron.NewWeekdays(time.Monday),
            gocron.NewAtTimes(gocron.NewAtTime(10, 0, 0)),
        ),
        gocron.NewTask(func() {
            fmt.Println("Weekly team meeting")
        }),
        gocron.WithName("team-meeting"),
    )

    // Monthly billing: 1st of month at midnight
    s.NewJob(
        gocron.MonthlyJob(
            1,
            gocron.NewDaysOfTheMonth(1),
            gocron.NewAtTimes(gocron.NewAtTime(0, 0, 0)),
        ),
        gocron.NewTask(func() {
            fmt.Println("Processing monthly billing")
        }),
        gocron.WithName("monthly-billing"),
    )

    // End of month cleanup: last day at 11 PM
    s.NewJob(
        gocron.MonthlyJob(
            1,
            gocron.NewDaysOfTheMonth(-1),
            gocron.NewAtTimes(gocron.NewAtTime(23, 0, 0)),
        ),
        gocron.NewTask(func() {
            fmt.Println("End of month cleanup")
        }),
        gocron.WithName("month-end-cleanup"),
    )

    // Weekday morning standup: Mon-Fri at 9:30 AM
    s.NewJob(
        gocron.WeeklyJob(
            1,
            gocron.NewWeekdays(
                time.Monday, time.Tuesday, time.Wednesday,
                time.Thursday, time.Friday,
            ),
            gocron.NewAtTimes(gocron.NewAtTime(9, 30, 0)),
        ),
        gocron.NewTask(func() {
            fmt.Println("Standup reminder")
        }),
        gocron.WithName("standup"),
    )

    // Start scheduler
    s.Start()
    fmt.Println("Scheduler started")

    // Print schedule
    for _, j := range s.Jobs() {
        nextRun, _ := j.NextRun()
        fmt.Printf("%s: next run at %v\n", j.Name(), nextRun)
    }

    // Wait for interrupt
    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
    <-sigCh

    fmt.Println("Shutting down...")
}

Related Documentation

  • API: Job Definitions — DailyJob, WeeklyJob, MonthlyJob
  • Guide: Advanced Scheduling
  • Examples: Cron Scheduling
  • Examples: One-Time Jobs

Install with Tessl CLI

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

docs

examples

by-task

cron-scheduling.md

interval-scheduling.md

one-time-jobs.md

time-based-scheduling.md

index.md

tile.json