Installation
/v1/, the compatibility protocol doors (Postgres, Mongo, Redis, Neo4j, ClickHouse, S3, Flight, SPARQL) are retired, and clustering and multi-tenancy are Enterprise. See What is new in 3.0 and HTTP route restructure.RelataDB ships as a single Rust binary — no JVM, no external services, no runtime dependencies. Docker is optional. In the 3.0 open build there is one posture: the RELATA_PROFILE selector accepts only free (the default), and the server and cluster profiles are retired. 2.5.8 shipped three profiles from the same binary.
Prerequisites
| Requirement | Version | Notes |
|---|---|---|
| Rust toolchain | 1.85+ (MSRV, edition 2024) | rustup default stable — build from source only |
protoc | 3.x+ | Required at build time (a dependency compiles a .proto file) |
| OS | Linux, macOS, Windows (WSL2) | x86_64 and aarch64 supported |
| Memory | 512 MB minimum | Memory budgets are derived from detected RAM; no profile clamps them |
| External services | None | No Redis, no Kafka, no JVM required |
Note: Docker users skip Rust and protoc entirely — the image is self-contained.
Docker (recommended)
The fastest path. The published image bundles the relata binary. The canonical image is ghcr.io/relatadb/relata (the same image is mirrored to Docker Hub as openworkbench/relata-db — pick whichever registry your environment prefers).
Auth is mandatory and the image binds 0.0.0.0:8080, so a bare docker run exits at boot with No authentication configured … Refusing to start. The minimum local-dev shape (the same defaults docker-compose.yml ships in the repo) is:
docker run -d -p 8080:8080 --name relata \
-e RELATA_BEARER_TOKEN=local-dev-bearer \
-e RELATA_ADMIN_TOKEN=local-dev-admin \
-e RELATA_KMS_LOCAL_DEV=true \
-e RELATA_SECURITY_MODE=open \
ghcr.io/relatadb/relata:latest
# or, the Docker Hub mirror (same image):
docker run -d -p 8080:8080 --name relata \
-e RELATA_BEARER_TOKEN=local-dev-bearer \
-e RELATA_ADMIN_TOKEN=local-dev-admin \
-e RELATA_KMS_LOCAL_DEV=true \
-e RELATA_SECURITY_MODE=open \
openworkbench/relata-db:latestVerify (the image listens on port 8080; RELATA_BEARER_TOKEN is loopback-only, so check from inside the container):
docker exec relata curl -s http://127.0.0.1:8080/health
# {"status":"ok"}To call the server from your host, mint a registry token —
RELATA_BEARER_TOKEN is refused through a published port. The full
boot → mint → connect flow is the Quickstart's
Prerequisites section.
To persist data to a host directory:
docker run -d -p 8080:8080 \
-e RELATA_BEARER_TOKEN=local-dev-bearer \
-e RELATA_ADMIN_TOKEN=local-dev-admin \
-e RELATA_KMS_LOCAL_DEV=true \
-e RELATA_SECURITY_MODE=open \
-v "$PWD/relata-data:/data/relata" \
--name relata \
ghcr.io/relatadb/relata:latestProduction: pin to a specific tag (e.g.
ghcr.io/relatadb/relata:3.0.0) and runrelata checkafter startup. Using:latestin production is a reliability risk — and replace everylocal-dev-*value above with real secrets.
Pre-built Binary
The signed install script downloads the correct pre-built binary for your platform and verifies its SHA-256 checksum:
curl -sSf https://relatadb.dev/install.sh | sh
relata --versionSupported targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin.
Build from Source
Relata DB 3.0 is open source (AGPL-3.0-only). Build from the source tree with Rust 1.85+, protoc, and cargo:
cargo install --path crates/relata-cli --locked # → ~/.cargo/bin/relata
# or, without installing system-wide:
cargo build --workspace --release # → target/release/relata--locked uses the exact dependency versions in Cargo.lock. Request source access via github.com/relatadb.
Note:
unsafeis forbidden (#![forbid(unsafe_code)]in every crate) andmissing_docsis denied.
Supply-chain check (optional but recommended before production):
cargo deny checkVerify the Install
relata --version
# relata 3.0.0Start the server and confirm it responds (auth is mandatory on every profile — the loopback dev convenience is an explicit two-flag opt-in):
RELATA_OPEN_DEV_ALLOWED=true relata serve &
curl http://127.0.0.1:9090/health
# {"status":"ok"}Run the full integration check suite (150+ checks covering storage, query and auth):
relata checkRun
relata checkafter every install or upgrade. It exercises the full server surface and catches misconfiguration before your workload does.
First-Run Checklist
- Start the server:
RELATA_OPEN_DEV_ALLOWED=true relata serve(loopback dev loop — or setRELATA_BEARER_TOKEN) - Confirm health:
curl http://127.0.0.1:9090/health - Run a query:
relata query "SELECT * FROM Person LIMIT 5" - Set a bearer token:
RELATA_BEARER_TOKEN=your-secret relata serve - Run integration checks:
relata check
Deployment Shape
Relata DB 3.0 is one binary on one machine with one tenant. There are no deployment profiles to choose: RELATA_PROFILE accepts only free (the default), and server, cluster and lite fail at startup. The security posture follows configuration: bind address, TLS, tokens and RELATA_OPEN_DEV_ALLOWED. See Deployment and the environment variable reference. Clustering and several tenants belong to Relata Enterprise DB (Editions and limits).
Key CLI Commands
| Command | Purpose |
|---|---|
relata serve | Start the HTTP server (HTTP/JSON, GraphQL, MCP) |
relata query "SQL" | Run a one-off query |
relata check | Run 150+ integration checks |
relata backup / relata restore | Snapshot backup and restore |
All commands respect the full RELATA_* environment variable matrix documented in Configuration.
Air-Gapped / Demo Mode
There's no single air-gap switch — outbound calls are opt-in already. Leave RELATA_LLM_URL/RELATA_LLM_API_KEY and RELATA_OTLP_ENDPOINT unset and the node makes no LLM or telemetry calls.
To disable rate limits for load testing, benchmarks, or demo environments, raise the per-IP limiter values directly:
RELATA_RATE_LIMIT_RPS=99999 \
RELATA_RATE_LIMIT_AUTH_FAIL_RPS=99999 \
relata serveWarning: Do not disable rate limits in production. They are part of the abuse-prevention posture. Use network-layer controls (mTLS sidecar, NetworkPolicy) if you need to enforce them at the infrastructure level instead.
Setting RELATA_RATE_LIMIT_AUTH_FAIL_RPS=0 is treated as 1 by the backend — zero is clamped to the minimum. Use 99999 to effectively disable the auth-fail bucket.
See Also
- Quickstart — get running and issue your first query in five minutes
- Configuration — full environment variable reference
- Deployment — production topology, TLS, object storage