Frequently Asked Questions

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?

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

Is it production-ready?

HeliosDB Nano is actively developed with a focus on stability and performance. Check the Feature Index for implementation status 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:

pip install heliosdb-nano

TypeScript/Node.js:

npm install heliosdb-nano

SQL Compatibility

Is it fully PostgreSQL-compatible?

HeliosDB Nano supports approximately 95% of PostgreSQL SQL syntax. 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:

• Stored procedures (PL/pgSQL)
• Triggers on views
• Foreign keys (parsed but not enforced)
• Some advanced PostgreSQL-specific functions

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?

When merging branches with conflicting changes to the same row:

-- View conflicts
SELECT * FROM helios_branch_conflicts('dev', 'main');

-- Resolve by choosing a version
CALL helios_resolve_conflict('table_name', 'row_id', 'keep_source');

Time-Travel

How far back can I query?

The retention period is configurable via the snapshot_retention setting:

SET helios.snapshot_retention = '7 days';

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?

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?

Yes, AES-256 encryption is available:

SET helios.encryption_key = 'your-secure-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:

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

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