Orisun

Orisun

Orisun is a batteries-included event store for systems that need durable event history, content-based consistency checks, and real-time delivery without running a separate broker.

Full documentation: oexza.github.io/Orisun

Start here: What is Orisun?

What It Provides

• Transactional event storage on PostgreSQL, YugabyteDB, or SQLite.
• Command Context Consistency: save only if the queried event context has not changed.
• Server-side latest-by-criteria reads for carried-state command contexts.
• Embedded NATS JetStream for catch-up and live subscriptions, with optional external NATS via ORISUN_NATS_URL.
• Durable publisher checkpoints so committed events are not skipped.
• Sequential publishing per boundary in ascending event-log position.
• gRPC APIs, generated clients, Docker images, embedding packages, auth, TLS, telemetry, pprof, and index management.

Quick Start

Download a release binary from GitHub Releases, or build one locally:

./build.sh linux amd64 dev sqlite

SQLite single-node with a binary:

mkdir -p ./data/orisun/sqlite ./data/orisun/nats

ORISUN_BACKEND=sqlite \
ORISUN_SQLITE_DIR=./data/orisun/sqlite \
ORISUN_NATS_STORE_DIR=./data/orisun/nats \
ORISUN_NATS_CLUSTER_ENABLED=false \
ORISUN_BOUNDARIES='[{"name":"orders"},{"name":"orisun_admin"}]' \
ORISUN_ADMIN_BOUNDARY=orisun_admin \
./build/orisun-sqlite-linux-amd64

For SQLite production durability, use ORISUN_SQLITE_SYNCHRONOUS=FULL (recommended). NORMAL is a throughput opt-out that can lose already acknowledged commits after an OS crash or power loss before checkpointing. SQLite stores event logs in one {boundary}.db file per boundary and stores publisher checkpoints, projector checkpoints, admin users, and count caches in one {boundary}_metadata.db file per boundary under ORISUN_SQLITE_DIR.

The same server can also run from Docker:

docker run --rm \
  -p 5005:5005 \
  -p 8991:8991 \
  -e ORISUN_BACKEND=sqlite \
  -e ORISUN_SQLITE_DIR=/var/lib/orisun/sqlite \
  -e ORISUN_NATS_CLUSTER_ENABLED=false \
  -e ORISUN_BOUNDARIES='[{"name":"orders"},{"name":"orisun_admin"}]' \
  -e ORISUN_ADMIN_BOUNDARY=orisun_admin \
  -v orisun-data:/var/lib/orisun \
  orexza/orisun:sqlite

PostgreSQL with a binary:

./build.sh linux amd64 dev pg

ORISUN_BACKEND=postgres \
ORISUN_PG_HOST=localhost \
ORISUN_PG_PORT=5432 \
ORISUN_PG_USER=postgres \
ORISUN_PG_PASSWORD='password@1' \
ORISUN_PG_NAME=orisun \
ORISUN_PG_SCHEMAS=orders:public,orisun_admin:admin \
ORISUN_BOUNDARIES='[{"name":"orders"},{"name":"orisun_admin"}]' \
ORISUN_ADMIN_BOUNDARY=orisun_admin \
./build/orisun-pg-linux-amd64

YugabyteDB uses the PostgreSQL-compatible binary with ORISUN_PG_DIALECT=yugabyte. Use YugabyteDB v2025.2.3+ and enable LISTEN/NOTIFY on Masters and TServers with ysql_yb_enable_listen_notify=true.

See the getting started guide for binary and Docker setup for all supported backends.

Artifacts

Release binaries are attached to each GitHub release:

Docker tags are published to Docker Hub (orexza/orisun) and GitHub Container Registry (ghcr.io/oexza/orisun) with the same flavor tags:

Use the same suffixes with ghcr.io/oexza/orisun, for example ghcr.io/oexza/orisun:fdb.

Development

go test ./...
go build ./...
task build
task build:pg
task build:sqlite
go build -tags foundationdb ./cmd/orisun-fdb

FoundationDB support is beta. It is covered by backend, failover, and ledger workload tests, but storage layout or operational behavior may still change in a future release if production feedback exposes a better contract.

Release:

./scripts/release.sh 1.2.3 --notes release-notes.md

License

MIT