Installation

Riverbase is distributed as a git dependency from riverbase-io/riverbase. You need a Rust toolchain and a PostgreSQL database.

Prerequisites

Requirement	Version	Notes
Rust	1.78 or newer	Edition 2021. Install with rustup.
PostgreSQL	14 or newer	Holds domain state, the audit log, and framework tables.
Docker	any	Optional. The fastest way to get a local Postgres.

Start Postgres

Any Postgres 14+ works. For local development, a container is enough:

docker run -d --name riverbase-pg -p 5432:5432 \
  -e POSTGRES_USER=riverbase -e POSTGRES_PASSWORD=change-me -e POSTGRES_DB=riverbase \
  postgres:16-alpine
export RIVERBASE_DB_URL=postgres://riverbase:change-me@127.0.0.1:5432/riverbase

Framework migrations (audit log, outbox, tracker tables) run automatically when a service first connects. Your domain's own migrations run through its store spec. See Datastore.

Add the crates

A service usually depends on three crates: the kernel, the proc macros, and the HTTP stack.

cargo add riverbase_core riverbase_proc riverbase_http --git https://github.com/riverbase-io/riverbase

Or declare them once in your workspace Cargo.toml and let member crates use workspace = true:

Cargo.toml (workspace root)

[workspace.dependencies]
riverbase_core = { git = "https://github.com/riverbase-io/riverbase" }
riverbase_proc = { git = "https://github.com/riverbase-io/riverbase" }
riverbase_http = { git = "https://github.com/riverbase-io/riverbase" }

# The macros expand to code that uses these crates directly.
async-trait = "0.1"
chrono = { version = "0.4", features = ["serde"] }
diesel = { version = "2.2", features = ["postgres", "chrono", "uuid", "serde_json", "r2d2"] }
diesel-async = { version = "0.5", features = ["postgres", "deadpool"] }
diesel_migrations = "2.2"
garde = { version = "0.22", default-features = false, features = ["derive", "serde"] }
schemars = { version = "0.9", features = ["preserve_order", "chrono04", "uuid1"] }
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", features = ["preserve_order"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "sync", "time"] }
tracing = "0.1"
uuid = { version = "1", features = ["v4", "v5", "serde"] }

Pin one revision

All Riverbase crates release together. Add the same rev = "…" (or tag = "…") to every riverbase_* line so a cargo update never mixes versions.

The third-party versions above match framework version 0.2.0. Check the root Cargo.toml of riverbase-io/riverbase when you upgrade.

Feature flags

riverbase_core defaults to the kernel feature (engines, datastore, macros, Postgres). riverbase_http defaults to auth. Turn on the rest as you need them:

# NATS message bus + realtime endpoints
cargo add riverbase_core --git https://github.com/riverbase-io/riverbase --features nats-io
cargo add riverbase_http --git https://github.com/riverbase-io/riverbase --features websocket,sse,rxdb

The full list is in Crates and features.

Verify the toolchain

Clone the framework and run its test suite against your database. Database tests read RIVERBASE_DB_URL and skip when it is unset.

git clone https://github.com/riverbase-io/riverbase
cd riverbase
cargo build --workspace
cargo test --workspace

License

Riverbase is distributed under the RFX JSC Proprietary License, not an open-source license. Read LICENSE and COPYRIGHT in the repository before you depend on it.

Next: Quick start.