In-Memory Mode Quick Reference

In-Memory Mode Quick Reference

Available since: v3.6.0 Flag: --memory Persistence: none (unless paired with --dump-on-shutdown)

---

UVP

Spinning up a fresh database for every CI run is the single most common source of flaky tests. HeliosDB Nano’s --memory flag drops the entire LSM stack into RAM — zero disk I/O, zero filesystem permissions, instant start — while keeping the full PostgreSQL wire protocol, REST API, vector search, and BaaS surface intact. Same SQL, same drivers, same client code as production. Pair with --dump-on-shutdown when you want a snapshot at exit. Sub-second test setup, no cleanup.

---

Start the Server

heliosdb-nano start --memory

Three protocols come up exactly as in disk mode:

Protocol	Port
PostgreSQL wire	5432
MySQL wire (with --mysql)	3306
REST / HTTP	8080

Add auth if your test code expects it:

heliosdb-nano start --memory --auth scram-sha-256 --password s3cret

---

REPL — Ephemeral Sandbox

heliosdb-nano repl --memory
heliosdb> CREATE TABLE t (id SERIAL PRIMARY KEY, name TEXT);
heliosdb> INSERT INTO t (name) VALUES ('hello');
heliosdb> \q
# Database vanishes on exit

---

Embedded API — Same Pattern

When using HeliosDB Nano as a library:

use heliosdb_nano::EmbeddedDatabase;

let db = EmbeddedDatabase::new_in_memory()?;
db.execute("CREATE TABLE users (id INT, name TEXT)")?;
db.execute("INSERT INTO users VALUES (1, 'Alice')")?;
let rows = db.query("SELECT * FROM users", &[])?;

EmbeddedDatabase::new_in_memory() is the in-memory equivalent of EmbeddedDatabase::new(path) — same EmbeddedDatabase type, same methods, same vector / branching / time-travel features.

---

Use Cases

CI — fast database setup per test job

.github/workflows/test.yml

- name: Start Nano
  run: |
    heliosdb-nano start --memory --daemon
    sleep 1
- name: Run integration tests
  run: pytest tests/

No volume mount, no cleanup step, no flaky teardown.

Ephemeral dev environment

# Spin up Nano + REST API on localhost in 100 ms; throw it away on Ctrl-C
heliosdb-nano start --memory --auth trust

Fixture-based tests (Python)

import pytest, psycopg2, subprocess, time

@pytest.fixture
def db():
    p = subprocess.Popen(["heliosdb-nano", "start", "--memory", "--auth", "trust"])
    time.sleep(0.5)
    conn = psycopg2.connect("postgresql://postgres@127.0.0.1:5432/postgres")
    yield conn
    conn.close()
    p.terminate()

def test_insert(db):
    cur = db.cursor()
    cur.execute("CREATE TABLE t (id INT, name TEXT)")
    cur.execute("INSERT INTO t VALUES (1, 'x')")
    cur.execute("SELECT count(*) FROM t")
    assert cur.fetchone()[0] == 1

Snapshot-on-exit (when you do want persistence)

heliosdb-nano start --memory --dump-on-shutdown
# Ctrl-C writes ./shutdown_dump.heliodump

Restore later via heliosdb-nano restore --input shutdown_dump.heliodump --target ./data.

---

What’s the Same

• Full PostgreSQL wire protocol, MySQL wire protocol, REST API, BaaS auth
• Vector search (HNSW), branching, time-travel queries
• RLS policies, triggers, CTEs, window functions
• Every clippy / SQL-spec regression test in the suite

What’s Different

Aspect	Disk mode	Memory mode
Persistence	Yes (RocksDB)	No
WAL fsync	Yes	No (no WAL)
Crash recovery	Yes	N/A — process exit = data loss
--data-dir	Required	Forbidden (mutually exclusive)
dump CLI command	Works	Errors — use --dump-on-shutdown instead
Maximum DB size	Disk space	Available RAM

---

Limits & Trade-offs

• All data fits in RAM. A 4 GiB heap holds roughly 4 GiB of rows; no spilling to disk.
• No PITR / time-travel beyond process lifetime. AS OF queries work within the running process; once the process exits, the history is gone.
• No HA replication. Tier 1 standby requires a WAL stream from the primary. Memory mode has no WAL.
• No dump from a live memory DB. Use --dump-on-shutdown (graceful exit) or implement a periodic SQL COPY to disk.

---

Troubleshooting

Symptom	Cause	Fix
Either --data-dir or --memory must be specified	Neither flag passed	Add one of them
Cannot dump from in-memory database without data directory	Tried heliosdb-nano dump --memory	Use start --memory --dump-on-shutdown
OOM-killed under load	Working set exceeds RAM	Reduce dataset, run with disk mode, or run with more memory
Tests pass locally, fail in CI	CI has stricter memory limits	Bump CI runner memory or switch to --data-dir /tmp

---

Where Next

• BACKUP_RESTORE_TUTORIAL — pairing --memory with --dump-on-shutdown.
• GETTING_STARTED_TUTORIAL — full disk-mode walkthrough.
• BAAS_REST_API_TUTORIAL — REST API works identically in memory mode.