HeliosDB Full Server Configuration Reference

Container images: HeliosDB Full images are not published on Docker Hub or any other public registry. Images and Helm charts are provided through private registry access during onboarding: contact sales@heliosdb.com. In the examples on this page, replace <heliosdb-full-image> with the image reference you receive.

HeliosDB Full runs as one server binary, heliosdb-full. You work with it through the database clients you already use (psql, MySQL clients, Oracle, MongoDB, Cassandra and Redis drivers) and configure it in three places:

1. Build features decide which feature groups are compiled into the binary.
2. Command-line flags, each with an environment-variable twin, configure the listeners, authentication, storage and limits. This is where almost all configuration happens.
3. A small TOML file can hold storage settings.

Inside a session, standard SQL (SET, SHOW, EXPLAIN, CREATE ROLE, …) does the rest. There is no separate administration tool to install.

Precedence: command-line flag > environment variable > config file > default.

heliosdb-full --help                  # every flag with its environment variable
heliosdb-full --show-features         # compiled-in feature groups and how to enable each listener
heliosdb-full --show-features --all   # also lists what this server does not provide

---

Build features

The release build uses --features full. heliosdb-full --show-features prints the feature groups compiled into your binary and the build type (FULL or MINIMAL). A feature being compiled in does not by itself open a listener or start a service; the flags below do that.

---

Listeners

Listener	Default	Enable / disable	Port flag (environment)
PostgreSQL wire	on	--no-postgres	--postgres-port (HELIOSDB_POSTGRES_PORT), default 5432
HTTP gateway	on	--no-http	--http-port (HELIOSDB_HTTP_PORT), default 8443
MySQL wire	off	--enable-mysql	--mysql-port (HELIOSDB_MYSQL_PORT), default 3306
Oracle TNS	off	--enable-oracle	--oracle-port (HELIOSDB_ORACLE_PORT), default 1521
SQL Server TDS	off	--enable-sqlserver	--sqlserver-port (HELIOSDB_SQLSERVER_PORT), default 1433
MongoDB wire	off	--enable-mongodb	--mongodb-port (HELIOSDB_MONGODB_PORT), default 27017
Cassandra CQL	off	--enable-cassandra	--cassandra-port (HELIOSDB_CASSANDRA_PORT), default 9042
Redis RESP	off	--enable-redis	--redis-port (HELIOSDB_REDIS_PORT), default 6379

All listeners share one bind address:

Flag (environment)	Default	Meaning
--bind-addr (HELIOSDB_BIND_ADDR)	127.0.0.1	Address every listener binds
--allow-external (HELIOSDB_ALLOW_EXTERNAL)	off	Required for any non-loopback bind; without it the server refuses to start

# PostgreSQL + HTTP on localhost (default)
heliosdb-full --data-dir /var/lib/heliosdb

# Also MySQL and Oracle, reachable from the private network
heliosdb-full --data-dir /var/lib/heliosdb \
  --bind-addr 10.0.0.12 --allow-external \
  --enable-mysql --enable-oracle

The server logs one line per listener (PostgreSQL protocol listening on ...) and a summary when it is ready. A port that cannot be bound is logged as a warning and that listener stays closed; the server exits only if no listener could start.

---

Authentication and credentials

Flag (environment)	Default	Meaning
--auth-mode (HELIOSDB_AUTH_MODE)	scram	scram requires credentials on every protocol. trust accepts PostgreSQL and HTTP clients without credentials and is accepted only on a loopback bind (it does not change the MySQL listener, which always requires an existing role name and a non-empty password)
HELIOSDB_SUPERUSER_PASSWORD	random	Password of the built-in superuser postgres. When unset, the server generates one and prints it once at startup
HELIOSDB_API_KEY	unset	Key for the HTTP gateway (Authorization: Bearer or X-API-Key); without it, data routes return 401

Which credentials each listener accepts:

