chrono

README

lesiw.io/chrono

A simple cronjob scheduler to handle job execution across multiple running copies of an application. Currently only github.com/jackc/pgx/v5 is supported as a backing store.

Instead of goroutines, lesiw.io/chrono schedules chronoroutines. Like goroutines, chronoroutines have a deliberately simple API and offer little configuration about how they are executed beyond their cron expression.

If a node dies partway through job execution, the job will be restarted by another node after a minute of missing heartbeats.

Jobs do not immediately fire upon being scheduled. However, if lesiw.io/chrono detects that a cron tick was missed, it will execute the missed job immediately.

For assistance with crontab syntax, check out https://crontab.guru.

Minimal example

package main

import (
    "context"
    "log"

    "github.com/jackc/pgx/v5"
    "lesiw.io/chrono"
)

func main() {
    conn, err := pgx.Connect(context.Background(), "")
    if err != nil {
        log.Fatal(err)
    }
    cron := chrono.Pgx{Conn: conn}
    if err := cron.Start(); err != nil {
        log.Fatal(err)
    }
    err = cron.Go("example", "* * * * *", func() { println("hello world!") })
    if err != nil {
        log.Fatal(err)
    }
    select {}
}

A docker compose example is available under internal/example. Run docker compose up to build it.

Documentation

Overview

Package chrono schedules durable cron jobs backed by data stores.

Index

• type Pgx
  • func (p *Pgx) Go(name, cron string, f func()) error
  • func (p *Pgx) Start() (err error)
• type PgxConn

Types

type Pgx

type Pgx struct {
	Conn PgxConn
	Log  io.Writer
	// contains filtered or unexported fields
}

Pgx is a PostgreSQL-backed scheduler.

The Conn field is required and should be a pgx.Conn or pgxpool.Pool.

cron := chrono.Pgx{Conn: conn}
if err := cron.Start(); err != nil {
	log.Fatal(err)
}

func (*Pgx) Go

func (p *Pgx) Go(name, cron string, f func()) error

Go schedules a task.

name is the unique identifier for this task.

The task will run on the next tick of the cron expression. If Pgx detects a missed cron tick, it runs the task immediately.

func (*Pgx) Start

func (p *Pgx) Start() (err error)

Start initializes a Pgx scheduler.

type PgxConn

type PgxConn interface {
	Begin(ctx context.Context) (pgx.Tx, error)
	Exec(ctx context.Context, sql string, arguments ...any) (
		pgconn.CommandTag, error)
}

A PgxConn is a pgx.Conn or pgxpool.Pool.