StellarDB is an embeddable multi-model database built in Rust. It combines a document store, graph traversal, HNSW vector search, and BM25 full-text search in one binaryβwithout stitching together four separate systems.
[!NOTE] StellarDB is under active development. Pin versions and validate backups before production use.
π Why StellarDB?
| Model | What you get |
|---|---|
| π Documents | Nested records, arrays, rich scalar types, schemas, and secondary indexes |
| πΈοΈ Graphs | Typed edges, bidirectional indexes, and variable-depth traversal |
| π§ Vectors | HNSW indexes with cosine, Euclidean, and dot-product distance |
| π Full text | Tantivy-powered BM25, analyzers, boosts, scores, and highlighting |
| β¨ Hybrid search | Reciprocal Rank Fusion across keyword and semantic results |
All models share the same storage engine, transaction layer, authorization path, and StellarQL query language.
π Quick start
Build
The executable is written to target/release/stellar.
Start the server
Then open http://localhost:3000/_station/ for the built-in Station UI.
Run with Docker
The HTTP API is available at http://localhost:3000. Data is persisted in the stellardb-data volume.
Send your first query
πͺ One language, four models
Documents
DEFINE COLLECTION user (
SCHEMA STRICT,
name string REQUIRED,
email string REQUIRED,
age int DEFAULT 0,
INDEX ON email UNIQUE
);
:alice SET
name = "Alice",
email = "alice@example.com",
age = 30;
SELECT name, age
FROM user
WHERE age >= 21
ORDER age DESC
LIMIT 10;
Graphs
:bob SET name = "Bob";
:carol SET name = "Carol";
RELATE user:alice->follows->user:bob SET since = 2024;
RELATE user:bob->follows->user:carol SET since = 2025;
SELECT ->follows{1..3}->user.{name}
FROM user:alice;
Vector search
(embedding)
HNSW DIMENSION 768 DIST COSINE;
SELECT title, vector::distance AS distance
FROM article
WHERE embedding <|10|> $query_vector;
Full-text search
DEFINE ANALYZER english
TOKENIZER standard
FILTERS [lowercase, stemmer(english)];
(title, body)
FULLTEXT ANALYZER english;
SELECT title, fts::score AS score
FROM article
WHERE MATCH(title^3, body) @@ "rust database"
ORDER score DESC
LIMIT 10;
Hybrid search
SELECT * FROM search::rrf([
(SELECT id, fts::score AS score
FROM article
WHERE body @@ "multi model database"
LIMIT 20),
(SELECT id, vector::distance AS distance
FROM article
WHERE embedding <|20|> $query_vector)
], 10);
π¦ Embedded Rust API
Use StellarDB directly inside a Rust processβno HTTP server and no caller-provided Tokio runtime required.
use ;
let db = open?;
db.execute?;
db.execute?;
let rows = db.query?;
assert_eq!;
db.close?;
# Ok::
A lightweight library build excludes the CLI and server stack:
[]
= {
git = "https://github.com/vadim-su/stellardb",
= false,
= ["embedded-lite"]
}
Add fts, hnsw, or both when an embedded application needs search indexes.
β‘ Core capabilities
- ACID writes with optimistic concurrency control
- Strict or flexible schemas with unions, references, defaults, and validation
- B-tree indexes for equality, range, compound, and unique constraints
- Multi-database isolation through namespaces and
X-Database - HTTP and gRPC APIs with typed values and structured errors
- Durable background DDL with progress, cancellation, and restart recovery
- Native TLS, JWT authentication, API keys, and policy-based authorization
- Prometheus metrics, bounded cardinality, query timing, and index telemetry
- Backup and restore through the CLI
- Station UI embedded into the server binary
ποΈ Architecture
Clients / Station / Embedded API
β
HTTP Β· gRPC Β· Rust
β
Parse β Bind β Optimize
β
Execute
ββββββββββΌβββββββββ
β β β
Documents Graph Search
β β ββββ΄βββ
β β HNSW BM25
ββββββββββ΄βββββββ¬βββββ
β
Fjall + rkyv storage
| Layer | Technology |
|---|---|
| Storage | Fjall LSM-tree |
| Serialization | rkyv zero-copy reads |
| HTTP | Axum |
| gRPC | Tonic |
| Full-text search | Tantivy |
| Vector search | usearch HNSW |
| Web UI | React + TypeScript, embedded with rust-embed |
π HTTP API
Every data request selects a database through X-Database.
# Query
# Collection metadata
# Server capabilities
A framework-free TypeScript client lives in packages/client.
import { StellarClient } from "@stellardb/client";
const db = new StellarClient({
baseUrl: "http://localhost:3000",
database: "default",
});
const result = await db.query("SELECT * FROM user LIMIT 20");
π§° CLI essentials
# Server
# Query
# Schema
# Backup and restore
ποΈ Feature flags
Default builds include the complete CLI, server, authentication, gRPC, TLS, full-text search, vector search, and Station UI.
| Flag | Purpose |
|---|---|
cli |
Build the stellar executable and CLI dependencies |
server |
Enable HTTP server runtime |
auth |
Enable JWT, password, API-key, and policy services |
grpc |
Enable protobuf generation and the gRPC server |
tls |
Enable rustls for HTTP, CLI, and gRPC transport |
fts |
Enable Tantivy full-text indexes |
hnsw |
Enable usearch vector indexes |
ui |
Embed Station into the server binary |
embedded-lite |
Allow library builds without search engines |
Useful build profiles:
# Complete release binary
# Small embedded document/graph library
# Embedded library with both search engines
# Lightweight CLI without the server
π§ͺ Development
Install the pinned Rust and Bun toolchains, then run the repository checks:
The repository also includes:
station/β the embedded administration and query workspace, served at/_station/packages/client/β the standalone TypeScript HTTP clientexamples/ai-agent-memory/β a graph + vector + FTS examplebenches/β reproducible Criterion benchmarksscripts/β dataset loaders and benchmark tooling
Build StellarDB with the embedded Station, or build Station independently:
With a local StellarDB server running, the scripts in scripts/ can populate
sample and benchmark datasets. The e-commerce loader additionally requires the
Python requests package:
π Security defaults
- Non-loopback plaintext binds require explicit opt-in.
- TLS key files must have safe Unix permissions and cannot be symlinks.
- CORS is disabled unless an allowlist is configured.
- HTTP body size, gRPC message size, concurrency, and query deadlines are bounded.
- Login rate limiting includes process-wide and per-client buckets.
For internet-facing deployments, use native TLS or place StellarDB behind a trusted TLS-terminating reverse proxy.
Public (anonymous) access
Every request needs a bearer token unless --anonymous-user <name> (env STELLAR_ANONYMOUS_USER) names a managed user. Requests without an Authorization header then run as that user, so its policies decide what anonymous clients may do; invalid tokens are still rejected and root cannot be used.
;
'guest' SET role = 'public';
CREATE POLICY public_read
WHEN subject.role = 'public' AND action = 'SELECT' AND resource.database = 'catalog'
ALLOW;
STELLAR_ANONYMOUS_USER=guest
π License
StellarDB is available under the MIT License.