gormlock

README

gocron-gorm-lock

A gocron locker implementation using gorm

install

go get github.com/go-co-op/gocron-gorm-lock

usage

Here is an example usage that would be deployed in multiple instances

package main

import (
	"fmt"

	"github.com/go-co-op/gocron"
	gormlock "github.com/go-co-op/gocron-gorm-lock"
	"gorm.io/gorm"
	"time"
)

func main() {
	var db * gorm.DB // gorm db connection
	var worker string // name of this instance to be used to know which instance run the job
	db.AutoMigrate(&CronJobLock{}) // We need the table to store the job execution
	locker, err := gormlock.NewGormLocker(db, worker)
	if err != nil {
		// handle the error
	}

	s := gocron.NewScheduler(time.UTC)
	s.WithDistributedLocker(locker)

	_, err = s.Every("1s").Name("unique_name").Do(func() {
		// task to do
		fmt.Println("call 1s")
	})
	if err != nil {
		// handle the error
	}

	s.StartBlocking()
}

Prerequisites

• The table cron_job_locks needs to exist in the database. This can be achieved, as an example, using gorm automigrate functionality db.Automigrate(&CronJobLock{})
• In order to uniquely identify the job, the locker uses the unique combination of the job name + timestamp (by default with precision to seconds).

FAQ

• Q: The locker uses the unique combination of the job name + timestamp with seconds precision, how can I change that?
  • A: It's possible to change the timestamp precision used to uniquely identify the job, here is an example to set an hour precision:

    locker, err := gormlock.NewGormLocker(db, "local", gormlock.WithDefaultJobIdentifier(60 * time.Minute))
    

• Q: But what about if we want to write our own implementation:
  • A: It's possible to set how to create the job identifier:

    locker, err := gormlock.NewGormLocker(db, "local",
        gormlock.WithJobIdentifier(
            func(ctx context.Context, key string) string {
                return ...
            },
        ),
    )
    

Documentation

Index

• Variables
• type CronJobLock
  • func (cjb *CronJobLock) GetID() int
  • func (cjb *CronJobLock) SetJobIdentifier(ji string)
• type GormLocker
  • func NewGormLocker(db *gorm.DB, worker string, options ...LockOption) (*GormLocker, error)
  • func (g *GormLocker) Close()
  • func (g *GormLocker) Lock(ctx context.Context, key string) (gocron.Lock, error)
• type JobLock
• type LockOption
  • func WithCleanInterval(interval time.Duration) LockOption
  • func WithDefaultJobIdentifier(precision time.Duration) LockOption
  • func WithJobIdentifier(f func(ctx context.Context, key string) string) LockOption
  • func WithTTL(ttl time.Duration) LockOption

Variables

var (
	StatusRunning  = "RUNNING"
	StatusFinished = "FINISHED"
)

Types

type CronJobLock

type CronJobLock struct {
	ID            int
	CreatedAt     time.Time
	UpdatedAt     time.Time
	JobName       string `gorm:"index:idx_name,unique"`
	JobIdentifier string `gorm:"index:idx_name,unique"`
	Worker        string `gorm:"not null"`
	Status        string `gorm:"not null"`
}

func (*CronJobLock) GetID

func (cjb *CronJobLock) GetID() int

func (*CronJobLock) SetJobIdentifier

func (cjb *CronJobLock) SetJobIdentifier(ji string)

type GormLocker

type GormLocker struct {
	// contains filtered or unexported fields
}

func NewGormLocker

func NewGormLocker(db *gorm.DB, worker string, options ...LockOption) (*GormLocker, error)

func (*GormLocker) Close

func (g *GormLocker) Close()

func (*GormLocker) Lock

func (g *GormLocker) Lock(ctx context.Context, key string) (gocron.Lock, error)

type JobLock

type JobLock[T any] interface {
	GetID() T
	SetJobIdentifier(ji string)
}

type LockOption

type LockOption func(*GormLocker)

func WithCleanInterval

func WithCleanInterval(interval time.Duration) LockOption

WithCleanInterval the time interval to run clean operation.

func WithDefaultJobIdentifier

func WithDefaultJobIdentifier(precision time.Duration) LockOption

func WithJobIdentifier

func WithJobIdentifier(f func(ctx context.Context, key string) string) LockOption

func WithTTL

func WithTTL(ttl time.Duration) LockOption

WithTTL when the locker records in the database exceeds the ttl, it is cleaned up. to avoid excessive data in the database.