---
title: "HeliosDB Nano Documentation"
---

# HeliosDB Nano Documentation

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

[![Rust](https://img.shields.io/badge/rust-1.85+-orange.svg)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://www.apache.org/licenses/LICENSE-2.0)

---

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

```rust
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

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

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

## Key Features

<div class="grid cards" markdown>

-:material-source-branch: **Database Branching**

    ---

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

    [:octicons-arrow-right-24: Learn more](https://www.heliosdb.com/docs/nano/features/branching/)

-: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](https://www.heliosdb.com/docs/nano/features/time-travel/)

-:material-vector-point: **Vector Search**

    ---

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

    [:octicons-arrow-right-24: Learn more](https://www.heliosdb.com/docs/nano/features/vector-search/)

-:material-table-refresh: **Materialized Views**

    ---

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

    [:octicons-arrow-right-24: Learn more](https://www.heliosdb.com/docs/nano/features/materialized-views/)

</div>

## 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](https://www.heliosdb.com/docs/nano/getting-started/)** - Installation, quick start, deployment
- **[User Guide](https://www.heliosdb.com/docs/nano/user-guide/sql-reference/)** - SQL reference, REPL commands, configuration
- **[Features](https://www.heliosdb.com/docs/nano/features/)** - Branching, time-travel, vectors, security
- **[API Reference](https://www.heliosdb.com/docs/nano/api/rest-api/)** - REST API, Rust, Python, TypeScript, Go SDKs
- **[Developer Guide](https://www.heliosdb.com/docs/nano/developer/architecture/)** - Architecture, contributing

**Need help?** Check the [FAQ](https://www.heliosdb.com/docs/nano/resources/faq/) or [open an issue](https://github.com/HeliosDatabase/HeliosDB-Nano/issues).