HeliosDB Nano Quick Fix Guide

Use this page for common operational issues when starting Nano, connecting with PostgreSQL clients, or running in memory mode.

Startup

Port already in use

ss -ltnp | grep ':5432'
heliosdb-nano start --port 55432 --data-dir ./data

Update your connection string to the selected port:

psql postgresql://127.0.0.1:55432/heliosdb

Data directory permissions

mkdir -p ./data
chmod 700 ./data
heliosdb-nano start --data-dir ./data

Use a service account with read/write access to the configured data directory for long-running deployments.

In-memory sessions lost data

In-memory mode keeps data in RAM. Start it with a shutdown dump when you need a snapshot on graceful exit:

heliosdb-nano repl --memory --dump-on-shutdown --dump-file ./session.heliodump
heliosdb-nano start --memory --dump-on-shutdown --data-dir ./data

Server mode writes shutdown_dump.heliodump under the selected data directory.

Connections

psql cannot connect

Check that Nano is listening on the expected address and port:

heliosdb-nano start --listen 127.0.0.1 --port 5432 --data-dir ./data
psql postgresql://127.0.0.1:5432/heliosdb

For container deployments, publish the port and connect to the host-mapped port.

Authentication mismatch

Match the client and server authentication mode. For local development, use the default local connection settings. For shared or remote environments, configure authentication and TLS before exposing the port.

Queries

SQL compatibility issue

Verify the statement against the current SQL Reference, then isolate the smallest failing query. When using generated SQL from an ORM, check the PostgreSQL Protocol Quick Start for supported wire-protocol behavior.

Slow query

Start with EXPLAIN, reduce unnecessary result rows with LIMIT, and add the appropriate primary key, secondary index, or vector index for the access pattern.

Safe Recovery

Before changing storage settings, take a dump or filesystem backup:

heliosdb-nano dump --data-dir ./data --output ./backup.heliodump

Restore into a separate directory first:

heliosdb-nano restore --input ./backup.heliodump --data-dir ./restore-test