Server configuration

Every option has three spellings: a flag, an environment variable, and a key in the YAML file named by --config FILE (or HARDCHARGER_CONFIG). A flag wins over an environment variable, which wins over the file, which wins over the default. Unknown flags and YAML keys stop the server. The configuration guide shows them in use.

Besides the options below, the server takes these command-line actions, which run and exit:

Action	Does
`--config FILE`	Read options from a YAML file (`HARDCHARGER_CONFIG`)
`--help`	List every option
`--version`, `--print-duckdb-version`	Print the server’s or DuckDB’s version
`--print-options-json`	Print every option as JSON (what this page is built from)
`--verify-tls URL`	Fetch a URL over HTTPS with the system’s CA bundle, then exit 0 or 1
`--verify-audit-log FILE [--verify-audit-log-partial]`	Check an audit log’s hash chain

96 options in 15 groups: Listener · TLS · Database · Authentication · Browser sign-in · Sessions · Statements · Access control · Statement queue · Guards · Cluster · Operations · Instrumentation · Catalog logging · Metrics.

Listener

`host`

Address to listen on.


Flag	`--host <value>`
Environment	`HARDCHARGER_HOST`
YAML	`host: …`
Type	string
Default	`0.0.0.0`

`port`

Port to listen on.


Flag	`--port <n>`
Environment	`HARDCHARGER_PORT`
YAML	`port: …`
Type	integer
Default	`31337`

`health_port`

Plaintext port serving only /health (0: none)


Flag	`--health-port <n>`
Environment	`HARDCHARGER_HEALTH_PORT`
YAML	`health_port: …`
Type	integer
Default	`0`

`max_header_bytes`

Largest request header block accepted, in bytes (0: 16384)


Flag	`--max-header-bytes <n>`
Environment	`HARDCHARGER_MAX_HEADER_BYTES`
YAML	`max_header_bytes: …`
Type	integer
Default	`16384`

`max_result_partitions`

Most partitions a result is split into for a client that reads them at once (1: never split)


Flag	`--max-result-partitions <n>`
Environment	`HARDCHARGER_MAX_RESULT_PARTITIONS`
YAML	`max_result_partitions: …`
Type	integer
Default	`32`

`web_ui`

Serve the web UI at /ui on this port (a build that embeds it)


Flag	`--web-ui`
Environment	`HARDCHARGER_WEB_UI`
YAML	`web_ui: …`
Type	boolean
Default	`false`

`trusted_proxies`

Reverse proxies (CIDRs such as 10.0.0.0/8 or fd00::/8, or single addresses) whose X-Forwarded-For or Forwarded header names the client; from them, the client’s address in logs, audit, sessions and the per-address browser sign-in bound is the rightmost forwarded hop that is not itself a trusted proxy. Never used for authentication or TLS. Empty: trust none (the TCP peer is the client)


Flag	`--trusted-proxies <a,b,...>`
Environment	`HARDCHARGER_TRUSTED_PROXIES`
YAML	`trusted_proxies: …`
Type	list
Default	`(empty)`

TLS

`tls_cert`

TLS certificate chain (PEM)


Flag	`--tls-cert <value>`
Environment	`HARDCHARGER_TLS_CERT`
YAML	`tls_cert: …`
Type	string
Default	`(empty)`

`tls_key`

TLS private key (PEM)


Flag	`--tls-key <value>`
Environment	`HARDCHARGER_TLS_KEY`
YAML	`tls_key: …`
Type	string
Default	`(empty)`

`mtls_ca_cert`

CA (PEM) client certificates must chain to.


Flag	`--mtls-ca-cert <value>`
Environment	`HARDCHARGER_MTLS_CA_CERT`
YAML	`mtls_ca_cert: …`
Type	string
Default	`(empty)`

`mtls_require_client_cert`

Refuse connections without a client certificate (false: they sign in another way)


Flag	`--mtls-require-client-cert`
Environment	`HARDCHARGER_MTLS_REQUIRE_CLIENT_CERT`
YAML	`mtls_require_client_cert: …`
Type	boolean
Default	`true`

`mtls_certificate_sign_in`

Offer certificate sign-in (the client_certificate grant); off: certificates only admit connections.


