---
title: "Dump and Restore Procedures Guide"
---

# Dump and Restore Procedures Guide

This guide covers the `heliosdb-nano dump` and `heliosdb-nano restore`
commands and the server's scheduled dumps. Flags are listed exactly as the
current release accepts them; see the
[CLI Reference](https://www.heliosdb.com/docs/nano/reference/cli_reference/) for the full option tables.

## Table of Contents

1. [Overview](#overview)
2. [Dump Operations](#dump-operations)
3. [Restore Operations](#restore-operations)
4. [Scheduled Dumps](#scheduled-dumps)
5. [Disaster Recovery](#disaster-recovery)
6. [Verification](#verification)
7. [Troubleshooting](#troubleshooting)
8. [Examples](#examples)

## Overview

Dump/restore gives you portable snapshots of a database:

- **Snapshots**: write a data directory to a single `.heliodump` file
- **Incremental dumps**: append changes to an existing dump (`--append`)
- **In-memory persistence**: dump an in-memory server or REPL on shutdown
- **Migration**: move data between machines or into a fresh data directory

### Dump File Format

`.heliodump` files are a versioned binary format:

- Start with the magic bytes `HELIODMP` and a format version; a restore refuses
  only dumps written by a *newer* format version
- Carry table schemas, vector index metadata, constraints and rows
- Are compressed with `zstd` (default), `gzip`, `brotli`, or not at all (`none`)

## Dump Operations

`dump` reads a **data directory** (embedded mode). Server-mode dumps over a
connection (`--connection`) are not implemented yet and exit with an error, so
either stop the server first, dump a copy of the data directory, or use
[scheduled dumps](#scheduled-dumps) on the running server.

### Basic Dump Command

```bash
# Full dump (zstd-compressed by default)
heliosdb-nano dump --data-dir ./mydb --output /backups/mydb.heliodump

# Choose the compression algorithm
heliosdb-nano dump --data-dir ./mydb --output /backups/mydb.heliodump --compression gzip

# No compression (fastest, largest file)
heliosdb-nano dump --data-dir ./mydb --output /backups/mydb.heliodump --compression none

# Verbose progress
heliosdb-nano dump --data-dir ./mydb --output /backups/mydb.heliodump --verbose
```

| Option | Description | Default |
|--------|-------------|---------|
| `-d`, `--data-dir` | Data directory to dump (required) | - |
| `-o`, `--output` | Output file | `backup.heliodump` |
| `-a`, `--append` | Append incremental changes to an existing dump | `false` |
| `--compression` | `zstd`, `gzip`, `brotli`, `none` | `zstd` |
| `-v`, `--verbose` | Verbose output | `false` |

The dump command always dumps every table; there is no per-table filter,
compression level or dry-run option.

### Full vs Incremental Dumps

```bash
# First dump (full)
heliosdb-nano dump --data-dir ./mydb --output /backups/base.heliodump

# Later dumps append the changes since the last dump
heliosdb-nano dump --data-dir ./mydb --output /backups/base.heliodump --append
```

Start a new full dump periodically (for example weekly) so a restore does not
have to replay a long chain of appended changes.

### Dumping an In-Memory Database

An in-memory database has no data directory, so dump it as it shuts down:

```bash
# Server
heliosdb-nano start --memory --dump-on-shutdown

# REPL (default file: heliosdb_dump.heliodump)
heliosdb-nano repl --memory --dump-on-shutdown --dump-file session.heliodump
```

## Restore Operations

`restore` writes a dump into a data directory, creating it if needed. Then
start a server (or REPL) on that directory.

### Basic Restore Command

```bash
# Restore into ./restored-db (default target: ./heliosdb-data-restored)
heliosdb-nano restore --input /backups/mydb.heliodump --target ./restored-db

# Check integrity first
heliosdb-nano restore --input /backups/mydb.heliodump --target ./restored-db --verify

# Serve the restored data
heliosdb-nano start --data-dir ./restored-db
```

| Option | Description | Default |
|--------|-------------|---------|
| `-i`, `--input` | Dump file (required) | - |
| `-t`, `--target` | Target data directory | `./heliosdb-data-restored` |
| `--verify` | Verify dump integrity before restoring | `false` |
| `--no-validate` | Restore even if rows violate the dump's constraints, reporting each as a warning | `false` |
| `-v`, `--verbose` | Verbose output | `false` |

There are no restore modes (`clean`/`append`), conflict policies, table filters
or dry-run option, and restoring into a running server over a connection
(`--connection`) is not implemented yet. Restore into a fresh directory, then
point the server at it.

### Constraint Validation

By default a restore fails if the dumped rows violate the constraints stored in
the dump. A database that legitimately holds such rows (for example a
`NOT ENFORCED` constraint) can be restored with `--no-validate`; each violation
is printed as a warning.

## Scheduled Dumps

A running server can dump itself on a cron schedule, either from the command line:

```bash
heliosdb-nano start --data-dir /var/lib/heliosdb --dump-schedule "0 2 * * *"
```

or from the `[dump]` section of the configuration file:

```toml
[dump]
auto_dump_enabled = true
schedule = "0 */6 * * *"     # every 6 hours
compression = "zstd"         # zstd, gzip or none
dump_dir = "/var/backups/heliosdb"
keep_dumps = 10              # 0 = keep all
max_dump_size_mb = 10000
```

See the [Configuration Reference](https://www.heliosdb.com/docs/nano/reference/configuration_reference/#dump-configuration).

For cold backups of a stopped server, a cron job or systemd timer can call
`dump` directly:

```bash
# crontab -e   (daily at 02:00, server stopped or a snapshot copy of the directory)
0 2 * * * heliosdb-nano dump --data-dir /var/lib/heliosdb-snapshot --output /backups/daily-$(date +\%Y\%m\%d).heliodump
```

## Disaster Recovery

```bash
# 1. Install HeliosDB Nano on the new host
# Resolve the latest release tag; pin a specific tag (VER=vX.Y.Z) in production
VER=$(curl -sSfL -o /dev/null -w '%{url_effective}' https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest | sed 's#.*/tag/##')
curl -sSfL -O "https://github.com/HeliosDatabase/HeliosDB-Nano/releases/download/$VER/heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
tar xzf "heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
sudo mv heliosdb-nano /usr/local/bin/

# 2. Fetch the latest dump (from wherever you store backups)
cp /mnt/backups/heliosdb-latest.heliodump ./

# 3. Restore into a fresh data directory
heliosdb-nano restore --input heliosdb-latest.heliodump --target /var/lib/heliosdb --verify

# 4. Start the server
heliosdb-nano start --data-dir /var/lib/heliosdb --listen 0.0.0.0 \
    --auth scram-sha-256 --password "$HELIOS_PASSWORD"

# 5. Spot-check the data
psql -h localhost -U postgres -c "SELECT COUNT(*) FROM users"
```

### Testing Restores

Restore the latest dump into a scratch directory regularly and run your own
validation queries against it:

```bash
#!/bin/bash
set -euo pipefail
TEST_DIR=$(mktemp -d)
heliosdb-nano restore --input /backups/heliosdb-latest.heliodump --target "$TEST_DIR/db" --verify
heliosdb-nano start --data-dir "$TEST_DIR/db" --port 15432 --daemon --pid-file "$TEST_DIR/pid"
sleep 2
psql -h localhost -p 15432 -U postgres -c "SELECT COUNT(*) FROM users"
heliosdb-nano stop --pid-file "$TEST_DIR/pid"
rm -rf "$TEST_DIR"
```

## Verification

- `restore --verify` checks the dump's integrity before writing anything.
- After a restore, compare row counts (`SELECT COUNT(*) ...`) and schemas
  (`\d <table>` in the REPL, or `information_schema.columns`) with the source.

## Troubleshooting

### "Server mode dump not yet implemented"

You passed `--connection`. Dump the data directory with `--data-dir` instead
(stop the server or use a copy), or enable scheduled dumps on the server.

### "Either --data-dir or --connection must be specified"

`dump` has no default data directory; pass `--data-dir`.

### Restore fails on constraint violations

The dumped rows violate a constraint the dump carries. Fix the source data, or
restore with `--no-validate` to load the rows and print each violation as a
warning.

### Dump written by a newer version

A restore refuses a dump whose format version is newer than the binary's.
Restore with the same or a newer `heliosdb-nano` release.

## Examples

### Development Fixtures

```bash
# Create the fixture once
heliosdb-nano dump --data-dir ./seed-db --output fixtures/seed-data.heliodump

# Reset before each test run
rm -rf ./test-db
heliosdb-nano restore --input fixtures/seed-data.heliodump --target ./test-db
```

### Moving a Database to Another Host

```bash
heliosdb-nano stop --pid-file ./heliosdb.pid
heliosdb-nano dump --data-dir ./mydb --output migration.heliodump
scp migration.heliodump new-host:/tmp/
ssh new-host 'heliosdb-nano restore --input /tmp/migration.heliodump --target /var/lib/heliosdb'
```

## See Also

- [In-Memory Mode Guide](https://www.heliosdb.com/docs/nano/guides/user/inmemory_mode/) - In-memory database operations
- [CLI Reference](https://www.heliosdb.com/docs/nano/reference/cli_reference/) - Complete command reference
- [Configuration Reference](https://www.heliosdb.com/docs/nano/reference/configuration_reference/) - Dump settings
- [Disaster Recovery Guide](https://www.heliosdb.com/docs/nano/enterprise/disaster_recovery/) - DR best practices