HeliosDB Nano

An embedded database with native PostgreSQL and MySQL wire-protocol compatibility, plus one-shot SQLite file import. Single self-contained binary (~32 MB; ~12 MB compressed download). HNSW vector search, git-like branching, time-travel queries, AES-256-GCM encryption, built-in BaaS layer (Auth, REST API, Realtime).

Use your existing clients (psql, mysql), RESTful HTTP, drivers (psycopg2, mysql-connector, node-postgres, JDBC), and ORMs (SQLAlchemy, Prisma, Drizzle, Hibernate, GORM) — zero migration required. Existing .sqlite files import via a bundled converter.

Ecosystem

Nano is one of four products in the HeliosDB family. SDKs and integrations are cross-edition — the same client code works against Nano, Lite, and Full.

• HeliosDatabase/HeliosDB-SDKs — Official client SDKs (Python, TypeScript, Rust, Go) + integrations (VS Code, n8n, Zapier, Make, Retool, AutoGen) + cross-platform CLI. Apache 2.0.
• HeliosDatabase/Any2HeliosDB — Apache-2.0 a2h migration toolkit for moving Oracle, MySQL, PostgreSQL, and SQL Server into HeliosDB Nano/Lite/Full or stock PostgreSQL, with wizard setup, resumable loads, validation, CDC, and MCP support.
• HeliosDatabase/HeliosDB-Lite — Production self-hosted database with HeliosProxy + HeliosCore baked in. SSPL-1.0.
• HeliosDatabase/HeliosDB-Full — Distributed enterprise database with 14 native wire protocols. SSPL-1.0.
• HeliosDatabase/HeliosDB-Proxy — Programmable Postgres data-plane (PgBouncer drop-in + WASM plugins + zero-downtime PG-12→17 upgrade). Apache 2.0.
• HeliosDatabase/HeliosDB-Proxy-Plugins · Operator · Terraform · Pulumi — Proxy ecosystem.

HeliosDatabase/HeliosDB-CodeKB-MCP provides an MCP server that turns HeliosDB codebases and docs into queryable technical knowledge for Claude Code, Codex, and other MCP clients.

Catalogue: heliosdb.com/sdks.html · Build with AI agents: heliosdb.com/build-with-agents.html · LLM-discoverable index: heliosdb.com/llms.txt

Performance: what's fast, and where we're still improving — honest strengths + transparent limits.

Benchmark: HeliosDB-Nano vs PostgreSQL 18.4 — the pg35 benchmark, its history & evolution — 35 SQL categories head-to-head; Nano wins all 35/35 at 300 iterations (30 by 10×–35,000×, the joins by 1.1×–2×). The one category that ever classified against Nano (Prepared stmts) turned out to expose a real ROLLBACK TO SAVEPOINT bug — fixed in v3.60.3, and now a ~157× Nano win.

Install

Supported now: Cargo / crates.io

Install Rust and Cargo first. On Linux, macOS, or WSL, the recommended installer is rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustc --version
cargo --version

On Windows, install Rust from rustup.rs, then open a new terminal so cargo is on PATH.

Install the heliosdb-nano CLI binary from crates.io:

cargo install heliosdb-nano --locked
heliosdb-nano --version

Use Nano as an embedded Rust library:

cargo add heliosdb-nano

Enable optional crate features when installing or adding the dependency:

cargo install heliosdb-nano --locked --features code-graph,mcp-endpoint
cargo add heliosdb-nano --features code-graph,mcp-endpoint

Build from source:

git clone https://github.com/HeliosDatabase/HeliosDB-Nano.git
cd HeliosDB-Nano
cargo build --release --locked
./target/release/heliosdb-nano --version

Prebuilt Binaries

Grab a self-contained binary from the GitHub Releases page — Linux (x86_64 / aarch64), macOS (aarch64), and Windows (x86_64), each with SHA256SUMS. No Rust toolchain required: download the archive for your platform, verify it against SHA256SUMS, extract, and run the heliosdb-nano binary.

