{"id":50492641,"url":"https://github.com/heliosdatabase/heliosdb-nano","last_synced_at":"2026-06-28T11:00:36.475Z","repository":{"id":355033603,"uuid":"1149970736","full_name":"HeliosDatabase/HeliosDB-Nano","owner":"HeliosDatabase","description":"Embedded SQL database for local-first apps, AI memory, edge analytics, and developer workflows.","archived":false,"fork":false,"pushed_at":"2026-06-26T06:10:14.000Z","size":47294,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T06:21:01.508Z","etag":null,"topics":["database"],"latest_commit_sha":null,"homepage":"https://www.heliosdb.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HeliosDatabase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-04T18:24:41.000Z","updated_at":"2026-06-26T06:10:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/HeliosDatabase/HeliosDB-Nano","commit_stats":null,"previous_names":["dimensigon/hdb-heliosdb-nano","heliosdatabase/heliosdb-nano"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/HeliosDatabase/HeliosDB-Nano","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HeliosDatabase%2FHeliosDB-Nano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HeliosDatabase%2FHeliosDB-Nano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HeliosDatabase%2FHeliosDB-Nano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HeliosDatabase%2FHeliosDB-Nano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HeliosDatabase","download_url":"https://codeload.github.com/HeliosDatabase/HeliosDB-Nano/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HeliosDatabase%2FHeliosDB-Nano/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34885802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database"],"created_at":"2026-06-02T04:03:06.717Z","updated_at":"2026-06-28T11:00:36.467Z","avatar_url":"https://github.com/HeliosDatabase.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HeliosDB Nano\n\n[![Crates.io](https://img.shields.io/crates/v/heliosdb-nano.svg)](https://crates.io/crates/heliosdb-nano)\n[![Documentation](https://docs.rs/heliosdb-nano/badge.svg)](https://docs.rs/heliosdb-nano)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n**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).\n\nUse 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.\n\n## Ecosystem\n\nNano 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.\n\n- **[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.\n- **[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.\n- **[HeliosDatabase/HeliosDB-Lite](https://github.com/HeliosDatabase/HeliosDB-Lite)** — Production self-hosted database with HeliosProxy + HeliosCore baked in. SSPL-1.0.\n- **[HeliosDatabase/HeliosDB-Full](https://github.com/HeliosDatabase/HeliosDB-Full)** — Distributed enterprise database with 14 native wire protocols. SSPL-1.0.\n- **[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.\n- **[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.\n\n**[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.\n\n**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)\n\n**Performance:** [what's fast, and where we're still improving](docs/PERFORMANCE.md) — honest strengths + transparent limits.\n\n**Benchmark:** [HeliosDB-Nano vs PostgreSQL 18.4 — the `pg35` benchmark, its history \u0026 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.\n\n## Install\n\n### Supported now: Cargo / crates.io\n\nInstall Rust and Cargo first. On Linux, macOS, or WSL, the recommended installer\nis `rustup`:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nsource \"$HOME/.cargo/env\"\nrustc --version\ncargo --version\n```\n\nOn Windows, install Rust from [rustup.rs](https://rustup.rs/), then open a new\nterminal so `cargo` is on `PATH`.\n\nInstall the `heliosdb-nano` CLI binary from crates.io:\n\n```bash\ncargo install heliosdb-nano --locked\nheliosdb-nano --version\n```\n\nUse Nano as an embedded Rust library:\n\n```bash\ncargo add heliosdb-nano\n```\n\nEnable optional crate features when installing or adding the dependency:\n\n```bash\ncargo install heliosdb-nano --locked --features code-graph,mcp-endpoint\ncargo add heliosdb-nano --features code-graph,mcp-endpoint\n```\n\nBuild from source:\n\n```bash\ngit clone https://github.com/HeliosDatabase/HeliosDB-Nano.git\ncd HeliosDB-Nano\ncargo build --release --locked\n./target/release/heliosdb-nano --version\n```\n\n### Prebuilt Binaries\n\nGrab a self-contained binary from the [**GitHub Releases**](https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest)\npage — Linux (`x86_64` / `aarch64`), macOS (`aarch64`), and Windows (`x86_64`),\neach with `SHA256SUMS`. No Rust toolchain required: download the archive for your\nplatform, verify it against `SHA256SUMS`, extract, and run the `heliosdb-nano`\nbinary.\n\n```bash\n# Example: Linux x86_64 (see Releases for macOS arm64 / Linux aarch64 / Windows)\nVER=\u003crelease-tag\u003e\ncurl -sSfL -O \"https://github.com/HeliosDatabase/HeliosDB-Nano/releases/download/$VER/heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz\"\ntar xzf \"heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz\"\n./heliosdb-nano --version\n```\n\n### Install Channels\n\nUse Cargo or the GitHub release binaries for a verified install. Package-manager\nchannels such as npm, Homebrew, and container images should be treated as\navailable only when they are listed on the official releases page.\n\n## Start the Server\n\n```bash\n# Persistent, all three protocols\nheliosdb-nano start --data-dir ./mydata --mysql\n\n# In-memory (great for dev/test)\nheliosdb-nano start --memory --mysql\n\n# With auth and TLS\nheliosdb-nano start --data-dir ./mydata --mysql \\\n  --auth scram-sha-256 --password s3cret \\\n  --tls-cert cert.pem --tls-key key.pem\n\n# Same-host / embedded mode — Unix sockets (no TCP)\nheliosdb-nano start --memory \\\n  --pg-socket-dir /tmp \\\n  --mysql --mysql-socket /tmp/heliosdb-mysql.sock\n# then: psql -h /tmp  or  mysql --socket=/tmp/heliosdb-mysql.sock\n```\n\nThree servers start on one process:\n\n| Protocol | Port | Connect |\n|----------|-----:|---------|\n| PostgreSQL wire | 5432 | `psql`, psycopg2, pgx, JDBC, Npgsql, node-postgres |\n| PostgreSQL Unix socket | `/tmp/.s.PGSQL.5432` | `psql -h /tmp`, libpq-default apps |\n| MySQL wire | 3306 | `mysql`, PyMySQL, SQLAlchemy, JDBC, mysql2 |\n| MySQL Unix socket | `/tmp/heliosdb-mysql.sock` (configurable) | `mysql --socket=…`, PHP `mysqli`, WordPress |\n| REST / HTTP | 8080 | `curl`, fetch, any HTTP client |\n\n## Triple Compatibility — Same Data, Any Client\n\nStart the server once, then connect from any of the three interfaces. They all read and write the same tables.\n\n### Interactive REPL (zero setup)\n\n```bash\n$ heliosdb-nano repl --data-dir ./mydata\nheliosdb\u003e CREATE TABLE products (id SERIAL PRIMARY KEY, name TEXT, price DECIMAL(10,2));\nOK\nheliosdb\u003e INSERT INTO products (name, price) VALUES ('Widget', 9.99), ('Gadget', 19.99);\nINSERT 2\nheliosdb\u003e SELECT * FROM products WHERE price \u003c 15;\n id |  name  | price\n----+--------+-------\n  1 | Widget |  9.99\n(1 row)\n```\n\n### PostgreSQL Client (`psql`)\n\n```bash\n$ psql -h 127.0.0.1 -p 5432 -U postgres\npsql (server HeliosDB Nano)\npostgres=# INSERT INTO products (name, price) VALUES ('Gizmo', 29.99);\nINSERT 0 1\npostgres=# SELECT COUNT(*) FROM products;\n count\n-------\n     3\n```\n\n### MySQL Client (`mysql`)\n\n```bash\n$ mysql -h 127.0.0.1 -P 3306 -u root\nServer version: HeliosDB-Nano\nmysql\u003e SELECT * FROM products WHERE name LIKE 'G%';\n+----+--------+-------+\n| id | name   | price |\n+----+--------+-------+\n|  2 | Gadget | 19.99 |\n|  3 | Gizmo  | 29.99 |\n+----+--------+-------+\nmysql\u003e INSERT INTO products (name, price) VALUES ('Gear', 39.99);\nQuery OK, 1 row affected\n```\n\n### REST API (`curl`)\n\n```bash\n# Query\n$ curl \"http://localhost:8080/rest/v1/products?price=lt.50\u0026select=id,name,price\"\n[{\"id\":1,\"name\":\"Widget\",\"price\":\"9.99\"},{\"id\":2,\"name\":\"Gadget\",\"price\":\"19.99\"}, ...]\n\n# Insert\n$ curl -X POST http://localhost:8080/rest/v1/products \\\n    -H 'Content-Type: application/json' \\\n    -d '{\"name\":\"Gear 2\",\"price\":49.99}'\n\n# Interactive API explorer (Swagger UI)\n$ open http://localhost:8080/docs\n```\n\n## Vector Search\n\nNative HNSW indexes — no extensions, no separate vector database. The default\npath is in-process HNSW; `--features vector-persist` enables RocksDB-backed\npersistent HNSW/PQ with `persistent = true`, `quantization = 'product'`, and\n`rerank_precision = 'f32' | 'f16' | 'i8'`.\n\n```sql\n-- From any client (psql / mysql / REPL):\nCREATE TABLE docs (\n    id SERIAL PRIMARY KEY,\n    title TEXT,\n    embedding VECTOR(1536)\n);\n\nCREATE INDEX ON docs USING hnsw (embedding vector_cosine_ops);\nCREATE INDEX docs_embedding_persistent ON docs USING hnsw (embedding)\nWITH (persistent = true, quantization = 'product', rerank_precision = 'i8');\n\nINSERT INTO docs (title, embedding)\nVALUES ('Intro', '[0.1, 0.2, 0.3, ...]');\n\n-- k-NN search\nSELECT title, embedding \u003c-\u003e '[0.15, 0.25, ...]' AS distance\nFROM docs\nORDER BY distance\nLIMIT 10;\n```\n\nDistance operators: `\u003c-\u003e` (L2), `\u003c=\u003e` (cosine), `\u003c#\u003e` (inner product).\nVector store IDs are namespace-scoped, and metadata/namespace filters are\napplied before top-k selection in the REST/embedded vector-store API.\n\nVia REST:\n\n```bash\ncurl -X POST http://localhost:8080/api/vectors/search \\\n    -H 'Content-Type: application/json' \\\n    -d '{\"collection\":\"docs\",\"query\":[0.15,0.25],\"k\":5,\"metric\":\"cosine\"}'\n```\n\n## Full-Text Search\n\nPostgreSQL-compatible FTS surface — no extensions, backed by built-in BM25:\n\n```sql\n-- Native tsvector / tsquery / @@ / ts_rank_cd:\nSELECT title, ts_rank_cd(to_tsvector(body), to_tsquery('heliosdb')) AS rank\nFROM articles\nWHERE to_tsvector(body) @@ to_tsquery('heliosdb')\nORDER BY rank DESC\nLIMIT 10;\n\n-- Persistent tsvector column + GIN-style DDL:\nCREATE TABLE articles (id SERIAL PRIMARY KEY, body TEXT, body_tsv TSVECTOR);\nCREATE INDEX articles_body_fts ON articles USING gin (body_tsv);\n\n-- Hybrid search (FTS + vector) in one query:\nSELECT id, text,\n       0.7 * (1.0 - (embedding \u003c=\u003e $1::vector))\n     + 0.3 * ts_rank_cd(to_tsvector(text), plainto_tsquery($2)) AS score\nFROM chunks\nORDER BY score DESC LIMIT 10;\n```\n\nScope and honest limitations: see [docs/compatibility/fts.md](docs/compatibility/fts.md).\n\n## Pagination — Constant-Time at Depth\n\nDeep `LIMIT … OFFSET` runs in **~30 µs regardless of offset** — constant-time,\nwhere a stock row-store re-scans every skipped row (linear in the offset).\nTop-K over Sort, storage-level `OFFSET` skip, and keyset\n(`WHERE (col, id) \u003c ($1, $2)`) are all native.\n\n```sql\n-- Traditional LIMIT / OFFSET — constant-time at any depth via storage-level skip\nSELECT id, created_at, subject\n  FROM leads\n ORDER BY created_at DESC, id DESC\n LIMIT 20 OFFSET 100000;\n\n-- Keyset (row-constructor tuple) — preferred for high-volume lists\nSELECT id, created_at, subject\n  FROM leads\n WHERE (created_at, id) \u003c ($1, $2)\n ORDER BY created_at DESC, id DESC\n LIMIT 20;\n\n-- JOIN + pagination composes cleanly\nSELECT l.id, l.subject, c.name AS company\n  FROM leads l\n  LEFT OUTER JOIN companies c ON l.company_id = c.id\n WHERE (l.created_at, l.id) \u003c ($1, $2)\n ORDER BY l.created_at DESC, l.id DESC\n LIMIT 20;\n```\n\nPitfalls: the sort key must be unique (always tail with `id` or another unique\ncolumn); avoid floating-point sort keys; do not mix `ASC`/`DESC` directions\ninside the tuple. See\n[pagination-performance.html](https://heliosdb.com/pagination-performance.html)\nfor measured numbers and reproduction recipe.\n\n## Git-Like Branching — Fork-Test-Discard Sandboxes\n\nIsolated copy-on-write branches: fork the database in an instant, test a\ndestructive change (a migration, an experiment, an AI agent's writes) against\nreal data, then discard the branch. `main` is never touched. This is the\nrecommended pattern for giving every agent run its own sandbox.\n\n```sql\nCREATE BRANCH agent_run_42 FROM main;\nUSE BRANCH agent_run_42;\n\n-- Changes here are invisible to main\nINSERT INTO products (name, price) VALUES ('Test', 0.01);\nUPDATE products SET price = price * 1.1;   -- rehearse the scary change\nSELECT COUNT(*), SUM(price) FROM products; -- validate it\n\nUSE BRANCH main;\nDROP BRANCH agent_run_42;                  -- discard; main never changed\n```\n\nBranches can also fork from a past point in time:\n`CREATE BRANCH rewind FROM main AS OF TIMESTAMP '2026-06-01 09:00:00'`\n(requires time-travel, which the `agent` profile keeps enabled).\n\n\u003e **Warning — `MERGE BRANCH` is currently unreliable.** `MERGE BRANCH x INTO\n\u003e main` exists, but its three-way conflict detection over-reports and can\n\u003e mis-detect conflicts (the merge-base lookup reads the latest value instead of\n\u003e the historical base). If you do merge, verify the merged rows afterwards;\n\u003e a full fix is tracked (audit C11). Until then, prefer fork-test-discard:\n\u003e re-run the validated SQL on `main` instead of merging the branch.\n\n## Time-Travel Queries\n\n```sql\n-- As of a timestamp\nSELECT * FROM products AS OF TIMESTAMP '2026-04-01 12:00:00';\n\n-- As of a transaction\nSELECT * FROM products AS OF TRANSACTION 12345;\n```\n\n## Built-in Backend-as-a-Service\n\nSelf-hosted Supabase/Firebase alternative — Auth, REST, Realtime, RLS in the same binary:\n\n```bash\n# Sign up\ncurl -X POST http://localhost:8080/auth/v1/signup \\\n    -H 'Content-Type: application/json' \\\n    -d '{\"email\":\"alice@example.com\",\"password\":\"s3cret\"}'\n\n# Google OAuth redirect\nopen http://localhost:8080/auth/v1/authorize?provider=google\n\n# Realtime subscriptions (WebSocket)\nwscat -c ws://localhost:8080/realtime/v1/websocket\n```\n\nRLS is automatic on REST endpoints via JWT claims. See [vs-supabase](https://heliosdb.com/vs-supabase.html).\n\n## ORM \u0026 Driver Compatibility\n\n| Language | PostgreSQL driver | MySQL driver | Tested ORMs |\n|----------|------------------|--------------|-------------|\n| Python | `psycopg2`, `asyncpg` | `PyMySQL`, `mysql-connector-python` | SQLAlchemy, Django ORM |\n| Node.js | `pg`, `node-postgres` | `mysql2` | Prisma, Drizzle, TypeORM, Sequelize |\n| Java | JDBC (postgresql) | JDBC (mysql-connector-j) | Hibernate, JPA |\n| Go | `lib/pq`, `pgx` | `go-sql-driver/mysql` | GORM, ent |\n| Rust | `tokio-postgres`, `sqlx` | `mysql_async`, `sqlx` | SeaORM, Diesel |\n| PHP | PDO pgsql | `mysqli`, PDO mysql | Laravel Eloquent, WordPress |\n\n**WordPress runs natively** with standard `wpdb` — no drop-in required.\n\n## Data Types\n\nAll PostgreSQL types plus MySQL type aliases (automatically translated):\n\n| Canonical | Aliases |\n|-----------|---------|\n| `BOOLEAN` | `BOOL`, `TINYINT(1)` |\n| `SMALLINT` / `INTEGER` / `BIGINT` | `INT2`/`INT4`/`INT8`, `TINYINT`, `MEDIUMINT` |\n| `REAL` / `DOUBLE PRECISION` | `FLOAT4`/`FLOAT8`, `FLOAT(N)` |\n| `NUMERIC(p,s)` | `DECIMAL(p,s)` |\n| `TEXT` | `VARCHAR(n)`, `LONGTEXT`, `MEDIUMTEXT`, `TINYTEXT` |\n| `BYTEA` | `BLOB`, `LONGBLOB`, `MEDIUMBLOB` |\n| `TIMESTAMP` | `DATETIME` |\n| `SERIAL` / `BIGSERIAL` | `INT AUTO_INCREMENT`, `BIGINT AUTO_INCREMENT` |\n| `UUID`, `JSON`, `JSONB`, `VECTOR(n)`, `ARRAY` | — |\n| `TSVECTOR`, `TSQUERY` | stored as JSON arrays of normalised tokens |\n\n## Features at a Glance\n\n- **Full SQL**: JOINs, CTEs, window functions, subqueries, set operations, aggregates, CASE\n- **PL/pgSQL**: Stored procedures and functions\n- **Materialized views**: `CREATE` / `REFRESH MATERIALIZED VIEW`, staleness tracking (`\\dmv`, `pg_mv_staleness()`)\n- **MVCC transactions**: snapshot isolation; `READ COMMITTED` / `REPEATABLE READ` / `SERIALIZABLE`; first-committer-wins write-write conflict detection (SQLSTATE `40001`)\n- **COPY (PostgreSQL wire)**: `COPY … FROM STDIN` / `TO STDOUT` in text and CSV — works with `psql \\copy` and high-throughput PG→Nano bulk migration\n- **JSONB**: `-\u003e`, `-\u003e\u003e`, `@\u003e`, `?` operators\n- **Full-text search**: `tsvector`, `tsquery`, `@@`, `ts_rank_cd`, `CREATE INDEX ... USING gin` (see [FTS scope](docs/compatibility/fts.md))\n- **Keyset pagination**: row-constructor comparison `WHERE (col, id) \u003c ($1, $2)`; top-K sort; constant-time deep OFFSET\n- **Foreign keys**: CASCADE, SET NULL, RESTRICT, deferred/audit/off validation modes, `NOT ENFORCED` constraints\n- **Triggers**: BEFORE/AFTER INSERT/UPDATE/DELETE\n- **Row-Level Security**: Per-tenant data isolation via policies\n- **EXPLAIN**: Cost-based optimizer, ANALYZE, JSON/XML/YAML output\n- **Code-graph** *(opt-in, `--features code-graph`)*: tree-sitter-backed AST index + `lsp_definition` / `lsp_references` / `lsp_call_hierarchy` / `lsp_hover` as Rust API \u0026 SQL table functions — see [code-graph overview](docs/code_graph/overview.md)\n- **Agentic SQL hooks**: `predict`, `infer`, `generate`, and preview-only self-driving optimizer plans\n- **Backup/Restore**: Compressed dumps (zstd/gzip/brotli)\n- **Import/Export**: CSV, JSON, JSONL, Parquet, Arrow, SQL\n- **Audit logging**: Tamper-proof trail (SHA-256 checksums)\n- **Encryption**: AES-256-GCM TDE, FIPS 140-3 mode\n- **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\n\n## Architecture\n\n| Layer | Technology |\n|-------|-----------|\n| Storage engine | RocksDB (LSM-tree) |\n| Columnar format | Apache Arrow |\n| SQL parser | sqlparser-rs |\n| Vector index | HNSW + Product Quantization |\n| Wire protocols | PostgreSQL v3, MySQL v10 |\n| HTTP server | Axum |\n| Encryption | AES-256-GCM, AWS-LC FIPS |\n\n## High Availability\n\n**Warm standby is enabled by default** — no feature flag needed. Just pass the replication flags at startup:\n\n```bash\n# Primary\nheliosdb-nano start --data-dir ./data --replication-role primary \\\n  --standby-hosts 10.0.0.2:5433,10.0.0.3:5433\n\n# Standby\nheliosdb-nano start --data-dir ./data --replication-role standby \\\n  --primary-host 10.0.0.1:5433\n```\n\nOptional HA features (opt-in at compile time):\n\n| Flag | Description |\n|------|-------------|\n| `ha-tier1` | Warm standby — **enabled by default** |\n| `ha-tier2` | Multi-primary: branch-based active-active |\n| `ha-tier3` | Sharding: consistent hash ring |\n| `ha-dedup` | Content-addressed deduplication across nodes |\n| `ha-ab-testing` | Branch-based experiment routing |\n| `ha-branch-replication` | Selective branch sync to remote servers |\n| `ha-full` | All optional HA features bundled |\n\n```bash\ncargo build --release --features ha-full    # everything\n```\n\n\u003e **Tip — verify HA changes locally, not in CI**: the HA streaming and\n\u003e lock-management integration tests rely on tight TCP-port spin-waits\n\u003e that pass cleanly on a developer workstation (sub-second) but routinely\n\u003e hang on the 2-CPU GitHub Actions runner. The release workflow gates on\n\u003e `cargo test --lib` only; if you're modifying anything under\n\u003e `src/storage/wal/`, `src/cluster/`, or `src/storage/locks/`, run the full\n\u003e integration suite locally first:\n\u003e\n\u003e ```bash\n\u003e cargo test --features ha-tier1 --test ha_integration   # warm-standby + streaming\n\u003e cargo test --tests --skip ha_tests::streaming_tests --skip lock_management\n\u003e ```\n\n### Connection Routing \u0026 Load Balancing\n\nFor production deployments with multiple HeliosDB Nano instances, put **[HeliosProxy](https://github.com/HeliosDatabase/HeliosDB-Proxy)** in front — a standalone binary providing:\n\n- Read/write splitting across primary + standbys\n- Automatic failover with transaction replay (Oracle TAF-style)\n- Connection pooling\n- Health checks + circuit breakers\n- TLS termination\n\n### Recommended Production Setup\n\n```\n           ┌────────────────┐\n    psql ─▶│                │──▶ HeliosDB Nano (primary, read+write)\n   mysql ─▶│  HeliosProxy   │──▶ HeliosDB Nano (standby, read-only)\n    curl ─▶│                │──▶ HeliosDB Nano (standby, read-only)\n           └────────────────┘\n              port 5432/3306/8080\n```\n\n1. Deploy 1 primary + 2 standbys (Fly.io / Render / Docker Swarm)\n2. HeliosProxy in front for routing + failover\n3. Automatic failover on primary death (\u003c 5 s typical)\n4. Readonly queries load-balanced across standbys\n\n## Deploy\n\n| Platform | Template |\n|----------|----------|\n| **Fly.io** | [deployment/flyio/](deployment/flyio/) |\n| **Railway** | [deployment/railway/](deployment/railway/) |\n| **Render** | [deployment/render/](deployment/render/) |\n| **Docker** | [deployment/docker/](deployment/docker/) |\n\n## Embedded Library (Rust)\n\nFor in-process use (no network, no daemon), add the crate as a dependency:\n\n```toml\n[dependencies]\nheliosdb-nano = \"3.39\"\n```\n\nSee **[the Rust API guide](https://docs.rs/heliosdb-nano)** for embedded usage and the [examples/](examples/) directory for working code.\n\n## Building from Source\n\nThe `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:\n\n```bash\n# Default build — embedded + Postgres/MySQL wire + warm-standby HA.\ncargo build --release\n\n# Code-graph + MCP server (matches what heliosdb-codekb-mcp links).\n# Adds tree-sitter parsers, _hdb_code_* tables, lsp_* APIs, and the\n# JSON-RPC dispatcher for stdio / HTTP / WebSocket / SSE clients.\ncargo build --release --features \"code-graph,graph-rag,mcp-endpoint\"\n\n# In-process embedder (no external HTTP service for embeddings).\n# Pulls fastembed-rs + ORT — adds ~30 MB to the binary.\ncargo build --release --features \"code-graph,code-embed\"\n\n# FIPS 140-3 compliant crypto (AWS-LC FIPS Cert #4816, SHA-256, PBKDF2).\n# `--no-default-features` is required to swap out ring-crypto.\ncargo build --release --no-default-features \\\n  --features \"fips,encryption,vector-search,ha-tier1\"\n\n# Full HA bundle — multi-primary + sharding + dedup + branch replication.\ncargo build --release --features \"ha-full\"\n```\n\n## SDKs \u0026 Integrations\n\nOfficial client SDKs (Go, Python, TypeScript, Rust) and platform integrations (VS Code, Zapier, n8n, Retool, Make, AutoGen) live in a shared repository:\n\n**[heliosdb-sdks](https://github.com/HeliosDatabase/HeliosDB-SDKs)** — works with all HeliosDB editions.\n\n```bash\n# JavaScript / TypeScript (Supabase-compatible fluent API)\nnpm install @heliosdb/client\n```\n\n```javascript\nimport { createClient } from '@heliosdb/client'\nconst db = createClient('http://localhost:8080', 'anon-key')\nconst { data } = await db.from('products').select('*').lt('price', 50)\n```\n\n## Agentic Operations (Claude Code, Codex CLI, MCP-aware tools)\n\n**The canonical way for an AI agent to operate Nano is MCP**: build with\n`--features mcp-endpoint`, then `claude mcp add heliosdb -- heliosdb-nano mcp\nserve --data-dir ./mydata` (stdio; HTTP and WebSocket transports also\navailable). The agent gets 16 structured tools — query, schema, insert, branch\ncreate/list/merge, time-travel, hybrid search — instead of building SQL\nstrings. See the `heliosdb-nano-mcp` skill for the full catalog and recipes.\n\nFor any LLM that ingests a single reference file, [`docs/llms.txt`](docs/llms.txt)\ncondenses install, connect, the SQL dialect, vector operators, branch\nsandboxes, time-travel, and the skill catalogue into one agent-readable page.\n\nFor agent deployments, set `profile = \"agent\"` in the config (see\n[config.example.toml](config.example.toml)): group-commit writes plus\ntime-travel kept ON, so branchable sandboxes, `AS OF` queries, and vector\nsearch all work out of the box.\n\nHeliosDB-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).\n\n```bash\n# After git clone, Claude Code automatically picks up .claude/skills/ in this project.\n\n# To install globally (~/.claude/skills/) so they apply in any project:\nbash scripts/install-agent-skills.sh                # copy (default, frozen snapshot)\nbash scripts/install-agent-skills.sh --symlink      # symlink (live updates)\n```\n\nExisting `~/.claude/skills/heliosdb-nano-*` directories are backed up to `*.bak.\u003cunix-ts\u003e` before being overwritten in either mode.\n\n**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:\n\n```bash\n# Skills bundled inside the crate you installed (newest cached version):\nSRC=$(ls -d ~/.cargo/registry/src/*/heliosdb-nano-*/.claude/skills 2\u003e/dev/null | sort -V | tail -1)\necho \"Deploying skills from: $SRC\"\n\n# Claude Code + OpenCode read ~/.claude/skills/ ; Codex + OpenCode read ~/.agents/skills/\nfor DEST in ~/.claude/skills ~/.agents/skills; do\n  mkdir -p \"$DEST\"\n  cp -r \"$SRC\"/heliosdb-nano-* \"$DEST\"/\n  cp -r \"$SRC\"/_index \"$DEST\"/heliosdb-nano-_index   # verb-map + feature-matrix (reference docs, not a skill)\ndone\n```\n\n| Agent | Global skill dir(s) it scans | Notes |\n|-------|------------------------------|-------|\n| **Claude Code** | `~/.claude/skills/` | Auto-discovered at next session start. |\n| **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. |\n| **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. |\n\nThe 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-\u003cversion\u003e/.claude/skills`. The `_index` folder has no `SKILL.md`, so OpenCode/Codex ignore it as a skill (it stays available as reference docs).\n\n| Skill | What it covers |\n|-------|---------------|\n| `heliosdb-nano-overview` | Top-level navigation; routes to the domain skills |\n| `heliosdb-nano-install` | crates.io, source, feature flags (code-graph, mcp-endpoint, fips, ha-full…) |\n| `heliosdb-nano-connect` | Embedded library, REPL, PG wire, MySQL wire, Python sqlite3 drop-in, TLS |\n| `heliosdb-nano-schema` | DDL: tables, indexes (B-tree + HNSW), views, triggers, PL/pgSQL |\n| `heliosdb-nano-query` | DML, parameter styles (`?` `$1` `:name` `@name`), `ON CONFLICT`, `RETURNING` |\n| `heliosdb-nano-transactions` | BEGIN/COMMIT/ROLLBACK, savepoints, bulk-load patterns |\n| `heliosdb-nano-branches` | Fork-test-discard sandboxes: `CREATE/USE/DROP DATABASE BRANCH`, `AS OF` forks |\n| `heliosdb-nano-time-travel` | `SELECT … AS OF TIMESTAMP '…'`, `\\snapshots` |\n| `heliosdb-nano-backup` | `dump`/`restore`, compression, append, partial restore, `--dump-schedule` |\n| `heliosdb-nano-vector` | HNSW indexes, `\u003c-\u003e \u003c#\u003e \u003c=\u003e` operators, hybrid search |\n| `heliosdb-nano-code-graph` | AST symbol index, LSP queries, git hook (`code-graph` feature) |\n| `heliosdb-nano-graph-rag` | Knowledge graph + RAG ingest pipeline (`graph-rag` feature) |\n| `heliosdb-nano-mcp` | MCP server, 16-tool catalog, stdio/HTTP/WS (`mcp-endpoint` feature) |\n| `heliosdb-nano-server` | Daemon, TLS, auth, HA tier 1/2/3, user management |\n| `heliosdb-nano-tenant` | Multi-tenant isolation modes, tiered plans, RLS policies |\n| `heliosdb-nano-deploy` | Docker, Fly.io, Railway, Render, systemd template |\n| `heliosdb-nano-observability` | Tracing, slow-query log, `/health`, `\\stats`, `\\optimize`, `\\indexes` |\n| `heliosdb-nano-migrate` | sqlite3 / Postgres / MySQL drop-in checklists |\n| `heliosdb-nano-merge-validation` | This repo's 8-phase pre-merge validation methodology (contributors) |\n\nLookups: [`.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).\n\n## Documentation\n\nIn-repo guides (`docs/`):\n\n- [Upgrade between Nano versions](docs/guides/upgrade.md)\n- [Database management — `CREATE` / `DROP DATABASE`](docs/guides/database_management.md)\n- [Authentication — SCRAM-SHA-256, trust, password, TLS](docs/guides/authentication.md)\n- [`information_schema` compatibility](docs/compatibility/information_schema.md)\n- [SQLite drop-in tutorial](docs/guides/sqlite_drop_in_tutorial.md)\n- [REPL demo](docs/guides/repl_demo.md)\n- [HA cluster tutorial](docs/guides/ha_cluster_tutorial.md) · [HA testing](docs/guides/ha_testing.md)\n- [Audit logging](docs/guides/audit.md)\n- [Tracing guide](docs/TRACING_GUIDE.md)\n- [Full-text search](docs/compatibility/fts.md) · [PL/pgSQL compatibility](docs/compatibility/plpgsql.md) · [SQLite compatibility](docs/compatibility/sqlite.md)\n- [Code-graph overview](docs/code_graph/overview.md)\n\nHosted docs:\n\n- [Getting Started](https://heliosdb.com/nano.html)\n- [API Explorer (Swagger UI)](http://localhost:8080/docs) — when running locally\n- [vs Supabase](https://heliosdb.com/vs-supabase.html)\n- [vs Firebase](https://heliosdb.com/vs-firebase.html)\n- [vs PostgreSQL](https://heliosdb.com/vs-postgresql.html)\n- [vs SQLite](https://heliosdb.com/vs-sqlite.html)\n- [Migrate from MySQL](https://heliosdb.com/migrate-mysql.html)\n\n## License\n\n[Apache-2.0](LICENSE) — Apache License, Version 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheliosdatabase%2Fheliosdb-nano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheliosdatabase%2Fheliosdb-nano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheliosdatabase%2Fheliosdb-nano/lists"}