Skip to content
HeliosDB HeliosDB Nano

Frequently Asked Questions

General

What is HeliosDB Nano?

HeliosDB Nano is a high-performance embedded database built in Rust. It combines PostgreSQL-compatible SQL with advanced features like:

  • Git-like database branching
  • Time-travel queries
  • Vector search for AI/ML applications
  • Transparent compression
  • Row-level security

How does it compare to SQLite?

FeatureHeliosDB NanoSQLite
LanguageRustC
SQL CompatibilityPostgreSQLSQLite-specific
BranchingBuilt-inNot available
Time-travelBuilt-inNot available
Vector searchBuilt-inExtension required
CompressionMultiple codecsLimited
ConcurrencyMVCCFile-level locking

Read the concurrency row carefully: MVCC gives concurrent reads and single-statement autocommit writes in every mode, but independent overlapping explicit transactions require separate wire connections — they are not available on the embedded API. See Concurrency and transactions.

Is it operationally hardened?

HeliosDB Nano is actively developed with a focus on stability and performance. Check the Feature Index for Implementation details of specific features.

Installation

What are the system requirements?

ComponentMinimumRecommended
Memory50 MB512 MB+
Disk10 MB100 MB+
CPU1 core2+ cores

Which platforms are supported?

  • Linux (x86_64, aarch64)
  • macOS (x86_64, Apple Silicon)
  • Windows (x86_64)

How do I install it?

Rust/Cargo:

Terminal window
cargo add heliosdb-nano

Python (embedded, in-process):

Terminal window
pip install heliosdb-nano-embedded   # then: import heliosdb_nano

The package name and the import name differ. pip install heliosdb-nano (without -embedded) does not exist.

TypeScript/Node.js: there is no published npm package. Run Nano as a server and connect with a PostgreSQL client such as pg:

Terminal window
npm install pg

SQL Compatibility

Is it fully PostgreSQL-compatible?

No. It implements the PostgreSQL wire protocol and a large subset of PostgreSQL SQL, which is what lets existing clients, drivers and ORMs connect — but wire compatibility is not semantic parity. Two concrete current gaps: collation is byte-order (C) only, and row-level security is not enforced over the wire protocols. Key supported features include:

  • DDL: CREATE TABLE, CREATE INDEX, ALTER TABLE
  • DML: SELECT, INSERT, UPDATE, DELETE
  • Joins: INNER, LEFT, RIGHT, FULL, CROSS
  • Aggregates: COUNT, SUM, AVG, MIN, MAX, and more
  • Window functions
  • CTEs (WITH clauses)
  • Subqueries

See SQL Reference for complete details.

Can I use my existing PostgreSQL tools?

Yes. HeliosDB Nano implements the PostgreSQL wire protocol, so you can use:

  • psql command-line client
  • pgAdmin
  • DBeaver
  • Most PostgreSQL drivers

What SQL features are NOT supported?

Currently not implemented:

  • Triggers on views
  • Locale-aware collation — collation is byte-order (C) only
  • Some advanced PostgreSQL-specific functions

See Known Limitations for the current list of open issues with workarounds (for example NULLS LAST being ignored, and ORDER BY aliases after GROUP BY).

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 (PostgreSQL, MySQL) are planned.

Branching

What is database branching?

Database branching creates isolated copies of your database that can be modified independently, then merged back - similar to Git branches for code.

Does branching duplicate all data?

No. Branching uses copy-on-write semantics, meaning only changed data is stored separately. Creating a branch is nearly instant regardless of database size.

How do I resolve merge conflicts?

You cannot, because they are never detected. MERGE DATABASE BRANCH is last-writer-wins with no conflict detection — rows changed on both branches are overwritten and nothing is reported. The conflict_resolution= option is parsed but not implemented, and the statement now returns an error rather than silently ignoring it.

For anything conflict-sensitive, branch, validate, discard, and re-apply the validated SQL to main. See Database Branching.

Time-Travel

How far back can I query?

As far back as versions have been retained. Retention is configured by storage.version_retention in the configuration file; older versions are reclaimed by background version GC, or explicitly by VACUUM VERSIONS.

Time travel is bounded by retention and is not a substitute for backups.

Does time-travel impact performance?

Minimal impact. Historical versions are stored alongside current data using MVCC. Queries against historical snapshots have similar performance to current queries.

How much storage does it use?

Storage depends on your change rate. With default compression, expect roughly 1.2x-2x the size of a single snapshot for moderate write workloads.

What embedding models are supported?

Built-in embedding generation is planned (roadmap). The planned providers are:

  • OpenAI (text-embedding-3-small, text-embedding-ada-002)
  • Sentence Transformers (all-MiniLM-L6-v2)
  • Custom models via API

Today, compute embeddings in your application (any model and dimension) and store them in VECTOR(n) columns.

What index types are available?

Index TypeBest ForTrade-offs
HNSWGeneral useFast, memory-efficient
IVF-PQLarge datasetsCompact, slightly less accurate
FlatSmall datasetsExact results, slower

HNSW typically achieves 95%+ recall with default parameters. Tune ef_search for higher accuracy at the cost of speed.

Performance

What’s the write throughput?

Typical benchmarks on modern hardware:

OperationThroughput
Single inserts10,000-50,000/sec
Batch inserts100,000-500,000/sec
Updates5,000-20,000/sec

What’s the query latency?

Query TypeLatency
Point lookup (indexed)<1ms
Range scan (1000 rows)1-5ms
Vector search (top-10)1-10ms
Complex joinVaries

How do I optimize performance?

  1. Create appropriate indexes for query patterns
  2. Use SMFI (Storage-Level Metadata Filtering) for time-series data
  3. Configure compression based on data type
  4. Tune cache sizes for your workload

See Configuration for tuning parameters.

Security

Is data encrypted at rest?

Only if you turn it on. AES-256-GCM transparent encryption is compiled into the default build but disabled at runtime by default, and it requires a configured key source (environment variable or key file; cloud KMS key sources are planned):

[encryption]
enabled = true
algorithm = "Aes256Gcm"
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }

HeliosDB Nano provides zero-knowledge encryption: keys are derived and data encrypted on the client, the server never sees plaintext keys.

Does it support authentication?

In server mode, HeliosDB Nano supports:

  • SCRAM-SHA-256, password and md5 authentication on the PostgreSQL listener
  • JWT sign-up and login through the /auth/v1 endpoints

Keep the HTTP and MySQL listeners on loopback (the default): API-key authentication for the HTTP API is planned, and a smaller listening surface is good practice anyway.

What about row-level security?

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. See the RLS Quick Start for the embedded API.

Troubleshooting

Database won’t start

Check:

  1. Data directory permissions
  2. Sufficient disk space
  3. Port availability (for server mode)
  4. Lock files from previous crash

Queries are slow

  1. Run EXPLAIN ANALYZE to see query plan
  2. Check if indexes exist for filter columns
  3. Review SMFI configuration
  4. Monitor memory usage

Data corruption

  1. Check disk health
  2. Review crash recovery logs
  3. Contact support with error details

Getting Help