outbox

README

GO Outbox (Core)

github.com/assurrussa/outbox is the core outbox library.

The repository is now a multi-module monorepo:

• core module: github.com/assurrussa/outbox
• MySQL backend: github.com/assurrussa/outbox/backends/mysql
• SQLite backend: github.com/assurrussa/outbox/backends/sqlite
• Postgres backend: github.com/assurrussa/outbox/backends/pgsql
• Picodata backend: github.com/assurrussa/outbox/backends/picodata

Install core

go get github.com/assurrussa/outbox@latest

import "github.com/assurrussa/outbox/outbox"

Core usage

package main

import (
	"context"
	"time"

	"github.com/assurrussa/outbox/outbox"
	outboxlogger "github.com/assurrussa/outbox/outbox/logger"
	sharedjob "github.com/assurrussa/outbox/shared/job"
)

type SendEmailJob struct {
	sharedjob.DefaultJob
}

func (*SendEmailJob) Name() string { return "send_email" }

func (*SendEmailJob) Handle(_ context.Context, _ string) error { return nil }

func main() {
	ctx := context.Background()

	svc, err := outbox.New(
		outbox.WithWorkers(1),
		outbox.WithReserveFor(time.Second),
		outbox.WithIdleTime(5*time.Minute),
		outbox.WithLogger(outboxlogger.Default()),
		outbox.WithJobsRepo(jobsRepo),
		// Optional: only needed for svc.GetQueueStats(...)
		outbox.WithJobsStatRepo(jobsRepo),
		outbox.WithJobsFailedRepo(jobsFailedRepo),
		outbox.WithTransactor(txManager),
	)
	if err != nil {
		panic(err)
	}

	emailJob := &SendEmailJob{}
	svc.MustRegisterJob(emailJob)

	go func() { _ = svc.Run(ctx) }()
	_, _ = svc.Put(ctx, "send_email", `{"id":"1"}`, time.Now())
}

JobsStatRepository is optional.
Set WithJobsStatRepo(...) only if you need svc.GetQueueStats(...).

Backend modules

Pick only the backend module you need for a project.

• MySQL backend
• SQLite backend
• Postgres backend
• Picodata backend

Example app

Runnable examples:

• examples/base-app (core only, in-memory stubs)
• examples/base-app-mysql
• examples/base-app-picodata
• examples/base-app-pgsql
• examples/base-app-sqlite

Migration from old import paths

Old infrastructure/* paths were removed (hard break).

See MIGRATION.md.

Notes on shared/*

shared/* is kept in core for internal library/backend reuse, but should be treated as unstable internal API by external consumers.

Development

Use workspace-aware commands:

make test-core
make test-backends
make test-integration-all

For integration services:

make devup
make devdown

Release prep for backend modules:

# pin backend modules to a published core tag
make release-ready-backends CORE_VERSION=v0.9.0

# verify each backend as standalone module (without go.work)
make release-verify-backends

License

MIT. See LICENSE.