---
title: "Deployment Modes"
---

# Deployment Modes

Deploying HeliosDB Nano means making two independent choices. The full
reference — flags, configuration, authentication, feature differences — lives in
[Deployment Modes](https://www.heliosdb.com/docs/nano/guides/deployment_modes/); this page is the short
version.

## 1. Storage mode — where the data lives

| Storage mode | How | Data after exit |
|---|---|---|
| **Persistent** | `--data-dir ./my-data`, or `EmbeddedDatabase::new("./my-data")` | Survives restart |
| **In-memory** | `--memory`, or `EmbeddedDatabase::new_in_memory()` | Discarded, unless `--dump-on-shutdown` writes a dump on graceful exit |

## 2. Access mode — how callers reach the engine

| Access mode | How | Use it for |
|---|---|---|
| **Embedded library API** | `EmbeddedDatabase::new(...)` in your process | Desktop, mobile, edge, CLI tools, single-process services |
| **Interactive REPL** | `heliosdb-nano repl --data-dir ./my-data` | Schema work, ad-hoc queries, inspection |
| **Foreground server** | `heliosdb-nano start --data-dir ./my-data --port 5432` | Development against real clients, protocol debugging |
| **Background daemon** | `heliosdb-nano start --daemon --data-dir ./my-data --pid-file ./heliosdb.pid` | Long-running deployments, containers, service managers |

Any access mode can be combined with either storage mode. "Embedded" is an
access mode; "in-memory" is a storage mode.

## Two quick starts

**Embedded, persistent:**

```rust
use heliosdb_nano::EmbeddedDatabase;

let db = EmbeddedDatabase::new("./my-data")?;
db.execute("CREATE TABLE users (id BIGSERIAL PRIMARY KEY, name TEXT)")?;
```

**Server, persistent, then connect with a PostgreSQL client:**

```bash
heliosdb-nano start --data-dir ./my-data --port 5432 --listen 127.0.0.1
psql -h 127.0.0.1 -p 5432
```

## Three rules worth knowing up front

1. **One process per data directory.** A second process opening a directory
   another process already owns fails with lock errors. If several callers need
   the same data, run the server and connect to it.
2. **Modes are chosen at start time.** Switching from embedded to server is a
   stop-then-start handoff onto the same data directory plus real client code in
   the application — not a live cutover.
3. **Independent transactions need separate connections.** Embedded access has a
   single process-global transaction slot; per-connection transactions exist
   over the wire protocols. See
   [Concurrency and transactions](https://www.heliosdb.com/docs/nano/guides/concurrency-and-transactions/).

## Next steps

- [Deployment Modes — full reference](https://www.heliosdb.com/docs/nano/guides/deployment_modes/)
- [Concurrency and transactions](https://www.heliosdb.com/docs/nano/guides/concurrency-and-transactions/)
- [Configuration Reference](https://www.heliosdb.com/docs/nano/user-guide/configuration/)
- [Security Best Practices](https://www.heliosdb.com/docs/nano/resources/security/)