# Example: Linux x86_64 (see Releases for macOS arm64 / Linux aarch64 / Windows)
VER=<release-tag>
curl -sSfL -O "https://github.com/HeliosDatabase/HeliosDB-Nano/releases/download/$VER/heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
tar xzf "heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
./heliosdb-nano --version

Install Channels

Use Cargo or the GitHub release binaries for a verified install. Package-manager channels such as npm, Homebrew, and container images should be treated as available only when they are listed on the official releases page.

Start the Server

# Persistent, all three protocols
heliosdb-nano start --data-dir ./mydata --mysql

# In-memory (great for dev/test)
heliosdb-nano start --memory --mysql

# With auth and TLS
heliosdb-nano start --data-dir ./mydata --mysql \
  --auth scram-sha-256 --password s3cret \
  --tls-cert cert.pem --tls-key key.pem

# Same-host / embedded mode — Unix sockets (no TCP)
heliosdb-nano start --memory \
  --pg-socket-dir /tmp \
  --mysql --mysql-socket /tmp/heliosdb-mysql.sock
# then: psql -h /tmp  or  mysql --socket=/tmp/heliosdb-mysql.sock

Three servers start on one process:

Triple Compatibility — Same Data, Any Client

Start the server once, then connect from any of the three interfaces. They all read and write the same tables.

Interactive REPL (zero setup)

$ heliosdb-nano repl --data-dir ./mydata
heliosdb> CREATE TABLE products (id SERIAL PRIMARY KEY, name TEXT, price DECIMAL(10,2));
OK
heliosdb> INSERT INTO products (name, price) VALUES ('Widget', 9.99), ('Gadget', 19.99);
INSERT 2
heliosdb> SELECT * FROM products WHERE price < 15;
 id |  name  | price
----+--------+-------
  1 | Widget |  9.99
(1 row)

PostgreSQL Client (psql)

$ psql -h 127.0.0.1 -p 5432 -U postgres
psql (server HeliosDB Nano)
postgres=# INSERT INTO products (name, price) VALUES ('Gizmo', 29.99);
INSERT 0 1
postgres=# SELECT COUNT(*) FROM products;
 count
-------
     3

MySQL Client (mysql)

$ mysql -h 127.0.0.1 -P 3306 -u root
Server version: HeliosDB-Nano
mysql> SELECT * FROM products WHERE name LIKE 'G%';
+----+--------+-------+
| id | name   | price |
+----+--------+-------+
|  2 | Gadget | 19.99 |
|  3 | Gizmo  | 29.99 |
+----+--------+-------+
mysql> INSERT INTO products (name, price) VALUES ('Gear', 39.99);
Query OK, 1 row affected

REST API (curl)

# Query
$ curl "http://localhost:8080/rest/v1/products?price=lt.50&select=id,name,price"
[{"id":1,"name":"Widget","price":"9.99"},{"id":2,"name":"Gadget","price":"19.99"}, ...]

# Insert
$ curl -X POST http://localhost:8080/rest/v1/products \
    -H 'Content-Type: application/json' \
    -d '{"name":"Gear 2","price":49.99}'

# Interactive API explorer (Swagger UI)
$ open http://localhost:8080/docs

Vector Search

Native HNSW indexes — no extensions, no separate vector database. The default path is in-process HNSW; --features vector-persist enables RocksDB-backed persistent HNSW/PQ with persistent = true, quantization = 'product', and rerank_precision = 'f32' | 'f16' | 'i8'.

-- From any client (psql / mysql / REPL):
CREATE TABLE docs (
    id SERIAL PRIMARY KEY,
    title TEXT,
    embedding VECTOR(1536)
);

CREATE INDEX ON docs USING hnsw (embedding vector_cosine_ops);
CREATE INDEX docs_embedding_persistent ON docs USING hnsw (embedding)
WITH (persistent = true, quantization = 'product', rerank_precision = 'i8');

