---
title: "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 |

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](https://www.heliosdb.com/docs/nano/guides/concurrency-and-transactions/).

### Is it operationally hardened?

HeliosDB Nano is actively developed with a focus on stability and performance. Check the [Feature Index](https://www.heliosdb.com/docs/nano/developer/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:**
```bash
cargo add heliosdb-nano
```

**Python (embedded, in-process):**
```bash
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`:

```bash
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](https://www.heliosdb.com/docs/nano/user-guide/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](https://www.heliosdb.com/docs/nano/reference/compatibility/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](https://www.heliosdb.com/docs/nano/features/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 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 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/nano/user-guide/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):

```toml
[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](/docs/nano/guides/rls_quickstart/) 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

- **Documentation**: this site, www.heliosdb.com/docs/nano/
- **Known limitations**: [Open issues in the current release](https://www.heliosdb.com/docs/nano/reference/compatibility/known-limitations/)
- **Email**: [support@heliosdb.com](mailto:support@heliosdb.com)
- **GitHub Issues**: [Report bugs](https://github.com/HeliosDatabase/HeliosDB-Nano/issues)
- **Discord**: [Ask questions](https://discord.gg/yTykuUrFXc)
- **Security Issues**: See [Security Policy](https://www.heliosdb.com/docs/nano/resources/security/)