Skip to Content
Quickstart

Quickstart

Get a governed Relata store running locally in under five minutes. The lite profile is single-binary, single-process, no external dependencies.

1. Install

Docker (recommended)

docker run -d -p 9090:9090 --name relata \
  ghcr.io/openworkbench-co/relatadb:latest

From source (requires Rust)

cargo install --path crates/relata-cli --locked

After install, the server exposes Postgres wire on port 9090 (any psql client connects directly).

2. Start the server

relata serve

Defaults:

SettingDefault
Deployment profilelite
Domain profileenterprise
HTTP port9090
Purpose modeopen (purpose optional; recorded for audit when declared)
Auth tokenunset (dev mode — no auth, pgwire disabled)
Storagelocal disk at ./data/relata/objects

3. Check health

curl http://127.0.0.1:9090/health
curl http://127.0.0.1:9090/status

4. Run your first query

relata query "SELECT * FROM Person LIMIT 5"
 
# with a declared purpose (recorded for audit):
relata query "PURPOSE 'analytics' SELECT * FROM Person LIMIT 5"
 
# from a file:
relata query --file queries/persons.sql

Or call HTTP directly:

curl -s http://127.0.0.1:9090/query \
  -H 'Content-Type: application/json' \
  -d '{"sql":"SELECT * FROM Person LIMIT 5"}'

5. Use an SDK

Pick the SDK that matches your stack — each takes under a minute:

Python

pip install relata-sdk
from relata import RelataClient
 
with RelataClient("http://localhost:9090", purpose="analytics") as client:
    result = client.query("SELECT * FROM Person LIMIT 5")
    for row in result:
        print(row)

TypeScript

npm install @relata/sdk
import { createClient } from "@relata/sdk";
 
const relata = createClient("http://localhost:9090", { defaultPurpose: "analytics" });
const result = await relata.query("SELECT * FROM Person LIMIT 5");
console.log(result.rows);

Go

go get github.com/OpenWorkBench-Co/RelataDB/sdks/go
client := relata.New("http://localhost:9090", &relata.ClientOptions{
    DefaultPurpose: "analytics",
})
result, _ := client.Query(context.Background(), "SELECT * FROM Person LIMIT 5")
result.Each(func(row map[string]any) { fmt.Println(row) })

Rust

Add to Cargo.toml: relata-sdk-rust = { path = "..." } (workspace member).

use relata_sdk_rust::{RelataClient, QueryRequest};
 
let mut client = RelataClient::connect("http://localhost:50051").await?;
let resp = client.query(QueryRequest {
    purpose: "analytics".to_owned(),
    sql: "SELECT * FROM Person LIMIT 5".to_owned(),
}).await?;

psql / pgvector

RELATA_BEARER_TOKEN=change-me relata serve
psql -h 127.0.0.1 -p 5433 -U relata relata   # password = RELATA_BEARER_TOKEN
SELECT * FROM Person LIMIT 5;

Any MCP-compatible agent (Claude Desktop, OpenAI Agents SDK, …)

Point your agent at http://localhost:9090/mcp. Discover tools:

curl http://localhost:9090/mcp/tools -H "Authorization: Bearer $RELATA_BEARER_TOKEN"

Call a tool:

curl -X POST http://localhost:9090/mcp/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -d '{"name":"query","arguments":{"sql":"SELECT * FROM Person LIMIT 5","purpose":"analytics"}}'

6. Store an agent memory

curl -X POST http://localhost:9090/memory/remember \
  -H "Content-Type: application/json" \
  -d '{"content":"Customer Alice prefers dark mode.","purpose":"account_management"}'
 
curl -X POST http://localhost:9090/memory/recall \
  -H "Content-Type: application/json" \
  -d '{"query":"ui preferences","top_k":3,"purpose":"account_management"}'

Next steps

  • Read the Concepts section to understand the model.
  • Browse the SQL Reference for the full operator surface.
  • Pick your SDK for typed access.
Last updated on
ProtocolsDeployment