Frequently Asked Questions

Applies to: HeliosDB Nano 4.31.1

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?

Feature	HeliosDB Nano	SQLite
Language	Rust	C
SQL Compatibility	PostgreSQL	SQLite-specific
Branching	Built-in	Not available
Time-travel	Built-in	Not available
Vector search	Built-in	Extension required
Compression	Multiple codecs	Limited
Concurrency	MVCC	File-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?

Component	Minimum	Recommended
Memory	50 MB	512 MB+
Disk	10 MB	100 MB+
CPU	1 core	2+ cores

Which platforms are supported?

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

How do I install it?

Rust/Cargo:

cargo add heliosdb-nano

Python (embedded, in-process):

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:

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

Row-level security is implemented, but reachable only through the embedded API and the REPL — it is not enforced over the PostgreSQL wire protocol, the MySQL wire protocol, or REST in any release to date.

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.

Vector Search

What embedding models are supported?

Built-in embedding generation supports:

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

What index types are available?

Index Type	Best For	Trade-offs
HNSW	General use	Fast, memory-efficient
IVF-PQ	Large datasets	Compact, slightly less accurate
Flat	Small datasets	Exact results, slower

How accurate is approximate search?

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:

Operation	Throughput
Single inserts	10,000-50,000/sec
Batch inserts	100,000-500,000/sec
Updates	5,000-20,000/sec

What’s the query latency?

Query Type	Latency
Point lookup (indexed)	<1ms
Range scan (1000 rows)	1-5ms
Vector search (top-10)	1-10ms
Complex join	Varies

How do I optimize performance?

Create appropriate indexes for query patterns
Use SMFI (Storage-Level Metadata Filtering) for time-series data
Configure compression based on data type
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, file, or cloud KMS):

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

Does it support authentication?

In server mode, HeliosDB Nano supports:

API key authentication
SCRAM-SHA-256 (PostgreSQL-compatible)

What about row-level security?

RLS policies can restrict access at the row level:

CREATE POLICY user_data ON users
  USING (user_id = current_setting('app.user_id')::INT);

Troubleshooting

Database won’t start

Check:

Data directory permissions
Sufficient disk space
Port availability (for server mode)
Lock files from previous crash

Queries are slow

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

Data corruption

Check disk health
Review crash recovery logs
Contact support with error details

Getting Help

Documentation: You’re reading it!
GitHub Issues: Report bugs
Discussions: Ask questions
Security Issues: See Security Policy