Home / Blog / HeliosDB Nano v3.19 — From Embedded SQL to AI-Native Retrieval Engine
Release 9 min read

HeliosDB Nano v3.19 — From Embedded SQL to AI-Native Retrieval Engine

HeliosDB Nano went from v3.11 to v3.19.1 in five weeks. The version number is a footnote; the shape of the product changed. Nano was an embedded SQL+vector database with PostgreSQL/MySQL wire compatibility and 32 MB on disk. It is now an AI-native retrieval engine: SQL + Vector + Graph + Code-Graph + Graph-RAG + native MCP server + an in-process embedder, in a 32 MB all-features release binary, with zero external services required.

This post is the headline. The four follow-ups go deep on the individual tracks — Code-Graph, Graph-RAG, native MCP server, plus the HeliosProxy v0.4 release for the platform side.

Three Tracks That Reframe Nano

Track 1 — Code-Graph (v3.15 → v3.18)

CREATE EXTENSION hdb_code; CREATE AST INDEX ON src/ turns your codebase into a queryable AST. The full LSP surface is exposed as SQL table functions: lsp_definition, lsp_references, lsp_call_hierarchy, lsp_hover, plus diff helpers (helios_lsp_references_diff, helios_lsp_body_diff, helios_ast_diff) and the v3.19 write-side helios_lsp_rename_preview / helios_lsp_rename_apply with sha256 conflict checking.

Eight languages out of the box (Rust, Python, TypeScript, TSX, JavaScript, Go, Markdown, SQL), plus a runtime grammar registry that lets you plug in any tree-sitter grammar at runtime via register_grammar + register_extractor. Every lsp_* call accepts ON BRANCH '<name>' per-call override and AS OF in either order — code intelligence is time-travel-aware on the same query.

Track 2 — Graph-RAG (v3.17 → v3.19)

RAG pipelines glue a vector store, a graph DB, an entity linker, and a re-ranker. Nano collapses them. WITH CONTEXT is a SQL clause; _hdb_graph.nodes and _hdb_graph.edges are queryable tables; entity linking and auto-projection happen on insert. v3.19 added six ingestion adapters — graph_rag_ingest_docs / _email / _issues / _qa plus Docling-backed _pdf / _office / _audio / _image. Centrality-biased re-ranking, semantic-Merkle invalidation via CREATE SEMANTIC HASH INDEX, and a vector-similar entity linker (graph_rag_link_vector) round it out.

Track 3 — Native MCP Server (v3.18 → v3.19)

Every modern coding agent — Claude Code, Cursor, Continue, Codex, Aider — speaks Model Context Protocol. Nano speaks it natively on three transports: POST /mcp (HTTP JSON-RPC), /mcp/ws (WebSocket), /mcp/sse (SSE). Plus stdio for sandboxed agents. JWT auth, Unix-socket transport, public-bind hardening (opt-in only). v3.19 added streaming notifications/progress events, single-shot helios/info discovery, tools/list?verbose=true, and HTTP POST + SSE session pairing.

The v3.19 Backlog Sweep

v3.19.0 (April 25) closed the residual FR backlog the v3.18 review left open. The most important deltas for users:

  • code-embed feature — fastembed-rs in-process with BGESmallENV15 (384-dim, ~30 MB model cache, no on-disk impact on the binary). Compile with --features code-embed and Nano embeds locally. HttpEmbedder remains available for managed embedding services.
  • Docling content-conversion ingestion — PDFs, Office docs, audio (transcribed), and images (OCR'd) project into _hdb_graph.nodes with CONTAINS edges. Idempotent via source-ref keys.
  • helios_lsp_rename_apply — write-back rename refactor, identifier-boundary aware, sha256 conflict check, optional dry_run.
  • Streaming MCP progress — helios_graphrag_search emits "seeding" and "n hits" events when the client opts in via _meta.progressToken.
  • Scope-chain resolver via IMPORTS — unresolved CALLS / REFERENCES upgrade to Exact when an unambiguous IMPORTS edge in the same file ends in the bare name.
  • hdb_code_languages system view — queryable list of supported + runtime-registered grammars.
  • Centrality-biased + prefilter-aware HNSW wrapper — over-fetches k × over_fetch_multiplier candidates, applies row-level prefilter, re-scores with (1−α)·distance − α·centrality.

Defensible Numbers

v3.19 also landed acceptance benchmarks — first measured numbers we are willing to put on the website:

Workload Target Measured
WITH CONTEXT mean (10k-node fixture, 100 queries)≤ 500 ms62 ms
Entity linker precision (hand-labelled fixture)≥ 80 %100 %
All-features release binary size—35.0 MiB

Source: tests/with_context_bench.rs, tests/linker_precision.rs, docs/followups/build-report.md. Single-machine, release build, criterion methodology.

v3.19.1 — the One-Day-After Fix

v3.19.1 (April 25, hours after v3.19.0) ships a single targeted fix: UUID literal coercion at PK index lookup. SELECT … WHERE id = '<uuid>' against a UUID-typed PK previously emitted Value::String regardless of the column's declared type, and the ART point-lookup encoded the search key by Value variant — so the lookup missed every row. Three patches land the fix at try_index_point_lookup, the fast_parse_one_value fast path, and the SIMD post-walk filter. CloudV2's admin DB — the bug's reporter — can now graduate cloud-v2.heliosdb.com to production.

Drizzle / Prisma / TypeORM Compatibility (v3.14.x)

Earlier in this release window we closed B1–B36, the full set of bugs Drizzle / Prisma / TypeORM exposed in our extended-protocol implementation. Highlights: DEFAULT in VALUES, extended-Q RETURNING, parameterised LIMIT / OFFSET, UPDATE SET coercion, mixed-qualifier GROUP BY, DATE key comparison, FK validation with quoted identifiers, and the fast-path-bypass-was-a-data-integrity-hole fix in v3.14.10. Every modern Node ORM works against Nano now without workarounds.

Compatibility

All of the above is additive. Code-graph, graph-RAG, MCP-endpoint, and code-embed are Cargo-feature-gated; embedded-only callers compile without them. The default release binary stays small. The PostgreSQL / MySQL wire surface is unchanged. SQL behaviour is unchanged except where v3.14.x bug fixes corrected divergence from PostgreSQL semantics.

Where This Goes Next

Read the deep-dives:

HeliosDB Nano is open source under Apache 2.0. The repo is github.com/dimensigon/HDB-HeliosDB-Nano; full CHANGELOG lives there.

← Back to Blog