Quick Start

Install OxiDB from scratch in under five minutes. Pick a path:

Server mode — one binary, listens on TCP, talk to it from any language. Start here.
Embedded mode — link OxiDB into your app, no separate process. Jump to Embed in your app.

1. Install the server

Pre-built static binaries — no runtime, no installer, no dependencies. Pick your platform:

Linux (x86_64)

curl -LO https://github.com/parisxmas/OxiDB/releases/download/v0.28.18/oxidb-server-v0.28.18-linux-amd64.tar.gz
tar xzf oxidb-server-v0.28.18-linux-amd64.tar.gz
sudo mv oxidb-server /usr/local/bin/
oxidb-server --version

Linux (ARM64)

curl -LO https://github.com/parisxmas/OxiDB/releases/download/v0.28.18/oxidb-server-v0.28.18-linux-arm64.tar.gz
tar xzf oxidb-server-v0.28.18-linux-arm64.tar.gz
sudo mv oxidb-server /usr/local/bin/

macOS (Apple Silicon / Intel)

# Apple Silicon
curl -LO https://github.com/parisxmas/OxiDB/releases/download/v0.28.18/oxidb-server-v0.28.18-darwin-arm64.tar.gz
tar xzf oxidb-server-v0.28.18-darwin-arm64.tar.gz

# Intel
curl -LO https://github.com/parisxmas/OxiDB/releases/download/v0.28.18/oxidb-server-v0.28.18-darwin-amd64.tar.gz
tar xzf oxidb-server-v0.28.18-darwin-amd64.tar.gz

sudo mv oxidb-server /usr/local/bin/

Windows (x86_64)

# PowerShell
Invoke-WebRequest -Uri https://github.com/parisxmas/OxiDB/releases/download/v0.28.18/oxidb-server-v0.28.18-windows-amd64.zip -OutFile oxidb-server.zip
Expand-Archive oxidb-server.zip -DestinationPath .
.\oxidb-server.exe --version

Build from source (any platform)

git clone https://github.com/parisxmas/OxiDB.git
cd OxiDB
cargo build --release -p oxidb-server
./target/release/oxidb-server --version

Docker

docker run -d --name oxidb \
  -p 4444:4444 \
  -v $(pwd)/data:/data \
  -e OXIDB_DATA=/data \
  -e OXIDB_ADDR=0.0.0.0:4444 \
  ghcr.io/parisxmas/oxidb:0.28.18

2. Start the server

# Defaults: listens on 127.0.0.1:4444, data directory ./oxidb_data
oxidb-server

# Or override with environment variables:
OXIDB_ADDR=0.0.0.0:4444 \
OXIDB_DATA=/var/lib/oxidb \
OXIDB_POOL_SIZE=8 \
oxidb-server

Variable	Default	Purpose
`OXIDB_ADDR`	`127.0.0.1:4444`	Bind address
`OXIDB_DATA`	`./oxidb_data`	Data directory
`OXIDB_POOL_SIZE`	`4`	Worker threads
`OXIDB_IDLE_TIMEOUT`	`30`	Idle connection timeout (s, 0 = never)

For TLS, SCRAM-SHA-256 auth, RBAC, and audit logging see Server.

3. Install the CLI & run your first query

# Linux example — pick the matching CLI archive from /downloads/ for your OS
curl -LO https://github.com/parisxmas/OxiDB/releases/download/v0.28.18/oxidb-cli-v0.28.18-linux-amd64.tar.gz
tar xzf oxidb-cli-v0.28.18-linux-amd64.tar.gz
sudo mv oxidb /usr/local/bin/

# Open the REPL against the running server
oxidb --host 127.0.0.1 --port 4444

oxidb> insert users {"name": "Alice", "age": 30, "department": "Engineering"}
oxidb> find   users {"age": {"$gte": 18}}
oxidb> update users {"name": "Alice"} {"$inc": {"age": 1}}
oxidb> count  users
oxidb> .exit

4. Connect from your application

Python

pip install oxidb

from oxidb import OxiDbClient

with OxiDbClient("127.0.0.1", 4444) as db:
    db.insert("users", {"name": "Alice", "age": 30})
    docs = db.find("users", {"age": {"$gte": 25}})
    db.update("users", {"name": "Alice"}, {"$inc": {"age": 1}})

Go

go get github.com/parisxmas/oxiwire-go

client, _ := oxidb.ConnectDefault()
defer client.Close()
client.UseOxiWire() // binary protocol — fastest

client.Insert("users", map[string]any{
    "name": "Alice", "age": 30,
})
docs, _ := client.Find("users", map[string]any{
    "age": map[string]any{"$gte": 25},
}, nil)

.NET (TCP or EF Core)

dotnet add package OxiDb.Client.Tcp
dotnet add package OxiDb.EntityFrameworkCore  # optional EF Core provider

// Program.cs
builder.Services.AddOxiDb(options => {
    options.UseTcp("127.0.0.1", 4444);
});

var users = await db.Users
    .Where(u => u.Age >= 25)
    .OrderBy(u => u.Name)
    .ToListAsync();

Other languages: Julia, Swift, JavaScript/TypeScript.

Embed in your app (no server)

Skip the TCP layer entirely — link OxiDB into your process, talk to it via function calls, zero network overhead.

Rust

cargo add oxidb

use oxidb::OxiDb;
use serde_json::json;

fn main() {
    let db = OxiDb::open("./my_data").unwrap();

    db.insert("users", json!({
        "name": "Alice", "age": 30
    })).unwrap();

    let results = db.find("users",
        json!({"age": {"$gte": 25}}), None).unwrap();
}

Python (Embedded via FFI)

pip install oxidb-embedded

from oxidb_embedded import OxiDb

db = OxiDb("./my_data")
db.insert("users", {"name": "Alice", "age": 30})

.NET (Embedded via FFI)

dotnet add package OxiDb.Client.Embedded

WebAssembly (browser)

Run the full engine in the browser — in-memory, no server. See WebAssembly.

Production: 3-node Raft cluster v0.28.18

Each node sets a unique OXIDB_NODE_ID and the same OXIDB_RAFT_PEERS list. After all three are up, bootstrap once via the leader candidate. Raft state is persisted to disk, so nodes survive container restarts.

# node 1 — initial leader candidate
OXIDB_NODE_ID=1 OXIDB_RAFT_ADDR=0.0.0.0:5000 \
  OXIDB_RAFT_PEERS="1=db-a0:5000,2=db-a1:5000,3=db-a2:5000" \
  oxidb-server &

# node 2 + node 3 — same OXIDB_RAFT_PEERS, different NODE_ID and host

# one-shot bootstrap on db-a0
oxidb raft_init
oxidb raft_add_learner --id=2 --addr=db-a1:5000
oxidb raft_add_learner --id=3 --addr=db-a2:5000
oxidb raft_change_membership --members=1,2,3

For a full reference deployment (3 shards × 3 Raft nodes, oxipool routing, Go API, Python failover + 1M-record load tests) see ShardReplicaRealWorldTest/ in the repo.

Next steps

Query operators — JSON query language reference
SQL — standard SQL with JOINs and GROUP BY
Indexes — single-field, composite, unique, vector
Transactions — multi-collection ACID with OCC
Server — TLS, auth, RBAC, sharding, Raft
Clients — every language binding