Getting started

Table of contents
  1. Getting started
    1. Install
    2. Connections and queues
    3. Create the tables (database driver)
    4. Build the manager
    5. Write and dispatch a job
    6. Run a worker

Install

Go 1.25 or newer.

go get github.com/LouisRiverstone/perago@latest
go install github.com/LouisRiverstone/perago/cmd/perago@latest   # optional: the CLI

perago is split into Go modules so a project downloads only what it uses. The core has no dependencies; each backend is a module you add when you need it:

Module go get Brings in
core github.com/LouisRiverstone/perago nothing: the standard library only. Jobs, workers, chains, batches, middleware, queuetest, console, the database driver and stores (database/sql)
Redis github.com/LouisRiverstone/perago/redis go-redis
SQS github.com/LouisRiverstone/perago/sqs AWS SDK v2 (SQS)
DynamoDB github.com/LouisRiverstone/perago/dynamodb AWS SDK v2 (DynamoDB)
Beanstalkd github.com/LouisRiverstone/perago/beanstalkd go-beanstalk
migro github.com/LouisRiverstone/perago/migro migro: Connect, migrations, model.Of

migro is optional. perago is compatible with migro but never depends on it: the core, the database driver and every other module work without it, on any database/sql connection. Add the perago/migro module only if your project already uses migro, to reuse its connection and transactions, run perago’s tables as migro migrations and serialize migro models with model.Of. Without it, nothing of migro (or GORM) is downloaded. See Using with migro.

Connections and queues

As in Laravel, a connection is a backend (a database, a Redis server, an SQS account) and a queue is a named line of jobs on it. Every connection has a default queue, default unless you set Connection.Queue. A job goes to the default connection and queue unless it says otherwise:

m.Dispatch(&ProcessPodcast{}).Send(ctx)                    // default connection, default queue
m.Dispatch(&ProcessPodcast{}).OnQueue("emails").Send(ctx)  // the "emails" queue

Workers take jobs from the queues you name, in priority order: queue:work --queue=high,default.

Create the tables (database driver)

The database driver needs a jobs table, failed jobs need failed_jobs, batches need job_batches, and the database cache needs cache. Generate a migration for each:

perago make:queue-table --dialect=postgres
perago make:queue-failed-table --dialect=postgres
perago make:queue-batches-table --dialect=postgres
perago make:cache-table --dialect=postgres

They are .sql files for your migration tool. On a project whose go.mod requires migro they are migro migrations instead (run them with migro migration:run); --format=sql|migro picks explicitly.

Or create any missing tables at startup with database.Install(ctx, db, database.Tables{}).

Build the manager

import (
	"database/sql"

	_ "github.com/jackc/pgx/v5/stdlib" // any database/sql driver
	"github.com/LouisRiverstone/perago"
	"github.com/LouisRiverstone/perago/database"
)

sqlDB, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))
db, err := database.New(sqlDB, "postgres")

m, err := perago.New(perago.Config{
	Default: "database",
	Connections: map[string]perago.Connection{
		"database": {Driver: database.NewDriver(db, database.DriverOptions{})},
		"sync":     {Driver: perago.SyncDriver()},
	},
	Failed:  database.NewFailedJobStore(db, ""),
	Batches: database.NewBatchStore(db, ""),
	Cache:   database.NewCache(db, ""),
	Key:     appKey, // 32 bytes, for encrypted jobs
})

When Default is empty, the PERAGO_CONNECTION or QUEUE_CONNECTION environment variable picks the connection, then sync.

Write and dispatch a job

perago make:job ProcessPodcast
type ProcessPodcast struct {
	perago.Queueable
	PodcastID int
}

func init() { perago.Register(&ProcessPodcast{}) }

func (j *ProcessPodcast) Handle(ctx context.Context) error {
	return transcode(ctx, j.PodcastID)
}
id, err := m.Dispatch(&ProcessPodcast{PodcastID: 1}).Send(ctx)

Run a worker

Workers live in your program, because they need your jobs and connections. Add a console command (see Command line):

// cmd/perago/main.go
func main() {
	app := &console.App{Manager: func(ctx context.Context) (*perago.Manager, error) { return app.Queue(ctx) }}
	os.Exit(app.Run(context.Background(), os.Args[1:]))
}
go run ./cmd/perago queue:work
perago queue:work            # the perago CLI forwards to ./cmd/perago

Or run one inside your service, in a goroutine, with m.Work(ctx, perago.WorkerOptions{Queues: []string{"high", "default"}}): your application and the database are then all you need, no Redis and no separate worker process. See Running the worker inside your application and Choosing a backend.