Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/heliosdatabase/heliosdb-nano

Embedded SQL database for local-first apps, AI memory, edge analytics, and developer workflows.
https://github.com/heliosdatabase/heliosdb-nano

database

Last synced: 2 days ago
JSON representation

Embedded SQL database for local-first apps, AI memory, edge analytics, and developer workflows.

Awesome Lists containing this project

README 

          
# HeliosDB Nano



[![Crates.io](https://img.shields.io/crates/v/heliosdb-nano.svg)](https://crates.io/crates/heliosdb-nano)

[![Documentation](https://docs.rs/heliosdb-nano/badge.svg)](https://docs.rs/heliosdb-nano)

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)



**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](https://github.com/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](https://github.com/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](https://github.com/HeliosDatabase/HeliosDB-Lite)** — Production self-hosted database with HeliosProxy + HeliosCore baked in. SSPL-1.0.

- **[HeliosDatabase/HeliosDB-Full](https://github.com/HeliosDatabase/HeliosDB-Full)** — Distributed enterprise database with 14 native wire protocols. SSPL-1.0.

- **[HeliosDatabase/HeliosDB-Proxy](https://github.com/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](https://github.com/HeliosDatabase/HeliosDB-Proxy-Plugins)** · **[Operator](https://github.com/HeliosDatabase/HeliosDB-Proxy-Operator)** · **[Terraform](https://github.com/HeliosDatabase/terraform-provider-HeliosDB-Proxy)** · **[Pulumi](https://github.com/HeliosDatabase/pulumi-HeliosDB-Proxy)** — Proxy ecosystem.



**[HeliosDatabase/HeliosDB-CodeKB-MCP](https://github.com/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](https://www.heliosdb.com/sdks.html) · **Build with AI agents:** [heliosdb.com/build-with-agents.html](https://www.heliosdb.com/build-with-agents.html) · **LLM-discoverable index:** [heliosdb.com/llms.txt](https://www.heliosdb.com/llms.txt)



**Performance:** [what's fast, and where we're still improving](docs/PERFORMANCE.md) — honest strengths + transparent limits.



**Benchmark:** [HeliosDB-Nano vs PostgreSQL 18.4 — the `pg35` benchmark, its history & evolution](docs/benchmarks/PG35_BENCHMARK.md) — 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`:



```bash

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](https://rustup.rs/), then open a new

terminal so `cargo` is on `PATH`.



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



```bash

cargo install heliosdb-nano --locked

heliosdb-nano --version

```



Use Nano as an embedded Rust library:



```bash

cargo add heliosdb-nano

```



Enable optional crate features when installing or adding the dependency:



```bash

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

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

```



Build from source:



```bash

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**](https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest)

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.



```bash

# Example: Linux x86_64 (see Releases for macOS arm64 / Linux aarch64 / Windows)

VER=

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



```bash

# 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:



| Protocol | Port | Connect |

|----------|-----:|---------|

| PostgreSQL wire | 5432 | `psql`, psycopg2, pgx, JDBC, Npgsql, node-postgres |

| PostgreSQL Unix socket | `/tmp/.s.PGSQL.5432` | `psql -h /tmp`, libpq-default apps |

| MySQL wire | 3306 | `mysql`, PyMySQL, SQLAlchemy, JDBC, mysql2 |

| MySQL Unix socket | `/tmp/heliosdb-mysql.sock` (configurable) | `mysql --socket=…`, PHP `mysqli`, WordPress |

| REST / HTTP | 8080 | `curl`, fetch, any HTTP client |



## 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)



```bash

$ 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`)



```bash

$ 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`)



```bash

$ 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`)



```bash

# 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'`.



```sql

-- 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:



```bash

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:



```sql

-- 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](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.



```sql

-- 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](https://heliosdb.com/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.



```sql

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



```sql

-- 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:



```bash

# 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](https://heliosdb.com/vs-supabase.html).



## ORM & Driver Compatibility



| Language | PostgreSQL driver | MySQL driver | Tested ORMs |

|----------|------------------|--------------|-------------|

| Python | `psycopg2`, `asyncpg` | `PyMySQL`, `mysql-connector-python` | SQLAlchemy, Django ORM |

| Node.js | `pg`, `node-postgres` | `mysql2` | Prisma, Drizzle, TypeORM, Sequelize |

| Java | JDBC (postgresql) | JDBC (mysql-connector-j) | Hibernate, JPA |

| Go | `lib/pq`, `pgx` | `go-sql-driver/mysql` | GORM, ent |

| Rust | `tokio-postgres`, `sqlx` | `mysql_async`, `sqlx` | SeaORM, Diesel |

| PHP | PDO pgsql | `mysqli`, PDO mysql | Laravel Eloquent, WordPress |



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



## Data Types



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



| Canonical | Aliases |

|-----------|---------|

| `BOOLEAN` | `BOOL`, `TINYINT(1)` |

| `SMALLINT` / `INTEGER` / `BIGINT` | `INT2`/`INT4`/`INT8`, `TINYINT`, `MEDIUMINT` |

| `REAL` / `DOUBLE PRECISION` | `FLOAT4`/`FLOAT8`, `FLOAT(N)` |

| `NUMERIC(p,s)` | `DECIMAL(p,s)` |

| `TEXT` | `VARCHAR(n)`, `LONGTEXT`, `MEDIUMTEXT`, `TINYTEXT` |

| `BYTEA` | `BLOB`, `LONGBLOB`, `MEDIUMBLOB` |

| `TIMESTAMP` | `DATETIME` |

| `SERIAL` / `BIGSERIAL` | `INT AUTO_INCREMENT`, `BIGINT AUTO_INCREMENT` |

| `UUID`, `JSON`, `JSONB`, `VECTOR(n)`, `ARRAY` | — |

| `TSVECTOR`, `TSQUERY` | stored as JSON arrays of normalised tokens |



## 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](docs/compatibility/fts.md))

- **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](docs/code_graph/overview.md)

- **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



| Layer | Technology |

|-------|-----------|

| Storage engine | RocksDB (LSM-tree) |

| Columnar format | Apache Arrow |

| SQL parser | sqlparser-rs |

| Vector index | HNSW + Product Quantization |

| Wire protocols | PostgreSQL v3, MySQL v10 |

| HTTP server | Axum |

| Encryption | AES-256-GCM, AWS-LC FIPS |



## High Availability



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



```bash

# 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):



| Flag | Description |

|------|-------------|

| `ha-tier1` | Warm standby — **enabled by default** |

| `ha-tier2` | Multi-primary: branch-based active-active |

| `ha-tier3` | Sharding: consistent hash ring |

| `ha-dedup` | Content-addressed deduplication across nodes |

| `ha-ab-testing` | Branch-based experiment routing |

| `ha-branch-replication` | Selective branch sync to remote servers |

| `ha-full` | All optional HA features bundled |



```bash

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:

>

> ```bash

> 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](https://github.com/HeliosDatabase/HeliosDB-Proxy)** 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



| Platform | Template |

|----------|----------|

| **Fly.io** | [deployment/flyio/](deployment/flyio/) |

| **Railway** | [deployment/railway/](deployment/railway/) |

| **Render** | [deployment/render/](deployment/render/) |

| **Docker** | [deployment/docker/](deployment/docker/) |



## Embedded Library (Rust)



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



```toml

[dependencies]

heliosdb-nano = "3.39"

```



See **[the Rust API guide](https://docs.rs/heliosdb-nano)** for embedded usage and the [examples/](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:



```bash

# 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](https://github.com/HeliosDatabase/HeliosDB-SDKs)** — works with all HeliosDB editions.



```bash

# JavaScript / TypeScript (Supabase-compatible fluent API)

npm install @heliosdb/client

```



```javascript

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`](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](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).



```bash

# 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.` 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`](https://agentskills.io), so the same files also work in **OpenCode** and **OpenAI Codex**, which scan their own global skill dirs:



```bash

# 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

```



| Agent | Global skill dir(s) it scans | Notes |

|-------|------------------------------|-------|

| **Claude Code** | `~/.claude/skills/` | Auto-discovered at next session start. |

| **OpenCode** | `~/.claude/skills/`, `~/.agents/skills/`, `~/.config/opencode/skills/` | Loaded on demand via the native `skill` tool; if your permission policy is `ask`/`deny`, allow that tool. |

| **OpenAI Codex** | `~/.agents/skills/` (personal), `.agents/skills/` (per-repo, team), `/etc/codex/skills/` (admin). The Codex CLI also scans `~/.codex/skills/`. | Auto-selected by `description`, or invoke `/skills` / `$heliosdb-nano-…`. Restart Codex if new skills don't appear. |



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-/.claude/skills`. The `_index` folder has no `SKILL.md`, so OpenCode/Codex ignore it as a skill (it stays available as reference docs).



| Skill | What it covers |

|-------|---------------|

| `heliosdb-nano-overview` | Top-level navigation; routes to the domain skills |

| `heliosdb-nano-install` | crates.io, source, feature flags (code-graph, mcp-endpoint, fips, ha-full…) |

| `heliosdb-nano-connect` | Embedded library, REPL, PG wire, MySQL wire, Python sqlite3 drop-in, TLS |

| `heliosdb-nano-schema` | DDL: tables, indexes (B-tree + HNSW), views, triggers, PL/pgSQL |

| `heliosdb-nano-query` | DML, parameter styles (`?` `$1` `:name` `@name`), `ON CONFLICT`, `RETURNING` |

| `heliosdb-nano-transactions` | BEGIN/COMMIT/ROLLBACK, savepoints, bulk-load patterns |

| `heliosdb-nano-branches` | Fork-test-discard sandboxes: `CREATE/USE/DROP DATABASE BRANCH`, `AS OF` forks |

| `heliosdb-nano-time-travel` | `SELECT … AS OF TIMESTAMP '…'`, `\snapshots` |

| `heliosdb-nano-backup` | `dump`/`restore`, compression, append, partial restore, `--dump-schedule` |

| `heliosdb-nano-vector` | HNSW indexes, `<-> <#> <=>` operators, hybrid search |

| `heliosdb-nano-code-graph` | AST symbol index, LSP queries, git hook (`code-graph` feature) |

| `heliosdb-nano-graph-rag` | Knowledge graph + RAG ingest pipeline (`graph-rag` feature) |

| `heliosdb-nano-mcp` | MCP server, 16-tool catalog, stdio/HTTP/WS (`mcp-endpoint` feature) |

| `heliosdb-nano-server` | Daemon, TLS, auth, HA tier 1/2/3, user management |

| `heliosdb-nano-tenant` | Multi-tenant isolation modes, tiered plans, RLS policies |

| `heliosdb-nano-deploy` | Docker, Fly.io, Railway, Render, systemd template |

| `heliosdb-nano-observability` | Tracing, slow-query log, `/health`, `\stats`, `\optimize`, `\indexes` |

| `heliosdb-nano-migrate` | sqlite3 / Postgres / MySQL drop-in checklists |

| `heliosdb-nano-merge-validation` | This repo's 8-phase pre-merge validation methodology (contributors) |



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



## Documentation



In-repo guides (`docs/`):



- [Upgrade between Nano versions](docs/guides/upgrade.md)

- [Database management — `CREATE` / `DROP DATABASE`](docs/guides/database_management.md)

- [Authentication — SCRAM-SHA-256, trust, password, TLS](docs/guides/authentication.md)

- [`information_schema` compatibility](docs/compatibility/information_schema.md)

- [SQLite drop-in tutorial](docs/guides/sqlite_drop_in_tutorial.md)

- [REPL demo](docs/guides/repl_demo.md)

- [HA cluster tutorial](docs/guides/ha_cluster_tutorial.md) · [HA testing](docs/guides/ha_testing.md)

- [Audit logging](docs/guides/audit.md)

- [Tracing guide](docs/TRACING_GUIDE.md)

- [Full-text search](docs/compatibility/fts.md) · [PL/pgSQL compatibility](docs/compatibility/plpgsql.md) · [SQLite compatibility](docs/compatibility/sqlite.md)

- [Code-graph overview](docs/code_graph/overview.md)



Hosted docs:



- [Getting Started](https://heliosdb.com/nano.html)

- [API Explorer (Swagger UI)](http://localhost:8080/docs) — when running locally

- [vs Supabase](https://heliosdb.com/vs-supabase.html)

- [vs Firebase](https://heliosdb.com/vs-firebase.html)

- [vs PostgreSQL](https://heliosdb.com/vs-postgresql.html)

- [vs SQLite](https://heliosdb.com/vs-sqlite.html)

- [Migrate from MySQL](https://heliosdb.com/migrate-mysql.html)



## License



[Apache-2.0](LICENSE) — Apache License, Version 2.0