mirror of https://github.com/go-co-op/gocron.git
156 lines
3.3 KiB
Markdown
156 lines
3.3 KiB
Markdown
# Migration Guide: `gocron` v1 → v2
|
|
|
|
This guide helps you migrate your code from the `v1` branch to the `v2` branch of [go-co-op/gocron](https://github.com/go-co-op/gocron).
|
|
Version 2 is a major rewrite focusing on improving the internals of gocron, while also enhancing the user interfaces and error handling.
|
|
All major functionality has been ported over.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
- [Overview of Major Changes](#overview-of-major-changes)
|
|
- [Installation](#installation)
|
|
- [API Changes](#api-changes)
|
|
- [Scheduler Creation](#scheduler-creation)
|
|
- [Job Definition](#job-definition)
|
|
- [Starting and Stopping the Scheduler](#starting-and-stopping-the-scheduler)
|
|
- [Error Handling](#error-handling)
|
|
- [Distributed Scheduling](#distributed-scheduling)
|
|
- [Examples Migration](#examples-migration)
|
|
- [Testing and Validation](#testing-and-validation)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [References](#references)
|
|
|
|
---
|
|
|
|
## Overview of Major Changes
|
|
|
|
- **Breaking API changes**: All major interfaces and types have changed.
|
|
- **Improved error reporting**: Most functions now return errors.
|
|
- **Job IDs and cancellation**: Jobs have unique IDs and can be cancelled.
|
|
- **Distributed and monitored scheduling**: Built-in support for distributed schedulers and job monitors.
|
|
- **Context and logging enhancements**: Improved support for cancellation, context, and custom logging interfaces.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Update your dependency to v2:
|
|
|
|
```sh
|
|
go get github.com/go-co-op/gocron/v2
|
|
```
|
|
|
|
**Note:** The import path is `github.com/go-co-op/gocron/v2`.
|
|
|
|
---
|
|
|
|
## API Changes
|
|
|
|
### 1. Scheduler Creation
|
|
|
|
**v1:**
|
|
```go
|
|
import "github.com/go-co-op/gocron"
|
|
|
|
s := gocron.NewScheduler(time.UTC)
|
|
```
|
|
|
|
**v2:**
|
|
```go
|
|
import "github.com/go-co-op/gocron/v2"
|
|
|
|
s, err := gocron.NewScheduler()
|
|
if err != nil { panic(err) }
|
|
```
|
|
- **v2** returns an error on creation.
|
|
- **v2** does not require a location/timezone argument. Use `WithLocation()` if needed.
|
|
|
|
---
|
|
|
|
### 2. Job Creation
|
|
|
|
**v1:**
|
|
```go
|
|
s.Every(1).Second().Do(taskFunc)
|
|
```
|
|
|
|
**v2:**
|
|
```go
|
|
j, err := s.NewJob(
|
|
gocron.DurationJob(1*time.Second),
|
|
gocron.NewTask(taskFunc),
|
|
)
|
|
if err != nil { panic(err) }
|
|
```
|
|
- **v2** uses explicit job types (`DurationJob`, `CronJob`, etc).
|
|
- **v2** jobs have unique IDs: `j.ID()`.
|
|
- **v2** returns an error on job creation.
|
|
|
|
#### Cron Expressions
|
|
|
|
**v1:**
|
|
```go
|
|
s.Cron("*/5 * * * *").Do(taskFunc)
|
|
```
|
|
|
|
**v2:**
|
|
```go
|
|
j, err := s.NewJob(
|
|
gocron.CronJob("*/5 * * * *"),
|
|
gocron.NewTask(taskFunc),
|
|
)
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
**v1:**
|
|
```go
|
|
s.Every(1).Second().Do(taskFunc, arg1, arg2)
|
|
```
|
|
|
|
**v2:**
|
|
```go
|
|
j, err := s.NewJob(
|
|
gocron.DurationJob(1*time.Second),
|
|
gocron.NewTask(taskFunc, arg1, arg2),
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
### 3. Starting and Stopping the Scheduler
|
|
|
|
**v1:**
|
|
```go
|
|
s.StartAsync()
|
|
s.Stop()
|
|
```
|
|
|
|
**v2:**
|
|
```go
|
|
s.Start()
|
|
s.Shutdown()
|
|
```
|
|
|
|
- Always call `Shutdown()` for graceful cleanup.
|
|
|
|
---
|
|
|
|
### 4. Error Handling
|
|
|
|
- Most v2 methods return errors. Always check `err`.
|
|
- Use `errors.go` for error definitions.
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- [v2 API Documentation](https://pkg.go.dev/github.com/go-co-op/gocron/v2)
|
|
- [Examples](https://pkg.go.dev/github.com/go-co-op/gocron/v2#pkg-examples)
|
|
- [Release Notes](https://github.com/go-co-op/gocron/releases)
|
|
|
|
---
|
|
|
|
**If you encounter issues, open a GitHub Issue or consider contributing a fix by checking out the [CONTRIBUTING.md](CONTRIBUTING.md) guide.**
|