HeliosDB Nano Documentation

High-performance embedded database with vector search, time-travel queries, and Git-like branching

What is HeliosDB Nano?

HeliosDB Nano is a lightweight, embeddable database engine written in Rust that combines the simplicity of SQLite with advanced features typically found in enterprise databases:

PostgreSQL-Compatible SQL - Standard SQL syntax with 95%+ PostgreSQL compatibility
Vector Search - Built-in HNSW indexing for similarity search and AI/ML applications
Database Branching - Git-like branching for development, testing, and experimentation
Time-Travel Queries - Query historical data at any point in time
Materialized Views - Automatic and incremental view refresh
Multi-Tenancy - Row-level security and tenant isolation

Quick Start

Installation

=== “Cargo (Rust)”

```bash
cargo add heliosdb-nano
```

=== “pip (Python, embedded binding)”

```bash
pip install heliosdb-nano-embedded   # import heliosdb_nano
```

The PyPI binding is published separately and currently lags the engine;
for the current engine from Python, connect over the PostgreSQL wire protocol.

=== “Prebuilt binary”

```bash
# Latest release tag (pin a specific tag in production)
VER=$(curl -sSf https://api.github.com/repos/HeliosDatabase/HeliosDB-Nano/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
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
```

Linux (x86_64 / aarch64), macOS (arm64) and Windows (x86_64) archives, plus
`SHA256SUMS`, are on the [GitHub Releases](https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest) page.
There is no npm package for Nano; from Node.js connect over the PostgreSQL
wire protocol (e.g. `pg`) or the REST API.

Basic Usage

use heliosdb_nano::EmbeddedDatabase;

// Create or open database
let db = EmbeddedDatabase::new("./mydb")?;

// Create table
db.execute("CREATE TABLE users (id INT PRIMARY KEY, name TEXT)")?;

// Insert data
db.execute("INSERT INTO users VALUES (1, 'Alice')")?;

// Query
let results = db.query("SELECT * FROM users")?;

Try the REPL

# Start interactive shell
heliosdb-nano repl --data-dir ./mydb

# Or in-memory mode
heliosdb-nano repl --memory

Key Features

-:material-source-branch: Database Branching

---

Create isolated branches for development, testing, or experimentation without duplicating data.

[:octicons-arrow-right-24: Learn more](features/branching.md)

-:material-clock-time-four: Time-Travel Queries

---

Query data as it existed at any point in time using `AS OF TIMESTAMP` syntax.

[:octicons-arrow-right-24: Learn more](features/time-travel.md)

-:material-vector-point: Vector Search

---

Built-in HNSW vector indexing for similarity search, RAG applications, and embeddings.

[:octicons-arrow-right-24: Learn more](features/vector-search.md)

-:material-table-refresh: Materialized Views

---

Auto-refreshing views with incremental updates and CPU-aware scheduling.

[:octicons-arrow-right-24: Learn more](features/materialized-views.md)

Deployment Options

Mode	Description	Best For
Embedded	In-process library	Applications, edge devices, testing
Server	PostgreSQL-compatible server	Multi-client access, production
In-Memory	RAM-only storage	Testing, caching, ephemeral data

Documentation Sections

Getting Started - Installation, quick start, deployment
User Guide - SQL reference, REPL commands, configuration
Features - Branching, time-travel, vectors, security
API Reference - REST API, Rust, Python, TypeScript, Go SDKs
Developer Guide - Architecture, contributing

Need help? Check the FAQ or open an issue.