Skip to content
HeliosDB HeliosDB Nano

Deployment Modes

Deployment Modes

Applies to: HeliosDB Nano 4.31.1

This is the canonical page for how a HeliosDB Nano process is deployed. Two decisions are independent of each other, and mixing them up is the single most common source of confusion:

  1. Storage mode — where the data lives: persistent (a data directory on disk) or in-memory (RAM only).
  2. Access mode — how callers reach the engine: embedded library API, interactive REPL, foreground server, or background daemon.

Every combination of the two is valid. “Embedded” is an access mode, not a storage mode; “in-memory” is a storage mode, not an access mode.

Storage modes

Persistent

Data is written to a data directory and survives process restart. The local crash-recovery write-ahead log is always on.

Terminal window
heliosdb-nano repl --data-dir ./my-data
heliosdb-nano start --data-dir ./my-data --port 5432
use heliosdb_nano::EmbeddedDatabase;


let db = EmbeddedDatabase::new("./my-data")?;

heliosdb-nano start requires either --data-dir or --memory; repl defaults to ./heliosdb-data.

In-memory

Data lives in RAM and is discarded when the process exits.

Terminal window
heliosdb-nano repl --memory
heliosdb-nano start --memory --port 5432
let db = EmbeddedDatabase::new_in_memory()?;

Add --dump-on-shutdown (CLI only) to write a dump on a graceful exit — heliosdb-nano repl --memory --dump-on-shutdown --dump-file ./snapshot.heliodump. An abrupt kill still loses everything: in-memory storage is not a durability mechanism.

Use in-memory for tests, CI, and short-lived transforms. Use persistent storage for anything whose loss would matter.

Access modes

1. Embedded library API (in-process)

The engine runs inside your process, with no network listener and no separate server to manage — the SQLite-style deployment.

use heliosdb_nano::EmbeddedDatabase;


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

A Python binding for this same in-process engine is published as heliosdb-nano-embedded (pip install heliosdb-nano-embedded, then import heliosdb_nano), version-locked to the engine release.

  • Best for: desktop and mobile apps, edge devices, CLI tools, single-process services, test harnesses.
  • No network listener, no authentication layer, no per-connection sessions.
  • Concurrent reads and single-statement autocommit writes are supported; independent overlapping explicit transactions are not — see Concurrency and transactions before you share one handle between threads.

2. Interactive REPL

A single-user interactive SQL shell over the same in-process engine.

Terminal window
heliosdb-nano repl --data-dir ./my-data
heliosdb-nano repl --memory
  • Best for: schema work, ad-hoc queries, inspecting a data directory, learning.
  • REPL meta commands (\d, \dt, \branches, \use, \stats) are available here and not over the wire protocols.
  • Single process, single user, no network access.

3. Foreground server

A PostgreSQL-wire server that stays attached to the terminal and logs to stdout.

Terminal window
heliosdb-nano start --data-dir ./my-data --port 5432 --listen 127.0.0.1

Connect with any PostgreSQL client:

Terminal window
psql -h 127.0.0.1 -p 5432
  • Best for: development, protocol debugging, watching server output live.
  • Multiple clients; each connection gets its own session and its own transaction state, which is the supported way to run independent transactions today.
  • Optional listeners on the same process: --mysql (MySQL wire), --pg-socket-dir <dir> (Unix-domain socket at <dir>/.s.PGSQL.<port>), --http-port (health/HTTP API).

4. Background daemon

The same server, detached, with a PID file for process management.

Terminal window
heliosdb-nano start --daemon \
  --data-dir ./my-data \
  --port 5432 \
  --pid-file ./heliosdb.pid


heliosdb-nano status --pid-file ./heliosdb.pid
heliosdb-nano stop --pid-file ./heliosdb.pid
  • Best for: long-running deployments, containers, service managers.
  • Identical engine and connection semantics to the foreground server; the difference is process lifecycle, not capability.

Choosing

