Skip to content
HeliosDB HeliosDB Nano

Deployment Modes

Deployment Modes

Applies to: HeliosDB Nano 4.31.1

Deploying HeliosDB Nano means making two independent choices. The full reference — flags, configuration, authentication, feature differences — lives in Deployment Modes; this page is the short version.

1. Storage mode — where the data lives

Storage modeHowData 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 modeHowUse it for
Embedded library APIEmbeddedDatabase::new(...) in your processDesktop, mobile, edge, CLI tools, single-process services
Interactive REPLheliosdb-nano repl --data-dir ./my-dataSchema work, ad-hoc queries, inspection
Foreground serverheliosdb-nano start --data-dir ./my-data --port 5432Development against real clients, protocol debugging
Background daemonheliosdb-nano start --daemon --data-dir ./my-data --pid-file ./heliosdb.pidLong-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:

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:

Terminal window
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.

Next steps