Flag	`--mtls-certificate-sign-in`
Environment	`HARDCHARGER_MTLS_CERTIFICATE_SIGN_IN`
YAML	`mtls_certificate_sign_in: …`
Type	boolean
Default	`false`

`mtls_crl_allow_missing_ca_crls`

Accept a CA above the leaf that has no CRL in mtls_crl_file (default: refuse it)


Flag	`--mtls-crl-allow-missing-ca-crls`
Environment	`HARDCHARGER_MTLS_CRL_ALLOW_MISSING_CA_CRLS`
YAML	`mtls_crl_allow_missing_ca_crls: …`
Type	boolean
Default	`false`

`mtls_crl_file`

Certificate revocation lists (PEM) for client certificates; reloaded when the file changes.


Flag	`--mtls-crl-file <value>`
Environment	`HARDCHARGER_MTLS_CRL_FILE`
YAML	`mtls_crl_file: …`
Type	string
Default	`(empty)`

`mtls_identity_source`

Where certificate sign-in takes the identity from: san_email, san_uri or subject_cn.


Flag	`--mtls-identity-source <value>`
Environment	`HARDCHARGER_MTLS_IDENTITY_SOURCE`
YAML	`mtls_identity_source: …`
Type	string
Default	`san_email`

`mtls_admin_identities`

Client certificate identities that sign in as the administrator.


Flag	`--mtls-admin-identities <a,b,...>`
Environment	`HARDCHARGER_MTLS_ADMIN_IDENTITIES`
YAML	`mtls_admin_identities: …`
Type	list
Default	`(empty)`

`mtls_require_identity_match`

A password or token sign-in over a client certificate must be for its identity.


Flag	`--mtls-require-identity-match`
Environment	`HARDCHARGER_MTLS_REQUIRE_IDENTITY_MATCH`
YAML	`mtls_require_identity_match: …`
Type	boolean
Default	`false`

Database

`database`

DuckDB database file, or :memory:.


Flag	`--database <value>`
Environment	`HARDCHARGER_DATABASE`
YAML	`database: …`
Type	string
Default	`:memory:`

`read_only`

Open the database read-only.


Flag	`--read-only`
Environment	`HARDCHARGER_READ_ONLY`
YAML	`read_only: …`
Type	boolean
Default	`false`

`memory_limit`

DuckDB memory_limit, e.g. 8GB.


Flag	`--memory-limit <value>`
Environment	`HARDCHARGER_MEMORY_LIMIT`
YAML	`memory_limit: …`
Type	string
Default	`(empty)`

`storage_version`

DuckDB storage version for new databases.


Flag	`--storage-version <value>`
Environment	`HARDCHARGER_STORAGE_VERSION`
YAML	`storage_version: …`
Type	string
Default	`(empty)`

`allow_unsigned_extensions`

Let DuckDB load unsigned extensions.


Flag	`--allow-unsigned-extensions`
Environment	`HARDCHARGER_ALLOW_UNSIGNED_EXTENSIONS`
YAML	`allow_unsigned_extensions: …`
Type	boolean
Default	`false`

`init_sql_commands`

SQL run at startup (before the file)


Flag	`--init-sql-commands <value>`
Environment	`HARDCHARGER_INIT_SQL_COMMANDS`
YAML	`init_sql_commands: …`
Type	string
Default	`(empty)`

`init_sql_commands_file`

SQL file run at startup.


Flag	`--init-sql-commands-file <value>`
Environment	`HARDCHARGER_INIT_SQL_COMMANDS_FILE`
YAML	`init_sql_commands_file: …`
Type	string
Default	`(empty)`

`default_catalog`

The catalog every new session starts in, unless the client’s session options name one (checked after the init SQL: the server refuses to start if it isn’t attached). Unset, with default_schema unset too, an init SQL that ends in USE x or USE x.y sets where sessions start; else they start in the database’s catalog. Under access control a user who may not see it starts where they would without it.


Flag	`--default-catalog <value>`
Environment	`HARDCHARGER_DEFAULT_CATALOG`
YAML	`default_catalog: …`
Type	string
Default	`(empty)`

`default_schema`

The schema every new session starts in, in default_catalog (or, without it, in the database’s catalog), unless the client’s session options name one; the server refuses to start if it doesn’t exist.


Flag	`--default-schema <value>`
Environment	`HARDCHARGER_DEFAULT_SCHEMA`
YAML	`default_schema: …`
Type	string
Default	`(empty)`

