riverqueue/river — v0.49.0 snapshot¶
Pinned: v0.49.0 Source: tagged source
Key API surface¶
Client¶
client, err := river.NewClient(riverpgxv5.New(pool), &river.Config{
Queues: map[string]river.QueueConfig{
river.QueueDefault: {MaxWorkers: 100},
},
Workers: river.NewWorkers(),
Logger: slog.Default(),
})
// Start / stop
err = client.Start(ctx)
err = client.Stop(ctx)
Defining a worker¶
type MyArgs struct {
UserID int64 `json:"user_id"`
}
func (MyArgs) Kind() string { return "my_job" }
type MyWorker struct {
river.WorkerDefaults[MyArgs]
}
func (w *MyWorker) Work(ctx context.Context, job *river.Job[MyArgs]) error {
// do work
return nil
}
// Register
river.AddWorker(workers, &MyWorker{})
Inserting jobs¶
// Direct insert
_, err = client.Insert(ctx, MyArgs{UserID: 42}, nil)
// In a transaction
_, err = client.InsertTx(ctx, tx, MyArgs{UserID: 42}, &river.InsertOpts{
Queue: river.QueueDefault,
Priority: 1,
MaxAttempts: 5,
ScheduledAt: clk.Now().Add(5 * time.Minute),
})
Periodic jobs¶
periodicJob := river.NewPeriodicJob(
river.PeriodicInterval(15*time.Minute),
func() (river.JobArgs, *river.InsertOpts) {
return MyArgs{}, nil
},
&river.PeriodicJobOpts{RunOnStart: true},
)
Put periodicJob in river.Config.PeriodicJobs at construction time. Dynamic
registration uses client.PeriodicJobs().AddSafely(periodicJob) and must handle
the returned validation error.
Error handling¶
func (w *MyWorker) Work(ctx context.Context, job *river.Job[MyArgs]) error {
if retryable {
return fmt.Errorf("transient: %w", err) // retried up to MaxAttempts
}
return river.JobCancel(err) // cancels permanently
}
Stop, retry, and fetch controls¶
cfg := &river.Config{
RetryPolicy: myPolicy, // river.ClientRetryPolicy: NextRetry(*rivertype.JobRow) time.Time
SoftStopTimeout: 30 * time.Second, // Stop escalates to job-context cancel after this
LeaderElectionDisabled: false, // v0.48: work jobs without leading maintenance
FetchOnlyKnownKinds: false, // v0.48: fetch only registered worker kinds
}
err = client.Stop(ctx) // soft: stop fetching, wait for running jobs
err = client.StopAndCancel(ctx) // hard: cancel running job contexts, then wait
SQLite driver¶
import "github.com/riverqueue/river/riverdriver/riversqlite"
db.SetMaxOpenConns(1) // upstream advice: avoids SQLITE_BUSY from parallel maintenance
client, err := river.NewClient(riversqlite.New(db), cfg) // *river.Client[*sql.Tx]
JobListParams.Metadata is unsupported on SQLite. Migration version 8 only
changes SQLite (river_job id gains AUTOINCREMENT).
Behaviour changes since v0.47.0¶
- v0.49: transactional helpers reuse the caller's transaction instead of a
savepoint; callers must roll back on error (
outbox/drainer.goalready wrapsInsertTxin its own savepoint). - v0.48:
UniqueOpts.ByPeriodbuckets on the effective scheduled time in UTC;UniqueOpts{ExcludeKind: true}alone is rejected at insert.
Transaction helper¶
// river/riverpgxv5 — pgx driver
import "github.com/riverqueue/river/riverdriver/riverpgxv5"
driver := riverpgxv5.New(pool)
golusoris usage¶
jobs/—river.Client+river.Workersprovided via fx; periodic job registration.jobs/cron/— cron expression →river.PeriodicJob.testutil/river/— in-process test harness.