Skip to content
HeliosDB HeliosDB Full

Production Deployment: Appendix

Part of: Production Deployment Guide

A. Quick Reference Commands

Terminal window
# Server version and the features and listeners in this build
heliosdb-full --version
heliosdb-full --show-features --all


# Every flag and its environment variable
heliosdb-full --help


# Start (systemd / container)
systemctl start heliosdb
docker start heliosdb


# Health and readiness (no key needed)
curl -fsS http://127.0.0.1:8443/health
curl -fsS http://127.0.0.1:8443/ready


# Connect
psql "host=127.0.0.1 port=5432 user=postgres"


# Status from SQL
psql "host=127.0.0.1 user=postgres" -c "SHOW SERVER STATUS" -c "SHOW PROTOCOLS" -c "SHOW CONNECTIONS"


# Storage and WAL
psql "host=127.0.0.1 user=postgres" -c "SHOW STORAGE STATUS" -c "SHOW WAL STATUS"


# Run SQL over HTTP
curl -s -X POST http://127.0.0.1:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"SELECT 1"}'


# Logs
journalctl -u heliosdb -f          # or: docker logs -f heliosdb


# Cold backup (see Backup & Disaster Recovery)
systemctl stop heliosdb && tar -C /var/lib -czf /backup/heliosdb-$(date +%F).tar.gz heliosdb && systemctl start heliosdb

B. Configuration Examples

Development, on localhost only:

Terminal window
HELIOSDB_SUPERUSER_PASSWORD=dev-only-password heliosdb-full --data-dir ./data

Production, reachable from a private network, TLS required on PostgreSQL:

Terminal window
# /etc/heliosdb/heliosdb.env (mode 0600): HELIOSDB_SUPERUSER_PASSWORD=..., HELIOSDB_API_KEY=...
heliosdb-full \
  --data-dir /var/lib/heliosdb \
  --bind-addr 10.0.0.12 --allow-external \
  --tls-cert /etc/heliosdb/tls/server.crt --tls-key /etc/heliosdb/tls/server.key --tls-require \
  --enable-compaction --read-cache-mb 1024 --enable-secondary-indexes \
  --max-connections 2000

With the MySQL and Oracle listeners for existing applications:

Terminal window
heliosdb-full --data-dir /var/lib/heliosdb --bind-addr 10.0.0.12 --allow-external \
  --enable-mysql --enable-oracle

The Server Configuration Reference lists every flag, environment variable and config-file key.

C. Port Reference

PortListenerDefault stateFlag
5432PostgreSQL wireon--postgres-port, --no-postgres
8443HTTP gateway (plain HTTP)on--http-port, --no-http
3306MySQL wireoff--enable-mysql, --mysql-port
1521Oracle TNSoff--enable-oracle, --oracle-port
1433SQL Server TDSoff--enable-sqlserver, --sqlserver-port
27017MongoDB wireoff--enable-mongodb, --mongodb-port
9042Cassandra CQLoff--enable-cassandra, --cassandra-port
6379Redis RESPoff--enable-redis, --redis-port

All listeners bind --bind-addr (default 127.0.0.1). Open in the firewall only the ports of the listeners you enable.

D. Sizing

HeliosDB Full runs as a single server process per data directory. Size it like a single-node database:

  • Disk: data size × 1.5 for SSTables awaiting compaction, plus the WAL and room for a local backup copy if you keep one. Use SSD or NVMe; every commit is fsynced by default.
  • Memory: 64 MB memtable (memtable_size_mb) + the read cache (--read-cache-mb) + working memory per concurrent query, plus operating-system page cache for the SSTables.
  • CPU: connections are served concurrently on the server’s async runtime, which uses all cores; size CPU by load-testing your own workload.
  • Connections: keep idle connections in a pool; --max-connections caps the total.

E. Support Resources

F. Glossary

  • ACID: Atomicity, Consistency, Isolation, Durability
  • LSM tree: Log-structured merge tree, the storage engine layout (memtable + SSTables)
  • Memtable: In-memory write buffer, flushed to SSTables
  • SSTable: Sorted, immutable data file on disk
  • Compaction: Merging SSTables to reclaim space and keep reads fast
  • WAL: Write-ahead log, replayed after a crash
  • SCRAM-SHA-256: Password authentication used by the PostgreSQL listener
  • TNS: Oracle’s network protocol, served by the Oracle listener
  • QPS: Queries per second
  • RTO: Recovery time objective
  • RPO: Recovery point objective