HeliosDB Nano vs SQLite

Choose HeliosDB Nano when you want relational SQL and vector search in one in-process engine, with branching, time-travel reads and the option to serve the same data over the PostgreSQL and MySQL wire protocols; keep SQLite when its maturity, single-file format and tooling, FTS5 full-text search, locale-aware collation or independent embedded transactions matter more.

SQLite is the most deployed database in the world, and deservedly so: it is in-process, zero-configuration, exhaustively tested, and backed by a file format and tooling ecosystem that has been stable for two decades. For a very large number of applications it is the correct answer, and staying on it is a legitimate engineering decision rather than a failure to scale.

HeliosDB Nano is a different embedded engine with a different brief: relational SQL and native vector search in one in-process library, with the option to expose the same data directory over the PostgreSQL and MySQL wire protocols when more than one process needs to reach it. Start embedded; add server access as the application grows. This page compares the two honestly, including the places where Nano is currently the weaker choice.

Nano claims on this page are drawn from the Nano documentation and source; the known-limitations page tracks what is open in the current release. Where a capability is partial, scoped to one access path, or behind a non-default build feature, the table says so.

Evaluating HeliosDB Lite instead? Lite is a separate product tier with its own licence, feature set, and deployment model — it is not Nano with more features, and nothing on this page describes it. See HeliosDB Lite.

---

Capability comparison

Nano is split into two columns because several capabilities exist on only one of its access paths. Reading the two as a single merged column will overstate what either one does.

Every cell keyed to a fuller note below — read the note before treating a short cell as the whole story, especially for the three rows marked not safe / not reachable / none on Nano's side.

Notes, row by row

In-process and server access

Access mode is chosen when the database is opened or the server is started. Moving from embedded to server means stopping the embedded process and starting a server on the same data directory — not a live cutover, and not two processes sharing one directory.

Reader / writer concurrency

Nano's storage layer is MVCC (src/storage/mvcc.rs).

Independent explicit transactions

Explicit transactions on an embedded Nano handle share a single process-global slot, shared across clones of the handle. This is the single most important line in the table for anyone porting a multi-threaded SQLite application. On the server, each connection carries its own transaction state. See Concurrency and transactions below.

Vector search

SQLite extensions add vector search; index types, maturity, and API differ per extension and per version — check the specific one you intend to use before comparing capabilities. Nano ships VECTOR(n) columns and <-> / <=> / <#> distance operators. The default path is in-process HNSW, and Product Quantization is in the default build too: add WITH (quantization='product') to an HNSW index (indexes are unquantized unless you ask). Durable, restart-surviving PQ-HNSW indexes backed by RocksDB need building with --features vector-persist, which is not in the default feature set.

Full-text search

SQLite has the more complete text engine today. FTS5 is a persisted inverted index with prefix, phrase, and NEAR queries, pluggable tokenizers including Porter stemming, and a bm25() ranking function. Nano's PostgreSQL-shaped surface (tsvector, tsquery, @@, ts_rank / ts_rank_cd) lowercases on Unicode word boundaries and does not stem; phrase and proximity operators parse but degrade to a bag of terms; @@ is true if any query term is present; setweight() and rank weights are accepted and ignored; and CREATE INDEX ... USING gin is accepted as DDL but not consulted at runtime, so @@ walks matching rows. Nano documents this itself in its full-text search compatibility notes.

Branching and historical queries

Branch scope is the whole database. MERGE DATABASE BRANCH moves rows but performs no conflict detection — it is last-writer-wins, with no warning if both sides touched the same row. Fork, validate, discard, and re-apply the validated SQL to main is the safe pattern. Time-travel reads are bounded by retained versions (by default Nano keeps all history; set storage.version_retention, e.g. "7d", to bound it, after which background version GC or VACUUM VERSIONS reclaims older versions) and are not a substitute for backups.

Row-level security

Nano's RLS is real — tenant isolation and RLS policies via the embedded and REPL path. In the stock Nano server, row-level security is enforced through the embedded API and the REPL; SQL CREATE POLICY and enforcement for REST and wire clients are planned. If your reason for looking at Nano is enforced multi-tenancy behind a network listener, this does not do it yet.

Encryption at rest

Nano's AES-256-GCM transparent encryption is compiled in by default, but disabled at runtime by default and must be enabled in the configuration with a key (environment variable or file; cloud KMS key sources are planned). HeliosDB Nano ships zero-knowledge encryption: keys are derived and data encrypted on the client, the server never sees plaintext keys. FIPS 140-3 mode is available via the fips build feature. Encryption seals values, not keys — table names, column names, row ids, and timestamps remain readable on disk, as do HNSW graph snapshots and backup dumps. Enabling it seals new writes only; it does not retroactively seal data already written.

Replication