`result_batch_rows`

Most rows per Arrow batch in a result.


Flag	`--result-batch-rows <n>`
Environment	`HARDCHARGER_RESULT_BATCH_ROWS`
YAML	`result_batch_rows: …`
Type	integer
Default	`122880`

Authentication

`admin_username`

The administrator’s user name.


Flag	`--admin-username <value>`
Environment	`HARDCHARGER_ADMIN_USERNAME`
YAML	`admin_username: …`
Type	string
Default	`hardcharger`

`admin_password`

The administrator’s password (prefer the environment variable)


Flag	`--admin-password <value>`
Environment	`HARDCHARGER_ADMIN_PASSWORD`
YAML	`admin_password: …`
Type	string
Default	`(empty)`

`secret_key`

Key that signs access tokens; share it across replicas.


Flag	`--secret-key <value>`
Environment	`HARDCHARGER_SECRET_KEY`
YAML	`secret_key: …`
Type	string
Default	`(empty)`

`token_lifetime_seconds`

Access token lifetime.


Flag	`--token-lifetime-seconds <n>`
Environment	`HARDCHARGER_TOKEN_LIFETIME_SECONDS`
YAML	`token_lifetime_seconds: …`
Type	integer
Default	`86400`

`allow_cross_instance_tokens`

Accept tokens issued by other replicas.


Flag	`--allow-cross-instance-tokens`
Environment	`HARDCHARGER_ALLOW_CROSS_INSTANCE_TOKENS`
YAML	`allow_cross_instance_tokens: …`
Type	boolean
Default	`false`

`token_signature_verify_cert_path`

PEM key or certificate that verifies sign-in tokens.


Flag	`--token-signature-verify-cert-path <value>`
Environment	`HARDCHARGER_TOKEN_SIGNATURE_VERIFY_CERT_PATH`
YAML	`token_signature_verify_cert_path: …`
Type	string
Default	`(empty)`

`token_allowed_issuer`

Required issuer of sign-in tokens.


Flag	`--token-allowed-issuer <value>`
Environment	`HARDCHARGER_TOKEN_ALLOWED_ISSUER`
YAML	`token_allowed_issuer: …`
Type	string
Default	`(empty)`

`token_allowed_audience`

Required audience of sign-in tokens.


Flag	`--token-allowed-audience <value>`
Environment	`HARDCHARGER_TOKEN_ALLOWED_AUDIENCE`
YAML	`token_allowed_audience: …`
Type	string
Default	`(empty)`

`token_default_role`

Role for sign-in tokens without one.


Flag	`--token-default-role <value>`
Environment	`HARDCHARGER_TOKEN_DEFAULT_ROLE`
YAML	`token_default_role: …`
Type	string
Default	`(empty)`

`token_groups_claim`

Sign-in token claim listing the user’s identity-provider groups.


Flag	`--token-groups-claim <value>`
Environment	`HARDCHARGER_TOKEN_GROUPS_CLAIM`
YAML	`token_groups_claim: …`
Type	string
Default	`groups`

`token_authorized_emails`

Users a sign-in token may name (globs, case-insensitive; *: anyone)


Flag	`--token-authorized-emails <a,b,...>`
Environment	`HARDCHARGER_TOKEN_AUTHORIZED_EMAILS`
YAML	`token_authorized_emails: …`
Type	list
Default	`*`

`token_jwks_uri`

JWKS of the identity provider whose ID tokens sign users in.


Flag	`--token-jwks-uri <value>`
Environment	`HARDCHARGER_TOKEN_JWKS_URI`
YAML	`token_jwks_uri: …`
Type	string
Default	`(empty)`

`token_auto_provision_users`

Under access control, a verified sign-in token from token_auto_provision_issuer whose user the store lacks creates it on first sign-in (no password, no grants; the token’s role in its provisioned_role attribute, readonly staying readonly); admin tokens and existing users (a disabled one stays disabled) are unchanged.


Flag	`--token-auto-provision-users`
Environment	`HARDCHARGER_TOKEN_AUTO_PROVISION_USERS`
YAML	`token_auto_provision_users: …`
Type	boolean
Default	`false`

`token_auto_provision_issuer`

The issuer (iss) whose sign-in tokens token_auto_provision_users provisions users for (default: token_allowed_issuer)


