--- title: "HeliosDB Full Server Configuration Reference" --- # 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](mailto:sales@heliosdb.com). > In the examples on this page, replace `` 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.** ```bash 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 | ```bash # 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 ` 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. :::caution[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: ```sql 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) :::caution[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): ```bash 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`) | `/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`) | `/warm`, `/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](/docs/full/reference/api/http_rest_api/). --- ## 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: ```toml [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: ```sql 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 ```ini # /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 ```bash 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 \ \ --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.