Listener	Log on with
PostgreSQL	postgres with HELIOSDB_SUPERUSER_PASSWORD, or any role created with CREATE ROLE ... LOGIN PASSWORD '...' (SCRAM-SHA-256)
MySQL	A role from the server’s role catalog, for example postgres (caching_sha2_password or mysql_native_password). The role name is checked; the password is not yet verified (see the warning below)
Redis	AUTH <role> <password> with a role from the role catalog. The role name is checked; the password is not yet verified
Oracle TNS	Any user name with the password in HELIOSDB_ORACLE_NATIVE_PASSWORD (O5LOGON). If the variable is unset, the password is the user name itself (for example scott/scott), so always set it before --enable-oracle
SQL Server	HELIOSDB_SQLSERVER_USER / HELIOSDB_SQLSERVER_PASSWORD
MongoDB	HELIOSDB_MONGODB_USER / HELIOSDB_MONGODB_PASSWORD
Cassandra	HELIOSDB_CASSANDRA_USER / HELIOSDB_CASSANDRA_PASSWORD
HTTP	HELIOSDB_API_KEY

The SQL Server, MongoDB and Cassandra listeners deny every login until their credentials are set. The Oracle listener does not deny logins when HELIOSDB_ORACLE_NATIVE_PASSWORD is unset: it then accepts any user whose password equals the user name.

MySQL and Redis listeners: passwords are not verified yet

The MySQL listener checks that the role exists and that the client sent a non-empty password, but it does not yet verify the password: any non-empty password is accepted for an existing role, including postgres; the Redis listener accepts AUTH for any existing role name. Use --enable-mysql and --enable-redis only on loopback or a private network where every client is trusted; use the PostgreSQL listener where authentication matters.

Run the MySQL, Redis, Oracle, SQL Server, MongoDB and Cassandra listeners on loopback or a private network segment and restrict their ports with a firewall. HeliosDB Full listeners do not terminate TLS; native PostgreSQL TLS (below) is planned for the next release.

Pass secrets through the environment from a secrets manager or an environment file that only the service account can read (EnvironmentFile= in systemd, --env-file or orchestrator secrets in containers), not on the command line.

Roles

Roles are managed with SQL over the PostgreSQL listener:

CREATE ROLE app LOGIN PASSWORD 'change-me' CONNECTION LIMIT 50 VALID UNTIL '2027-01-01';
ALTER ROLE app PASSWORD 'new-password';
ALTER ROLE app NOLOGIN;
DROP ROLE app;

LOGIN/NOLOGIN, PASSWORD (stored as a SCRAM-SHA-256 verifier), VALID UNTIL and CONNECTION LIMIT are enforced at login. In the current release every role that can log in has full access to the data: GRANT/REVOKE and row-level security return SQLSTATE 0A000. Separate applications by server instance (or data directory) when they need isolation from each other.

---

TLS (PostgreSQL listener)

TLS: next release

HeliosDB Full listeners do not terminate TLS; put a TLS-terminating proxy in front, and native PostgreSQL TLS (with post-quantum key exchange preferred) is planned for the next release. The --tls-cert, --tls-key and --tls-require flags in this section belong to that release.