Writes made inside explicit embedded transactions reach the logical WAL. The first HA tier is compiled in by default but needs runtime configuration. Known limitation: a standby can transiently expose a partially applied transaction, because atomic-apply markers are not emitted yet.

SQL dialect, API, and file format

SQLite has its own dialect and one self-contained database file, with an enormous and mature ecosystem built around that format. Nano speaks PostgreSQL-flavoured SQL plus a SQLite-dialect compatibility layer for common patterns; its store is a data directory, not a single file, and is not SQLite-format compatible. Nano never opens a .sqlite file in place — existing files come across as a one-shot conversion through the converter bundled in the Nano repository. Nano is statically typed where SQLite is dynamically typed, so inserts SQLite accepts can be rejected.

Maturity and operational track record

SQLite has decades of production use at enormous scale, with a test suite far beyond what most databases carry — a real, current reason to choose it. Nano is young and moving quickly, with a visible correctness campaign in the changelog, including a fix for a data-loss-on-upgrade bug in two earlier releases. Read the changelog before any upgrade, and rehearse upgrades on a copy. Nano is not production-mature in the sense SQLite is, and we are not going to claim otherwise.

The table scrolls sideways on narrow screens, so the four limits that most often decide this comparison are repeated here:

• Embedded explicit transactions are not independent. Two in-process callers cannot hold overlapping BEGIN…COMMIT blocks safely. Server mode is the supported answer.
• Row-level security is embedded-only in the stock server. It is enforced through the embedded API and the REPL; SQL CREATE POLICY and enforcement over the PostgreSQL wire, the MySQL wire and REST are planned.
• MERGE DATABASE BRANCH does not detect conflicts. It is last-writer-wins and silent. Discard branches and re-apply validated SQL instead.
• SQLite's full-text search is more capable than Nano's. No stemming, no phrase queries, and no runtime inverted index on the Nano side today; stemming and phrase search are planned.

Two cells in the table are deliberately non-specific. The SQLite + extensions entry for vector search does not name an extension or an index type, because index support in that ecosystem moves and differs by project and version — verify against the extension and release you actually plan to ship. The comparison is otherwise drawn from Nano's own source and compatibility documentation.

---

Concurrency and transactions

This is where a port from SQLite most often goes wrong, so it is worth stating plainly.

What works on the embedded API: concurrent reads, and writes issued as single autocommit statements. MVCC means readers are not blocked by a writer.

What does not work on the embedded API: two callers holding overlapping explicit BEGIN…COMMIT transactions. Explicit transaction state lives in one process-global slot per handle and is shared across every clone of that handle, so independent, overlapping transactions from separate threads are not safe. There are lower-level session primitives in the crate, but they are internal plumbing rather than a supported public API, and they are not a workaround we recommend. A public embedded session API is roadmap, not shipped.

Supported options today, in order of preference:

1. Run the daemon and give each caller its own PostgreSQL connection, over TCP or a Unix socket. Per-connection transaction state is real here, and this is the only path that gives genuinely independent sessions.
2. If the application must share one embedded handle, it has to coordinate around the entire transaction lifetime — including the error and rollback paths, not just the BEGIN and the COMMIT.
3. Use single-statement autocommit writes where the workload allows it.

One further distinction worth keeping straight: the local crash-recovery WAL is always on and is separate from the logical WAL used for replication. Embedded writes inside explicit transactions reach the logical WAL.

---

When HeliosDB is not the right fit

In these cases SQLite is the better choice. Outgrowing SQLite is not inevitable, and these are not edge cases: an SQLite deployment that meets its requirements is not a problem waiting to be solved, and the migration cost and the reliability you would trade away are both real.

• You depend on the SQLite file format, extensions or tooling. The format's ecosystem — inspection tools, backup tooling, language bindings, extensions — is a genuine asset, and none of it carries over. Nano cannot open a .sqlite file; moving means export, reload and verify. SQLite compatibility · Migrating from SQLite
• You need a full-featured text search engine now. FTS5's persisted index, stemming, and phrase and proximity queries are ahead of Nano's current full-text surface. If search quality is a product requirement rather than a convenience, this alone can settle it. Full-text search compatibility
• Multiple in-process callers need independent explicit transactions. Nano's embedded API cannot do this today, and the fix is to restructure the application around the server — a larger change than swapping a library. Concurrency and transactions
• Locale-aware collation matters. Nano compares text by byte order only; there is no locale-aware collation support. If your sorting or comparison semantics depend on a collation, SQLite with ICU is the shorter path. Nano FAQ
• You value a long reliability record over new capability. SQLite has decades of production evidence behind it. Nano has months, and its open issues are tracked in public. Known limitations
• You are extremely constrained, or ship to older systems. SQLite's footprint is far smaller than a self-contained Nano binary, and prebuilt Nano Linux binaries need glibc 2.39 or newer. Distribution notes

---

