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 for the full option tables.

Overview
Dump Operations
Restore Operations
Scheduled Dumps
Disaster Recovery
Verification
Troubleshooting
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 on the running server.

Basic Dump Command

# 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

# 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:

# 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

# 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:

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

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

[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.

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

# 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

# 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:

#!/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

# 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

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'