---
title: "Frequently Asked Questions"
description: "Answers about HeliosDB Lite: licensing and installation, PostgreSQL compatibility, branching, time travel, vector search, performance and security."
---

# 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 operationally hardened?

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

HeliosDB-Lite is available to licensed customers; contact
[sales@heliosdb.com](mailto:sales@heliosdb.com) for access. It is not
published on crates.io, PyPI or npm. With the source distribution unpacked,
build the `heliosdb-lite` binary (REPL and server):

```bash
cd heliosdb-lite && cargo build --release
```

**Python / TypeScript / Go / other languages:** connect to a running Lite
server with any PostgreSQL driver, or use the Apache-2.0 client SDKs from
[HeliosDatabase/HeliosDB-SDKs](https://github.com/HeliosDatabase/HeliosDB-SDKs).
See [Installation](https://www.heliosdb.com/docs/lite/getting-started/installation/).

## 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](https://www.heliosdb.com/docs/lite/user-guide/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:

- PL/SQL, T-SQL and DB2 SQL PL routines (planned; SQL and PL/pgSQL functions run today)
- 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:

```sql
-- 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:

```sql
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?

Any model: generate embeddings in your application (OpenAI, Sentence Transformers or your
own model) and store them in `VECTOR(n)` columns. Built-in embedding generation through the
REST API is planned.

### 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](https://www.heliosdb.com/docs/lite/user-guide/configuration/) for tuning parameters.

## Security

### Is data encrypted at rest?

Yes, AES-256-GCM encryption at rest is enabled in the configuration file, with the key read
from the environment:

```toml
[encryption]
enabled = true
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }
```

### Does it support authentication?

In server mode, HeliosDB-Lite supports:

- PostgreSQL wire: `--auth password`, `md5` or `scram-sha-256` with `--password` (the default
  `trust` is for local development only)
- REST API: JWT bearer tokens signed with `HELIOSDB_JWT_SECRET`

### What about row-level security?

RLS policies can restrict access at the row level:

```sql
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**: this documentation site
- **Support**: [Report bugs](mailto:support@heliosdb.com)
- **Discussions**: [Ask on Discord](https://discord.gg/yTykuUrFXc)
- **Security Issues**: See [Security Policy](https://www.heliosdb.com/docs/lite/resources/security/)