---
title: "In-Memory Mode Quick Reference"
---

# In-Memory Mode Quick Reference

**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

```bash
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:

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

---

## REPL — Ephemeral Sandbox

```bash
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:

```rust
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

```yaml
# .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

```bash
# 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)

```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)

```bash
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 static analysis / 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](https://www.heliosdb.com/docs/nano/guides/tutorials/backup_restore_tutorial/) — pairing `--memory` with `--dump-on-shutdown`.
- [GETTING_STARTED_TUTORIAL](https://www.heliosdb.com/docs/nano/guides/tutorials/getting_started_tutorial/) — full disk-mode walkthrough.
- [BAAS_REST_API_TUTORIAL](https://www.heliosdb.com/docs/nano/guides/tutorials/baas_rest_api_tutorial/) — REST API works identically in memory mode.