INSERT INTO docs (title, embedding)
VALUES ('Intro', '[0.1, 0.2, 0.3, ...]');

-- k-NN search
SELECT title, embedding <-> '[0.15, 0.25, ...]' AS distance
FROM docs
ORDER BY distance
LIMIT 10;

Distance operators: <-> (L2), <=> (cosine), <#> (inner product). Vector store IDs are namespace-scoped, and metadata/namespace filters are applied before top-k selection in the REST/embedded vector-store API.

Via REST:

curl -X POST http://localhost:8080/api/vectors/search \
    -H 'Content-Type: application/json' \
    -d '{"collection":"docs","query":[0.15,0.25],"k":5,"metric":"cosine"}'

Full-Text Search

PostgreSQL-compatible FTS surface — no extensions, backed by built-in BM25:

-- Native tsvector / tsquery / @@ / ts_rank_cd:
SELECT title, ts_rank_cd(to_tsvector(body), to_tsquery('heliosdb')) AS rank
FROM articles
WHERE to_tsvector(body) @@ to_tsquery('heliosdb')
ORDER BY rank DESC
LIMIT 10;

-- Persistent tsvector column + GIN-style DDL:
CREATE TABLE articles (id SERIAL PRIMARY KEY, body TEXT, body_tsv TSVECTOR);
CREATE INDEX articles_body_fts ON articles USING gin (body_tsv);

-- Hybrid search (FTS + vector) in one query:
SELECT id, text,
       0.7 * (1.0 - (embedding <=> $1::vector))
     + 0.3 * ts_rank_cd(to_tsvector(text), plainto_tsquery($2)) AS score
FROM chunks
ORDER BY score DESC LIMIT 10;

Scope and honest limitations: see docs/compatibility/fts.md.

Pagination — Constant-Time at Depth

Deep LIMIT … OFFSET runs in ~30 µs regardless of offset — constant-time, where a stock row-store re-scans every skipped row (linear in the offset). Top-K over Sort, storage-level OFFSET skip, and keyset (WHERE (col, id) < ($1, $2)) are all native.

-- Traditional LIMIT / OFFSET — constant-time at any depth via storage-level skip
SELECT id, created_at, subject
  FROM leads
 ORDER BY created_at DESC, id DESC
 LIMIT 20 OFFSET 100000;

-- Keyset (row-constructor tuple) — preferred for high-volume lists
SELECT id, created_at, subject
  FROM leads
 WHERE (created_at, id) < ($1, $2)
 ORDER BY created_at DESC, id DESC
 LIMIT 20;

-- JOIN + pagination composes cleanly
SELECT l.id, l.subject, c.name AS company
  FROM leads l
  LEFT OUTER JOIN companies c ON l.company_id = c.id
 WHERE (l.created_at, l.id) < ($1, $2)
 ORDER BY l.created_at DESC, l.id DESC
 LIMIT 20;

Pitfalls: the sort key must be unique (always tail with id or another unique column); avoid floating-point sort keys; do not mix ASC/DESC directions inside the tuple. See pagination-performance.html for measured numbers and reproduction recipe.

Git-Like Branching — Fork-Test-Discard Sandboxes

