Skip to content

Frequently Asked Questions

General

What is HeliosDB-Lite?

HeliosDB-Lite 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-Lite 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-Lite 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-lite

Python: 

pip install heliosdb-lite

TypeScript/Node.js: 

npm install heliosdb-lite

SQL Compatibility

Is it fully PostgreSQL-compatible?

HeliosDB-Lite 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-Lite 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.

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

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-Lite 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