When to evaluate Nano

• You want relational data and vector search in one in-process engine. HNSW is built in on the default build, so there is no separate vector service to run, sync, or keep consistent with the rows it describes.
• You expect to need network access later. The same data directory can be served over the PostgreSQL and MySQL wire protocols, so growing past a single process does not mean changing engines — though it does mean stopping the embedded process and writing real client code.
• Multiple clients need independent transactions. Server mode gives you that today; the embedded API does not.
• You want disposable database sandboxes. Branching is a SQL statement, forks are cheap, and fork-validate-discard is a good fit for migration rehearsals and agent runs — provided you discard rather than merge, given the merge caveat above.
• You want historical reads as part of the query language. AS OF TIMESTAMP answers "what did this look like before that job ran" without restoring anything, within the retention window.
• Existing PostgreSQL or MySQL clients are an advantage. Your drivers, ORMs, and psql muscle memory carry over at the connection layer. Wire-protocol compatibility is about connectivity, not full semantic parity — byte-order-only collation and embedded-only RLS are two concrete current gaps.

---

Getting started

Install

# Rust / CLI
cargo install heliosdb-nano

# Python, in-process binding
pip install heliosdb-nano-embedded

# Container image (default-feature build)
docker pull ghcr.io/heliosdatabase/heliosdb-nano:latest

Embedded

# Scratch database in memory
heliosdb-nano repl --memory

# Or initialise a persistent data directory
heliosdb-nano init ./heliosdb-data
heliosdb-nano repl --data-dir ./heliosdb-data

From Python, the binding calls the embedded engine directly — no subprocess, no wire protocol:

import heliosdb_nano

db = heliosdb_nano.EmbeddedDatabase("./heliosdb-data")   # or .in_memory()

db.execute("CREATE TABLE notes (id INT, title TEXT, body TEXT)")
db.execute_many(
    "INSERT INTO notes (id, title, body) VALUES ($1, $2, $3)",
    [(1, "First", "hello"), (2, "Second", "world")],
)
db.query("SELECT * FROM notes WHERE title = $1", ("First",))

db.create_vector_store("emb", 3)
db.insert_vectors("emb", [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
db.vector_search("emb", [1.0, 0.0, 0.0], k=1)

Server

# Stop the embedded process first — one directory, one process
heliosdb-nano start \
    --data-dir ./heliosdb-data \
    --port 5432 \
    --auth scram-sha-256 --password "$HELIOSDB_PASSWORD"

# Connect with any PostgreSQL client
psql -h 127.0.0.1 -p 5432 -U postgres

# Or enable the MySQL listener alongside it
heliosdb-nano start --data-dir ./heliosdb-data --mysql

Keep the Nano version identical across the embedded-to-server switch. Changing access mode and engine version at the same time makes any resulting problem much harder to attribute.

Vector and full-text queries

CREATE TABLE docs (
    id SERIAL PRIMARY KEY,
    title TEXT,
    body TEXT,
    embedding VECTOR(1536)
);

CREATE INDEX ON docs USING hnsw (embedding vector_cosine_ops);

-- k-NN
SELECT title, embedding <-> '[0.15, 0.25, ...]' AS distance
FROM docs ORDER BY distance LIMIT 10;

-- Full-text, PostgreSQL-shaped (unstemmed; see the table above)
SELECT title, ts_rank_cd(to_tsvector(body), to_tsquery('heliosdb')) AS rank
FROM docs
WHERE to_tsvector(body) @@ to_tsquery('heliosdb')
ORDER BY rank DESC LIMIT 10;

Bringing a SQLite database across

There is no in-place path: Nano does not read the SQLite file format. Conversion is a one-shot export through the converter bundled in the Nano repository, followed by re-testing your queries against Nano. Budget real time for the type-affinity difference — Nano is statically typed, so values SQLite silently accepted into a column can be rejected — and do not assume SQLite-specific statements translate one-for-one. INSERT OR REPLACE and ON CONFLICT DO UPDATE in particular are not equivalent: the former deletes and reinserts the row, which resets unspecified columns to their defaults, while the latter updates in place.

See the migration guides for the current step-by-step.

---

Performance

We do not publish a head-to-head SQLite benchmark, and this page deliberately carries no throughput figures. Relative performance between an embedded MVCC engine and SQLite depends heavily on write pattern, transaction size, durability settings, and whether the workload touches vector or text search at all — a single number would mislead more than it informed. Measure both on your own workload. Published HeliosDB figures, with their fixtures, are on the benchmarks page.

---

Further reading

• HeliosDB Nano — the full product page, including its own SQLite comparison and the embedded-versus-server decision.
• HeliosDB Lite — the separate tier, if that is what you were actually comparing.
• All comparisons — PostgreSQL, MySQL, vector databases, and more.
• Nano documentation and the source and changelog on GitHub.