Getting Started

Key concepts in 60 seconds

Before running anything, here are the building blocks you will encounter.

Records. Every record is a key (string), a value (bytes), and a per-key monotonic VersionId used for optimistic concurrency. Keys are arbitrary byte strings — Oxia is agnostic to their structure, and applications are free to use flat identifiers, path-shaped keys, or whatever fits. The namespace’s key sorting mode (hierarchical with special / handling, or natural byte-wise order) controls how range scans traverse the key space.
Namespaces. An isolated key space with its own shards and configuration. Every client picks one on connect (default by default). See namespaces.
Shards. A namespace is partitioned into shards, each with its own leader and replica set. The client library routes keys to the right shard; there is no shard-aware code to write. See logical architecture.
Per-key linearizability. Successful operations on any single key are linearizable; operations on different keys may land on different shards and have no cluster-wide real-time order. See consistency model.
Sessions and ephemerals. Records can be marked ephemeral: they live as long as the client’s session does, and are deleted when the client disconnects. The building block of leader election and service discovery. See ephemerals.
Notifications. Clients can subscribe to a reliable, resumable stream of create / modify / delete events in a namespace. See notifications.

Obtaining Oxia

Docker

Oxia is available in form of a Docker image: oxia/oxia:latest

Standalone

Oxia standalone is a single-node single-process instance of Oxia that can started with little or no configuration. It provides a full-fledged Oxia service with a default namespace. Being a single-node instance, the data is not getting replicated.


oxia standalone

Output will be something like:


Mar 30 16:51:40.519927 INF Starting Oxia standalone
config={"DataDir":"./data/db","InMemory":false,"InternalServiceAddr":"","MetricsServiceAddr":"0.0.0.0:8080","NotificationsRetentionTime":3600000000000,"NumShards":1,"PublicServiceAddr":"0.0.0.0:6648","WalDir":"./data/wal","WalRetentionTime":3600000000000}
Mar 30 16:51:40.553559 INF Created leader controller component=leader-controller namespace=default shard=0 term=-1
Mar 30 16:51:40.566230 INF Leader successfully initialized in new term component=leader-controller
last-entry={"offset":"-1","term":"-1"} namespace=default shard=0 term=0
Mar 30 16:51:40.566372 INF Applying all pending entries to database commit-offset=-1 component=leader-controller
head-offset=-1 namespace=default shard=0 term=0
Mar 30 16:51:40.566389 INF Started leading the shard component=leader-controller head-offset=-1 namespace=default
shard=0 term=0
Mar 30 16:51:40.566701 INF Started Grpc server bindAddress=[::]:6648 grpc-server=public
Mar 30 16:51:40.566760 INF Serving Prometheus metrics at http://localhost:8080/metrics

The service is now ready at localhost:6648 address.

Using docker this can be done with:


docker run -p 6648:6648 oxia/oxia:latest oxia standalone

Interacting with Oxia

There is a convenient CLI tool that allows you to interact with the records stored in Oxia.


# Write or update a record
$ oxia client put my-key my-value
{"key":"my-key","version_id":2132,"created_timestamp":"2025-06-17T17:09:26.043-07:00","modified_timestamp":"2025-06-17T17:09:26.043-07:00","modifications_count":0,"ephemeral":false,"session_id":0,"client_identity":""}
 
 
# Read the value of a key
$ oxia client get my-key
my-value
 
# Read value with version information
$ oxia client get my-key -v
my-value
---
{"key":"my-key","version_id":2132,"created_timestamp":"2025-06-17T17:09:26.043-07:00","modified_timestamp":"2025-06-17T17:09:26.043-07:00","modifications_count":0,"ephemeral":false,"session_id":0,"client_identity":""}

Going beyond standalone

oxia standalone runs a single-node, single-process cluster with replication factor 1 — fine for local development, but it is not a production deployment. To run a real cluster:

Kubernetes — install the official Helm chart for a multi-node cluster with coordinators, storage nodes, and metrics pre-wired.
Bare metal or self-managed — see bare metal for running the coordinator and storage nodes as plain processes.
Tune the namespace. Namespaces carry initialShardCount and replicationFactor; pick values that match your throughput and availability targets.
Day-two operations. Admin operations covers shard management and cluster upkeep.

Using client SDKs

Oxia has several client SDKs that can be used: