---
title: "HeliosDB Nano Quick Fix Guide"
---

# 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

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

Update your connection string to the selected port:

```bash
psql postgresql://127.0.0.1:55432/heliosdb
```

### Data directory permissions

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

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

```bash
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](https://www.heliosdb.com/docs/nano/guides/sql_reference/), then isolate the smallest failing query. When using generated SQL from an ORM, check the [PostgreSQL Protocol Quick Start](https://www.heliosdb.com/docs/nano/guides/postgres_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:

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

Restore into a separate directory first:

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