Flag (environment)	Meaning
--tls-cert (HELIOSDB_TLS_CERT)	PEM certificate chain, leaf first
--tls-key (HELIOSDB_TLS_KEY)	PEM private key (PKCS#8, PKCS#1 or SEC1)
--tls-require (HELIOSDB_TLS_REQUIRE)	Refuse sessions that did not negotiate TLS

The files are read once at startup; an unreadable or invalid file stops startup. Without a certificate, a client’s TLS request is declined and the session is plaintext. Clients connect with sslmode=require (or verify-full with your CA):

heliosdb-full --tls-cert /etc/heliosdb/tls/server.crt --tls-key /etc/heliosdb/tls/server.key --tls-require
psql "host=db.internal port=5432 user=postgres sslmode=verify-full sslrootcert=/etc/ssl/ca.pem"

The other listeners, including the HTTP gateway, are plaintext: terminate TLS in front of them (a reverse proxy for HTTP, a TLS tunnel or private network for the others).

---

Storage and durability

Flag (environment)	Default	Meaning
-d, --data-dir (HELIOSDB_STORAGE_DATA_DIR)	/var/lib/heliosdb	Data directory (WAL under wal/)
--synchronous-commit on|off (HELIOSDB_SYNCHRONOUS_COMMIT)	on	on: each acknowledged write is fsynced. off: acknowledge after the OS write and fsync on an interval
--wal-flush-interval-ms (HELIOSDB_WAL_FLUSH_INTERVAL_MS)	5	Fsync interval with --synchronous-commit off (1-10000)
--flush-interval-secs (HELIOSDB_FLUSH_INTERVAL_SECS)	60	Background memtable flush to SSTables; 0 disables it
--enable-compaction	off	Background LSM compaction
--compaction-strategy size-tiered|leveled (HELIOSDB_COMPACTION_STRATEGY)	size-tiered	Compaction strategy
--compaction-max-level (HELIOSDB_COMPACTION_MAX_LEVEL)	7	Levels for leveled
--compaction-l0-threshold-mb (HELIOSDB_COMPACTION_L0_THRESHOLD_MB)	100	Level-0 size that triggers compaction
--compaction-min-sstables (HELIOSDB_COMPACTION_MIN_SSTABLES)	4	SSTables needed for a size-tiered compaction
--compaction-max-mbps (HELIOSDB_COMPACTION_MAX_MBPS)	0 (unthrottled)	Compaction write throughput cap
--compaction-max-concurrent (HELIOSDB_COMPACTION_MAX_CONCURRENT)	4	Concurrent compaction tasks
--read-cache-mb (HELIOSDB_READ_CACHE_MB)	0 (off)	SSTable read cache size
--prefetch-depth (HELIOSDB_PREFETCH_DEPTH)	4	Slots read ahead on a cache miss
--prefetch-min-run (HELIOSDB_PREFETCH_MIN_RUN)	2	Sequential reads before readahead starts
--prefetch-max-bytes (HELIOSDB_PREFETCH_MAX_BYTES)	1048576	Cap on one readahead
--enable-secondary-indexes	off	Makes CREATE INDEX build and maintain indexes (otherwise it records catalog metadata only)
--index-dir (HELIOSDB_INDEX_DIR)	<data-dir>/indexes	Secondary index data
--enable-tiering	off	Creates warm/cold tier directories
--warm-tier-path, --cold-tier-path (HELIOSDB_WARM_TIER_PATH, HELIOSDB_COLD_TIER_PATH)	<data-dir>/warm, <data-dir>/cold	Tier directories
--cold-tier-after-hours (HELIOSDB_COLD_TIER_AFTER_HOURS)	24	Age before data is considered cold

On SIGTERM or Ctrl+C the server flushes the memtable and stops; acknowledged writes are also in the WAL and are replayed after a crash.

---

Connections, limits and logging

Flag (environment)	Default	Meaning
--max-connections (HELIOSDB_MAX_CONNECTIONS)	10000	Concurrent client connections across all listeners
--startup-timeout-secs (HELIOSDB_STARTUP_TIMEOUT_SECS)	30	Time a client has to complete the handshake and authentication
HELIOSDB_RATE_LIMITING	true	Connection and query rate limiting; set HELIOSDB_RATE_LIMITING=false to turn it off. The --rate-limiting flag takes no value and cannot turn it off
--conn-rate-limit (HELIOSDB_CONN_RATE_LIMIT)	500/min per IP	New connections per client IP per minute
--query-rate-limit (HELIOSDB_QUERY_RATE_LIMIT)	unset	Queries per second per client IP (PostgreSQL wire and HTTP SQL); off unless set
--log-min-duration-statement (HELIOSDB_LOG_MIN_DURATION_STATEMENT)	1000 ms	Log statements slower than this at WARN; -1 disables, 0 logs all. A session can override it with SET
-v, --verbose	off	Debug logging

The server logs at info level, or at debug level with --verbose; it does not apply RUST_LOG filters.

HTTP gateway settings (--http-sessions, --http-pg-pool-size and the session limits) are described in the HTTP/REST API reference.

---

Config file

The server reads one TOML file, from the first of: --config / HELIOSDB_CONFIG, ./heliosdb.toml, /etc/heliosdb/heliosdb.toml, ~/.config/heliosdb/heliosdb.toml. It honours these keys:

[storage]
data_dir = "/var/lib/heliosdb"
memtable_size_mb = 64          # also HELIOSDB_STORAGE_MEMTABLE_SIZE_MB
compaction_strategy = "SizeTiered"   # or { Leveled = { max_level = 7 } }
read_cache_mb = 512
prefetch_depth = 4
prefetch_min_run = 2
prefetch_max_bytes = 1048576

A file that sets any other key stops startup with a list of the keys the server would ignore, so a setting can never be silently dropped. Move those settings to flags or environment variables, or set HELIOSDB_CONFIG_ALLOW_UNSUPPORTED=1 to start anyway with them ignored.

---

Session settings (SQL)

Standard PostgreSQL session settings work from any client:

SET statement_timeout = '30s';
SET lock_timeout = '5s';
SET idle_in_transaction_session_timeout = '60s';
SET idle_session_timeout = '10min';
SET log_min_duration_statement = 250;
SET search_path TO app, public;
SHOW statement_timeout;
RESET statement_timeout;
BEGIN READ ONLY;      -- writes in this transaction fail with 25006

The four timeouts and read-only transactions are enforced. Planner and resource knobs (work_mem, enable_*, …) are accepted and stored for client compatibility. Settings HeliosDB cannot honour, such as a non-UTC TimeZone or a per-session synchronous_commit, are refused with 0A000 rather than silently ignored; an unknown name returns 42704.

---

Monitoring with SQL

These statements run from psql or any PostgreSQL client:

Statement	Shows
SHOW SERVER STATUS	Version, uptime, protocols, table count
SHOW PROTOCOLS	Protocols and their ports
SHOW CONNECTIONS (also SHOW ACTIVE QUERIES)	Sessions with user, database, state and current statement
SELECT * FROM pg_stat_activity	Sessions, PostgreSQL style
SHOW TRANSACTIONS, SHOW LOCKS, SHOW PREPARED TRANSACTIONS, SHOW SAVEPOINTS	Transactions and locks
SHOW STORAGE STATUS, SHOW STORAGE TIERS, SHOW WAL STATUS	Storage engine, tiers, WAL
SHOW QUERY CACHE	Parse, scan and wire caches
FLUSH QUERY CACHE, FLUSH SCAN CACHE, FLUSH WIRE CACHE	Clear those caches
SHOW CDC EVENTS [LIMIT n] (alias SHOW AUDIT LOG)	Recent INSERT/UPDATE/DELETE events, kept in memory
SHOW CERTIFICATES	TLS certificate in use
SHOW TABLES, SHOW INDEXES [ON t], SHOW COLUMNS FROM t, SHOW CREATE TABLE t, SHOW ROLES	Catalog
SHOW DASHBOARD	Table count, cache entries, change events, version
EXPLAIN [ANALYZE] ..., EXPLAIN (FORMAT JSON|YAML|XML|HTML|GRAPHVIZ|MERMAID) ...	Query plans

Statements for subsystems that this server does not run (for example SHOW REPLICATION STATUS, FAILOVER, CREATE SNAPSHOT, SHOW BACKUP STATUS) return SQLSTATE 0A000 with an explanation and change nothing. heliosdb-full --show-features --all lists them.

The HTTP gateway serves GET /health and GET /ready without authentication for liveness and readiness probes.

---

Example: systemd unit

/etc/systemd/system/heliosdb.service

[Unit]
Description=HeliosDB Full
After=network-online.target

[Service]
User=heliosdb
EnvironmentFile=/etc/heliosdb/heliosdb.env      # HELIOSDB_SUPERUSER_PASSWORD, HELIOSDB_API_KEY (mode 0600)
ExecStart=/usr/local/bin/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
Restart=on-failure
LimitNOFILE=65536
TimeoutStopSec=60

[Install]
WantedBy=multi-user.target

Example: container

docker run -d --name heliosdb \
  --env-file /etc/heliosdb/heliosdb.env \
  -p 127.0.0.1:5432:5432 -p 127.0.0.1:8443:8443 \
  -v heliosdb-data:/var/lib/heliosdb/data \
  <heliosdb-full-image> \
  --enable-compaction --read-cache-mb 1024

The image sets HELIOSDB_STORAGE_DATA_DIR=/var/lib/heliosdb/data, HELIOSDB_BIND_ADDR=0.0.0.0 and HELIOSDB_ALLOW_EXTERNAL=true; arguments after the image name are passed to heliosdb-full. Publish only the ports you use.