RequirementAccess mode
Ship the database inside the application binaryEmbedded library API
Explore or administer a data directory by handInteractive REPL
Several clients, or clients in another language/hostForeground server or daemon
Independent overlapping explicit transactionsServer or daemon (separate connections)
Run under systemd / Docker / a supervisorBackground daemon
Throwaway state for a test runAny access mode + in-memory storage
RequirementStorage mode
Data must survive restartPersistent
Reproducible, isolated test fixturesIn-memory
Fastest possible scratch workspaceIn-memory (accepting total loss on exit)

One process per data directory

A data directory is owned by exactly one running process. Starting a second process against a directory another process already has open is not supported and surfaces as lock errors (database is locked) — see Troubleshooting.

This has three practical consequences:

  • Modes are chosen at open/start time. There is no live switch between embedded and server access.
  • Moving from embedded to server is a stop-then-start handoff. Stop the embedded process, start the server against the same data directory, then repoint the application at a PostgreSQL client. Keep the engine version identical across the switch — combine one change at a time.
  • Two processes cannot share one dataset. If more than one process needs the same data, one of them must be the server and the rest must be clients.

Running a server and a REPL at the same time (“hybrid”)

Running a daemon and a REPL side by side is a genuinely useful development setup — but it is two independent processes with two separate data directories, not shared access to one dataset:

Terminal window
# Terminal 1 — server, its own data directory
heliosdb-nano start --daemon \
  --data-dir ./server-data \
  --port 5432 \
  --pid-file ./heliosdb.pid


# Terminal 2 — REPL, a DIFFERENT data directory
heliosdb-nano repl --data-dir ./scratch-data

Writes made in the REPL are not visible to clients of the server, and vice versa. The two processes share nothing. To inspect the server’s data interactively, connect to the server with psql instead of opening a second process against its directory.

Authentication and network exposure

  • --auth accepts trust, password, md5, scram-sha-256; the default is trust.
  • Any method other than trust requires --password.
  • trust is refused on a non-loopback listener — binding to anything other than 127.0.0.1/::1 requires a real authentication method.
  • TLS: --tls-cert and --tls-key must be supplied together.
  • --max-connections (default 100) caps concurrent client connections.
Terminal window
heliosdb-nano start --daemon \
  --data-dir /var/lib/heliosdb \
  --listen 0.0.0.0 --port 5432 \
  --auth scram-sha-256 --password "$HELIOSDB_PASSWORD" \
  --tls-cert /etc/heliosdb/cert.pem --tls-key /etc/heliosdb/key.pem \
  --pid-file /run/heliosdb.pid

Configuration file

Server-mode settings can come from a TOML file instead of flags:

Terminal window
heliosdb-nano start --config heliosdb.toml
[storage]
path = "/var/lib/heliosdb"
memory_only = false
cache_size = 536870912      # bytes
compression = "zstd"
wal_enabled = true


[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 100
tls_enabled = false
# tls_cert_path = "/etc/heliosdb/cert.pem"
# tls_key_path = "/etc/heliosdb/key.pem"


[performance]
worker_threads = 8
simd_enabled = true
parallel_query = true
query_timeout_secs = 300


[encryption]
enabled = false
algorithm = "Aes256Gcm"
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }

Encryption is compiled in by default but disabled at runtime by default and requires a key source; setting algorithm alone does not encrypt anything.

See Configuration for the full key reference.

Feature differences between access modes

CapabilityEmbedded / REPLServer / daemon
SQL, vector search, branching, time travelYesYes
REPL meta commands (\d, \branches, …)REPL onlyNo
Network clients (psql, JDBC, drivers)NoYes
Per-connection sessions and transactionsNo — one process-global transaction slotYes, per connection
Row-level security / multi-tenancyYesNot reachable over PG wire, MySQL wire or REST in any release to date
AuthenticationNot applicable (in-process)trust / password / md5 / scram-sha-256

Backups

Do not treat a copy of a live data directory as a backup. Use the dump/restore path, which is the supported mechanism:

Terminal window
heliosdb-nano dump --data-dir ./my-data --output backup.heliodump
heliosdb-nano restore --input backup.heliodump --target ./restored --verify

The same operations are available on the embedded API as dump_full and restore_from_dump.