Isolated copy-on-write branches: fork the database in an instant, test a destructive change (a migration, an experiment, an AI agent's writes) against real data, then discard the branch. main is never touched. This is the recommended pattern for giving every agent run its own sandbox.

CREATE BRANCH agent_run_42 FROM main;
USE BRANCH agent_run_42;

-- Changes here are invisible to main
INSERT INTO products (name, price) VALUES ('Test', 0.01);
UPDATE products SET price = price * 1.1;   -- rehearse the scary change
SELECT COUNT(*), SUM(price) FROM products; -- validate it

USE BRANCH main;
DROP BRANCH agent_run_42;                  -- discard; main never changed

Branches can also fork from a past point in time: CREATE BRANCH rewind FROM main AS OF TIMESTAMP '2026-06-01 09:00:00' (requires time-travel, which the agent profile keeps enabled).

Warning — MERGE BRANCH is currently unreliable. MERGE BRANCH x INTO main exists, but its three-way conflict detection over-reports and can mis-detect conflicts (the merge-base lookup reads the latest value instead of the historical base). If you do merge, verify the merged rows afterwards; a full fix is tracked (audit C11). Until then, prefer fork-test-discard: re-run the validated SQL on main instead of merging the branch.

Time-Travel Queries

-- As of a timestamp
SELECT * FROM products AS OF TIMESTAMP '2026-04-01 12:00:00';

-- As of a transaction
SELECT * FROM products AS OF TRANSACTION 12345;

Built-in Backend-as-a-Service

Self-hosted Supabase/Firebase alternative — Auth, REST, Realtime, RLS in the same binary:

# Sign up
curl -X POST http://localhost:8080/auth/v1/signup \
    -H 'Content-Type: application/json' \
    -d '{"email":"alice@example.com","password":"s3cret"}'

# Google OAuth redirect
open http://localhost:8080/auth/v1/authorize?provider=google

# Realtime subscriptions (WebSocket)
wscat -c ws://localhost:8080/realtime/v1/websocket

RLS is automatic on REST endpoints via JWT claims. See vs-supabase.

ORM & Driver Compatibility

WordPress runs natively with standard wpdb — no drop-in required.

Data Types

All PostgreSQL types plus MySQL type aliases (automatically translated):

Features at a Glance

• Full SQL: JOINs, CTEs, window functions, subqueries, set operations, aggregates, CASE
• PL/pgSQL: Stored procedures and functions
• Materialized views: CREATE / REFRESH MATERIALIZED VIEW, staleness tracking (\dmv, pg_mv_staleness())
• MVCC transactions: snapshot isolation; READ COMMITTED / REPEATABLE READ / SERIALIZABLE; first-committer-wins write-write conflict detection (SQLSTATE 40001)
• COPY (PostgreSQL wire): COPY … FROM STDIN / TO STDOUT in text and CSV — works with psql \copy and high-throughput PG→Nano bulk migration
• JSONB: ->, ->>, @>, ? operators
• Full-text search: tsvector, tsquery, @@, ts_rank_cd, CREATE INDEX ... USING gin (see FTS scope)
• Keyset pagination: row-constructor comparison WHERE (col, id) < ($1, $2); top-K sort; constant-time deep OFFSET
• Foreign keys: CASCADE, SET NULL, RESTRICT, deferred/audit/off validation modes, NOT ENFORCED constraints
• Triggers: BEFORE/AFTER INSERT/UPDATE/DELETE
• Row-Level Security: Per-tenant data isolation via policies
• EXPLAIN: Cost-based optimizer, ANALYZE, JSON/XML/YAML output
• Code-graph (opt-in, --features code-graph): tree-sitter-backed AST index + lsp_definition / lsp_references / lsp_call_hierarchy / lsp_hover as Rust API & SQL table functions — see code-graph overview
• Agentic SQL hooks: predict, infer, generate, and preview-only self-driving optimizer plans
• Backup/Restore: Compressed dumps (zstd/gzip/brotli)
• Import/Export: CSV, JSON, JSONL, Parquet, Arrow, SQL
• Audit logging: Tamper-proof trail (SHA-256 checksums)
• Encryption: AES-256-GCM TDE, FIPS 140-3 mode
• Unix domain socket listeners for both PostgreSQL (--pg-socket-dir /tmp) and MySQL (--mysql-socket /tmp/heliosdb.sock) — PHP mysqli / WordPress embedded-mode and libpq defaults work out of the box

Architecture

High Availability

Warm standby is enabled by default — no feature flag needed. Just pass the replication flags at startup:

# Primary
heliosdb-nano start --data-dir ./data --replication-role primary \
  --standby-hosts 10.0.0.2:5433,10.0.0.3:5433

# Standby
heliosdb-nano start --data-dir ./data --replication-role standby \
  --primary-host 10.0.0.1:5433

Optional HA features (opt-in at compile time):

cargo build --release --features ha-full    # everything

Tip — verify HA changes locally, not in CI: the HA streaming and lock-management integration tests rely on tight TCP-port spin-waits that pass cleanly on a developer workstation (sub-second) but routinely hang on the 2-CPU GitHub Actions runner. The release workflow gates on cargo test --lib only; if you're modifying anything under src/storage/wal/, src/cluster/, or src/storage/locks/, run the full integration suite locally first:

cargo test --features ha-tier1 --test ha_integration   # warm-standby + streaming
cargo test --tests --skip ha_tests::streaming_tests --skip lock_management

Connection Routing & Load Balancing

For production deployments with multiple HeliosDB Nano instances, put HeliosProxy in front — a standalone binary providing:

• Read/write splitting across primary + standbys
• Automatic failover with transaction replay (Oracle TAF-style)
• Connection pooling
• Health checks + circuit breakers
• TLS termination

Recommended Production Setup

           ┌────────────────┐
    psql ─▶│                │──▶ HeliosDB Nano (primary, read+write)
   mysql ─▶│  HeliosProxy   │──▶ HeliosDB Nano (standby, read-only)
    curl ─▶│                │──▶ HeliosDB Nano (standby, read-only)
           └────────────────┘
              port 5432/3306/8080

1. Deploy 1 primary + 2 standbys (Fly.io / Render / Docker Swarm)
2. HeliosProxy in front for routing + failover
3. Automatic failover on primary death (< 5 s typical)
4. Readonly queries load-balanced across standbys

Deploy

Embedded Library (Rust)

For in-process use (no network, no daemon), add the crate as a dependency:

[dependencies]
heliosdb-nano = "3.39"

See the Rust API guide for embedded usage and the examples/ directory for working code.

Building from Source

The heliosdb-nano binary builds with cargo build --release. Default features are encryption + vector-search + ring-crypto + ha-tier1 — covers most embedded and single-node-server cases. Run cargo info heliosdb-nano (or cargo metadata --no-deps --format-version 1 | jq '.packages[0].features') for the live list. Recipes for the non-obvious combinations:

# Default build — embedded + Postgres/MySQL wire + warm-standby HA.
cargo build --release

# Code-graph + MCP server (matches what heliosdb-codekb-mcp links).
# Adds tree-sitter parsers, _hdb_code_* tables, lsp_* APIs, and the
# JSON-RPC dispatcher for stdio / HTTP / WebSocket / SSE clients.
cargo build --release --features "code-graph,graph-rag,mcp-endpoint"

# In-process embedder (no external HTTP service for embeddings).
# Pulls fastembed-rs + ORT — adds ~30 MB to the binary.
cargo build --release --features "code-graph,code-embed"

# FIPS 140-3 compliant crypto (AWS-LC FIPS Cert #4816, SHA-256, PBKDF2).
# `--no-default-features` is required to swap out ring-crypto.
cargo build --release --no-default-features \
  --features "fips,encryption,vector-search,ha-tier1"

# Full HA bundle — multi-primary + sharding + dedup + branch replication.
cargo build --release --features "ha-full"

SDKs & Integrations

Official client SDKs (Go, Python, TypeScript, Rust) and platform integrations (VS Code, Zapier, n8n, Retool, Make, AutoGen) live in a shared repository:

heliosdb-sdks — works with all HeliosDB editions.

# JavaScript / TypeScript (Supabase-compatible fluent API)
npm install @heliosdb/client

import { createClient } from '@heliosdb/client'
const db = createClient('http://localhost:8080', 'anon-key')
const { data } = await db.from('products').select('*').lt('price', 50)

Agentic Operations (Claude Code, Codex CLI, MCP-aware tools)

The canonical way for an AI agent to operate Nano is MCP: build with --features mcp-endpoint, then claude mcp add heliosdb -- heliosdb-nano mcp serve --data-dir ./mydata (stdio; HTTP and WebSocket transports also available). The agent gets 16 structured tools — query, schema, insert, branch create/list/merge, time-travel, hybrid search — instead of building SQL strings. See the heliosdb-nano-mcp skill for the full catalog and recipes.

For any LLM that ingests a single reference file, docs/llms.txt condenses install, connect, the SQL dialect, vector operators, branch sandboxes, time-travel, and the skill catalogue into one agent-readable page.

For agent deployments, set profile = "agent" in the config (see config.example.toml): group-commit writes plus time-travel kept ON, so branchable sandboxes, AS OF queries, and vector search all work out of the box.

HeliosDB-Nano also ships an agentic-operations skill catalogue — 19 SKILL.md files that give an LLM-driven coding agent a full A→Z catalogue of "verbs" for operating the database (install, connect, schema, DML, transactions, branches, time-travel, backup, vector, code-graph, graph-rag, MCP, server, tenant, deploy, observability, migrate).

# After git clone, Claude Code automatically picks up .claude/skills/ in this project.

# To install globally (~/.claude/skills/) so they apply in any project:
bash scripts/install-agent-skills.sh                # copy (default, frozen snapshot)
bash scripts/install-agent-skills.sh --symlink      # symlink (live updates)

Existing ~/.claude/skills/heliosdb-nano-* directories are backed up to *.bak.<unix-ts> before being overwritten in either mode.

Installed via cargo install (no git checkout)? The skill files ship inside the published crate, so they are already on disk in cargo's registry cache — but scripts/install-agent-skills.sh is not packaged. Deploy them straight from the cache. The catalogue is plain Anthropic SKILL.md, so the same files also work in OpenCode and OpenAI Codex, which scan their own global skill dirs:

# Skills bundled inside the crate you installed (newest cached version):
SRC=$(ls -d ~/.cargo/registry/src/*/heliosdb-nano-*/.claude/skills 2>/dev/null | sort -V | tail -1)
echo "Deploying skills from: $SRC"

# Claude Code + OpenCode read ~/.claude/skills/ ; Codex + OpenCode read ~/.agents/skills/
for DEST in ~/.claude/skills ~/.agents/skills; do
  mkdir -p "$DEST"
  cp -r "$SRC"/heliosdb-nano-* "$DEST"/
  cp -r "$SRC"/_index "$DEST"/heliosdb-nano-_index   # verb-map + feature-matrix (reference docs, not a skill)
done

The cache path exists once cargo has extracted the crate (cargo install does this). If cargo GC'd it, run cargo fetch heliosdb-nano or reinstall. To pin a specific version instead of newest-cached, replace the SRC= glob with …/heliosdb-nano-<version>/.claude/skills. The _index folder has no SKILL.md, so OpenCode/Codex ignore it as a skill (it stays available as reference docs).

Lookups: .claude/skills/_index/verb-map.md (every CLI flag / REPL meta-command / public Rust API method / MCP tool) · .claude/skills/_index/feature-matrix.md (cargo feature ↔ skill).

Documentation

In-repo guides (docs/):

• Upgrade between Nano versions
• Database management — CREATE / DROP DATABASE
• Authentication — SCRAM-SHA-256, trust, password, TLS
• information_schema compatibility
• SQLite drop-in tutorial
• REPL demo
• HA cluster tutorial · HA testing
• Audit logging
• Tracing guide
• Full-text search · PL/pgSQL compatibility · SQLite compatibility
• Code-graph overview

Hosted docs:

• Getting Started
• API Explorer (Swagger UI) — when running locally
• vs Supabase
• vs Firebase
• vs PostgreSQL
• vs SQLite
• Migrate from MySQL

License

Apache-2.0 — Apache License, Version 2.0