Flag	`--token-auto-provision-issuer <value>`
Environment	`HARDCHARGER_TOKEN_AUTO_PROVISION_ISSUER`
YAML	`token_auto_provision_issuer: …`
Type	string
Default	`(empty)`

`oauth_client_id`

OAuth client id; set, browser sign-in is offered (Warp SQL oauth_browser)


Flag	`--oauth-client-id <value>`
Environment	`HARDCHARGER_OAUTH_CLIENT_ID`
YAML	`oauth_client_id: …`
Type	string
Default	`(empty)`

`oauth_client_secret`

OAuth client secret (prefer the environment variable)


Flag	`--oauth-client-secret <value>`
Environment	`HARDCHARGER_OAUTH_CLIENT_SECRET`
YAML	`oauth_client_secret: …`
Type	string
Default	`(empty)`

`oauth_scopes`

OAuth scopes requested.


Flag	`--oauth-scopes <value>`
Environment	`HARDCHARGER_OAUTH_SCOPES`
YAML	`oauth_scopes: …`
Type	string
Default	`openid profile email`

`oauth_base_url`

The server’s public URL, for the redirect URI (default http(s)://localhost:<port>)


Flag	`--oauth-base-url <value>`
Environment	`HARDCHARGER_OAUTH_BASE_URL`
YAML	`oauth_base_url: …`
Type	string
Default	`(empty)`

`oauth_redirect_uri`

Redirect URI registered with the provider (default <base url>/warp/v1/auth/oauth/callback)


Flag	`--oauth-redirect-uri <value>`
Environment	`HARDCHARGER_OAUTH_REDIRECT_URI`
YAML	`oauth_redirect_uri: …`
Type	string
Default	`(empty)`

`oauth_instance_id`

Prefix of the OAuth state, for a shared callback proxy.


Flag	`--oauth-instance-id <value>`
Environment	`HARDCHARGER_OAUTH_INSTANCE_ID`
YAML	`oauth_instance_id: …`
Type	string
Default	`(empty)`

`oauth_provider_name`

The identity provider’s name for people (“Sign in with <name>”)


Flag	`--oauth-provider-name <value>`
Environment	`HARDCHARGER_OAUTH_PROVIDER_NAME`
YAML	`oauth_provider_name: …`
Type	string
Default	`(empty)`

`oauth_max_flows`

Browser sign-ins in progress at once.


Flag	`--oauth-max-flows <n>`
Environment	`HARDCHARGER_OAUTH_MAX_FLOWS`
YAML	`oauth_max_flows: …`
Type	integer
Default	`10000`

Sessions

`max_sessions`

Most non-admin sessions at once (0: unlimited)


Flag	`--max-sessions <n>`
Environment	`HARDCHARGER_MAX_SESSIONS`
YAML	`max_sessions: …`
Type	integer
Default	`0`

`session_idle_timeout`

A session is evicted within 5 s after this many seconds without requests (0: never), unless a statement of it is running, an ingest of it is in progress, a result of it is being read, or it holds a retained result that hasn’t expired (result_retention_seconds)


Flag	`--session-idle-timeout <n>`
Environment	`HARDCHARGER_SESSION_IDLE_TIMEOUT`
YAML	`session_idle_timeout: …`
Type	integer
Default	`900`

`result_retention_seconds`

Seconds a retained result (resumable, readable again) is kept after its statement ends, from 1 to 2592000 (30 days); its statement document’s expires_at says until when.


Flag	`--result-retention-seconds <n>`
Environment	`HARDCHARGER_RESULT_RETENTION_SECONDS`
YAML	`result_retention_seconds: …`
Type	integer
Default	`3600`

Statements

`query_timeout_seconds`

Default statement timeout (0: none)


Flag	`--query-timeout-seconds <n>`
Environment	`HARDCHARGER_QUERY_TIMEOUT_SECONDS`
YAML	`query_timeout_seconds: …`
Type	integer
Default	`0`

`print_queries`

Log every statement.


Flag	`--print-queries`
Environment	`HARDCHARGER_PRINT_QUERIES`
YAML	`print_queries: …`
Type	boolean
Default	`true`

Access control

`rbac_store_uri`

Turn on role-based access control, with users, roles and grants kept in this PostgreSQL database (postgresql://user:password@host/db or ‘host=… dbname=…’), which every replica of a cluster names; or, for development or a server that will only ever run one replica, in a DuckDB file of its own (duckdb:/path/to/rbac.duckdb, or a path ending in .duckdb), which one server alone may open. Use PostgreSQL in production.


Flag	`--rbac-store-uri <value>`
Environment	`HARDCHARGER_RBAC_STORE_URI`
YAML	`rbac_store_uri: …`
Type	string
Default	`(empty)`

`rbac_opa_url`

Also ask this Open Policy Agent decision URL about every store user’s session and statement; only {“result”: true} lets them run.


Flag	`--rbac-opa-url <value>`
Environment	`HARDCHARGER_RBAC_OPA_URL`
YAML	`rbac_opa_url: …`
Type	string
Default	`(empty)`

`rbac_opa_timeout_ms`

How long to wait for the policy service (no answer refuses)


Flag	`--rbac-opa-timeout-ms <n>`
Environment	`HARDCHARGER_RBAC_OPA_TIMEOUT_MS`
YAML	`rbac_opa_timeout_ms: …`
Type	integer
Default	`2000`

`rbac_store_timeout_seconds`

The longest one access-control store round trip may take, from 1 to 300: a store that does not answer in time fails the statement that needed it (access control store unavailable: timed out after N s) and what it was doing is rolled back. For PostgreSQL it also sets libpq’s connect_timeout, TCP keepalives, tcp_user_timeout and the session’s statement_timeout, each unless the connection string sets it.


Flag	`--rbac-store-timeout-seconds <n>`
Environment	`HARDCHARGER_RBAC_STORE_TIMEOUT_SECONDS`
YAML	`rbac_store_timeout_seconds: …`
Type	integer
Default	`10`

`rbac_max_snapshot_age_seconds`

While the store does not answer, sign-ins and statements go on with the last users, roles and grants it gave (a warning is logged, and hardcharger_rbac_snapshot_age_seconds says how old they are); past this many seconds every principal but the administrator is refused until it answers again (fail closed). 0: no limit (stay available)


Flag	`--rbac-max-snapshot-age-seconds <n>`
Environment	`HARDCHARGER_RBAC_MAX_SNAPSHOT_AGE_SECONDS`
YAML	`rbac_max_snapshot_age_seconds: …`
Type	integer
Default	`0`

`rbac_store_shared`

Let clusters with different cluster_ids share one store, and with it their users, roles and grants (grants name catalogs, so a grant on one cluster’s catalog applies to another’s catalog of that name). Off: the store records the first cluster_id that opens it and refuses any other.


Flag	`--rbac-store-shared`
Environment	`HARDCHARGER_RBAC_STORE_SHARED`
YAML	`rbac_store_shared: …`
Type	boolean
Default	`false`

`audit_chain_key`

Key that seals access-control audit records into a tamper-evident chain (HMAC-SHA256; unset: SHA-256); –verify-audit-log FILE checks a JSON log.


Flag	`--audit-chain-key <value>`
Environment	`HARDCHARGER_AUDIT_CHAIN_KEY`
YAML	`audit_chain_key: …`
Type	string
Default	`(empty)`

Statement queue

`max_concurrent_statements`

Statements that run at once; more wait in a queue (0: no queue)


Flag	`--max-concurrent-statements <n>`
Environment	`HARDCHARGER_MAX_CONCURRENT_STATEMENTS`
YAML	`max_concurrent_statements: …`
Type	integer
Default	`0`

`max_queued_statements`

Statements that may wait (-1: 8 x concurrency; 0: unbounded)


Flag	`--max-queued-statements <n>`
Environment	`HARDCHARGER_MAX_QUEUED_STATEMENTS`
YAML	`max_queued_statements: …`
Type	integer
Default	`-1`

`max_queue_wait`

Seconds a statement may wait (-1: 300; 0: forever)


Flag	`--max-queue-wait <n>`
Environment	`HARDCHARGER_MAX_QUEUE_WAIT`
YAML	`max_queue_wait: …`
Type	integer
Default	`-1`

`admin_bypass_queue_default`

Admin sessions skip the queue unless they SET hardcharger.bypass_queue = false.


Flag	`--admin-bypass-queue-default`
Environment	`HARDCHARGER_ADMIN_BYPASS_QUEUE_DEFAULT`
YAML	`admin_bypass_queue_default: …`
Type	boolean
Default	`true`

Guards

`block_sensitive_paths`

Keep credential and system files from every statement, admins’ included.


Flag	`--block-sensitive-paths`
Environment	`HARDCHARGER_BLOCK_SENSITIVE_PATHS`
YAML	`block_sensitive_paths: …`
Type	boolean
Default	`true`

`sensitive_paths`

More paths no statement may open, list or write (comma-separated)


Flag	`--sensitive-paths <a,b,...>`
Environment	`HARDCHARGER_SENSITIVE_PATHS`
YAML	`sensitive_paths: …`
Type	list
Default	`(empty)`

`block_unredacted_secrets`

Refuse SET allow_unredacted_secrets, even for admins.


Flag	`--block-unredacted-secrets`
Environment	`HARDCHARGER_BLOCK_UNREDACTED_SECRETS`
YAML	`block_unredacted_secrets: …`
Type	boolean
Default	`true`

Cluster

`cluster_id`

UUID shared by the replicas of one cluster.


Flag	`--cluster-id <value>`
Environment	`HARDCHARGER_CLUSTER_ID`
YAML	`cluster_id: …`
Type	string
Default	`(empty)`

Operations

`log_level`

Debug, info, warning or error.


Flag	`--log-level <value>`
Environment	`HARDCHARGER_LOG_LEVEL`
YAML	`log_level: …`
Type	string
Default	`info`

`log_format`

Text or json.


Flag	`--log-format <value>`
Environment	`HARDCHARGER_LOG_FORMAT`
YAML	`log_format: …`
Type	string
Default	`text`

`log_file`

Log destination (empty: stderr; -: stdout)


Flag	`--log-file <value>`
Environment	`HARDCHARGER_LOG_FILE`
YAML	`log_file: …`
Type	string
Default	`(empty)`

`log_emoji`

Mark text log lines’ levels with emoji: auto (only on a UTF-8 terminal), always or never; JSON lines never have them.


Flag	`--log-emoji <value>`
Environment	`HARDCHARGER_LOG_EMOJI`
YAML	`log_emoji: …`
Type	string
Default	`auto`

`banner`

Print the startup banner (versions and URLs) in a text log; –no-banner or HARDCHARGER_NO_BANNER=true turns it off.


Flag	`--banner`
Environment	`HARDCHARGER_BANNER`
YAML	`banner: …`
Type	boolean
Default	`true`

`query_log_level`

Level of statement log lines.


Flag	`--query-log-level <value>`
Environment	`HARDCHARGER_QUERY_LOG_LEVEL`
YAML	`query_log_level: …`
Type	string
Default	`info`

`auth_log_level`

Level of sign-in log lines.


Flag	`--auth-log-level <value>`
Environment	`HARDCHARGER_AUTH_LOG_LEVEL`
YAML	`auth_log_level: …`
Type	string
Default	`info`

`session_log_level`

Level of session log lines.


Flag	`--session-log-level <value>`
Environment	`HARDCHARGER_SESSION_LOG_LEVEL`
YAML	`session_log_level: …`
Type	string
Default	`info`

`graceful_shutdown`

On the first stop signal, let running work finish (false: stop at once)


Flag	`--graceful-shutdown`
Environment	`HARDCHARGER_GRACEFUL_SHUTDOWN`
YAML	`graceful_shutdown: …`
Type	boolean
Default	`true`

`shutdown_grace_period_seconds`

How long a graceful shutdown waits for running work (0: forever)


Flag	`--shutdown-grace-period-seconds <n>`
Environment	`HARDCHARGER_SHUTDOWN_GRACE_PERIOD_SECONDS`
YAML	`shutdown_grace_period_seconds: …`
Type	integer
Default	`300`

`health_check_query`

SQL the health check runs.


Flag	`--health-check-query <value>`
Environment	`HARDCHARGER_HEALTH_CHECK_QUERY`
YAML	`health_check_query: …`
Type	string
Default	`SELECT 1`

`health_check_interval_seconds`

Seconds between health checks.


Flag	`--health-check-interval-seconds <n>`
Environment	`HARDCHARGER_HEALTH_CHECK_INTERVAL_SECONDS`
YAML	`health_check_interval_seconds: …`
Type	integer
Default	`5`

`health_check_staleness_seconds`

Age at which the last check no longer counts (0: 3 x interval)


Flag	`--health-check-staleness-seconds <n>`
Environment	`HARDCHARGER_HEALTH_CHECK_STALENESS_SECONDS`
YAML	`health_check_staleness_seconds: …`
Type	integer
Default	`0`

`cors_origins`

Browser origins allowed to call the server.


Flag	`--cors-origins <a,b,...>`
Environment	`HARDCHARGER_CORS_ORIGINS`
YAML	`cors_origins: …`
Type	list
Default	`(empty)`

Instrumentation

`enable_instrumentation`

Record sessions, statements and executions in SQL tables.


Flag	`--enable-instrumentation`
Environment	`HARDCHARGER_ENABLE_INSTRUMENTATION`
YAML	`enable_instrumentation: …`
Type	boolean
Default	`false`

`instrumentation_db_path`

DuckDB file for the instrumentation tables (default: next to the database), for development or a single server.


Flag	`--instrumentation-db-path <value>`
Environment	`HARDCHARGER_INSTRUMENTATION_DB_PATH`
YAML	`instrumentation_db_path: …`
Type	string
Default	`(empty)`

`instrumentation_catalog`

Keep them instead in this PostgreSQL catalog, which the init SQL attaches and several servers may share (DuckLake and other catalogs are refused). Use PostgreSQL in production.


Flag	`--instrumentation-catalog <value>`
Environment	`HARDCHARGER_INSTRUMENTATION_CATALOG`
YAML	`instrumentation_catalog: …`
Type	string
Default	`(empty)`

`instrumentation_schema`

Schema for them in that catalog.


Flag	`--instrumentation-schema <value>`
Environment	`HARDCHARGER_INSTRUMENTATION_SCHEMA`
YAML	`instrumentation_schema: …`
Type	string
Default	`main`

Catalog logging

`enable_catalog_logging`

Also write every log line to a logs table.


Flag	`--enable-catalog-logging`
Environment	`HARDCHARGER_ENABLE_CATALOG_LOGGING`
YAML	`enable_catalog_logging: …`
Type	boolean
Default	`false`

`log_catalog_db_path`

DuckDB file for the logs table (default: next to the database)


Flag	`--log-catalog-db-path <value>`
Environment	`HARDCHARGER_LOG_CATALOG_DB_PATH`
YAML	`log_catalog_db_path: …`
Type	string
Default	`(empty)`

`log_catalog`

An attached catalog (DuckLake, PostgreSQL) for it instead.


Flag	`--log-catalog <value>`
Environment	`HARDCHARGER_LOG_CATALOG`
YAML	`log_catalog: …`
Type	string
Default	`(empty)`

`log_schema`

Schema for it in that catalog.


Flag	`--log-schema <value>`
Environment	`HARDCHARGER_LOG_SCHEMA`
YAML	`log_schema: …`
Type	string
Default	`main`

`instance_tag`

JSON object recorded with this instance.


Flag	`--instance-tag <value>`
Environment	`HARDCHARGER_INSTANCE_TAG`
YAML	`instance_tag: …`
Type	string
Default	`(empty)`

`capture_query_profile`

Record DuckDB’s query profile with each execution: off, standard or detailed.


Flag	`--capture-query-profile <value>`
Environment	`HARDCHARGER_CAPTURE_QUERY_PROFILE`
YAML	`capture_query_profile: …`
Type	string
Default	`off`

Metrics

`enable_metrics`

Collect runtime metrics and serve /metrics (default: on when metrics_port or metrics_bind_address is set)


Flag	`--enable-metrics`
Environment	`HARDCHARGER_ENABLE_METRICS`
YAML	`enable_metrics: …`
Type	boolean
Default	`false`

`metrics_port`

Port serving /metrics (0: none, metrics in SQL only); setting it turns metrics on.


Flag	`--metrics-port <n>`
Environment	`HARDCHARGER_METRICS_PORT`
YAML	`metrics_port: …`
Type	integer
Default	`9091`

`metrics_bind_address`

Address /metrics listens on; setting it turns metrics on.


Flag	`--metrics-bind-address <value>`
Environment	`HARDCHARGER_METRICS_BIND_ADDRESS`
YAML	`metrics_bind_address: …`
Type	string
Default	`0.0.0.0`