Configuration

This page describes methods for configuring QuestDB server settings.

Configuration can be set using:

• The server.conf configuration file available in the root directory
• Environment variables
• Command-line options for startup behavior such as root directory, service tags, and web console redeployment

When a key is absent from both the config file and the environment variables, the default value is used.

note

For Windows users

When entering path values, use either \\ or / instead of the native path separator char \.

• 👍 C:\\path\\to\\file\\path
• 👍 C:/path/to/file
• 👎 C:\path\to\file

The single backslash is interpreted as an escape sequence start within Java properties.

Environment variables

All settings in the configuration file can be set or overridden using environment variables. If a key is set in both the server.conf file and via an environment variable, the environment variable will take precedence and the value in the server configuration file will be ignored.

To make these configuration settings available to QuestDB via environment variables, they must be in the following format:

QDB_<KEY_OF_THE_PROPERTY>

Where <KEY_OF_THE_PROPERTY> is equal to the configuration key name. To properly format a server.conf key as an environment variable it must have:

1. QDB_ prefix
2. uppercase characters
3. all . period characters replaced with _ underscore

For example, the server configuration key for query timeout must be passed as described below:

server.conf key	env var
query.timeout	QDB_QUERY_TIMEOUT

note

QuestDB applies these configuration changes on startup and a running instance must be restarted in order for configuration changes to take effect.

Examples

The following configuration property customizes the query timeout:

conf/server.conf

query.timeout=120s

Customizing the query timeout via environment variable

export QDB_QUERY_TIMEOUT=120s

Secrets from files

QuestDB supports reading sensitive configuration values from files using the _FILE suffix convention. This is useful in containerized environments like Kubernetes, where secrets are typically mounted as files rather than passed as environment variables.

When a _FILE variant is set, QuestDB reads the secret value from the specified file path. This works with both environment variables and properties in server.conf.

Usage

Environment variable:

QDB_PG_PASSWORD_FILE=/run/secrets/pg-password

Property file:

server.conf

pg.password.file=/run/secrets/pg-password

Precedence

If both a _FILE variant and the direct value are set, the _FILE variant takes precedence. For example, if both QDB_PG_PASSWORD_FILE and QDB_PG_PASSWORD are set, the value is read from the file.

File requirements

Secret files must meet the following requirements:

• Maximum size: 64KB
• Encoding: UTF-8
• Content handling: Leading and trailing whitespace is automatically trimmed

The following paths are not allowed for security reasons:

• Paths containing .. (path traversal)
• Paths starting with /dev/, /proc/, or /sys/
• Directories (including symlinks to directories)

If a secret file is empty or contains only whitespace, QuestDB logs an advisory warning, as this may weaken authentication.

Error handling

If a secret file cannot be read at startup, QuestDB fails to start. This includes cases where the file does not exist, is too large, or the path is not allowed.

During runtime, if reload_config() cannot read a secret file, the reload fails and the previous value is retained. This ensures the server continues operating if a secret file is temporarily unavailable.

Reloading secrets

Secrets loaded from files support runtime reloading. After updating a secret file, call reload_config() to apply the new value. See Reloadable settings for details.

To verify that a secret was loaded from a file, run SHOW PARAMETERS and check the value_source column, which displays file for secrets loaded from files.

Supported properties

The following properties support the _FILE suffix:

Property	Environment variable
pg.password	QDB_PG_PASSWORD_FILE
pg.readonly.password	QDB_PG_READONLY_PASSWORD_FILE
http.password	QDB_HTTP_PASSWORD_FILE

Enterprise properties

The following additional properties are available in QuestDB Enterprise:

Property	Environment variable
acl.admin.password	QDB_ACL_ADMIN_PASSWORD_FILE
acl.oidc.tls.keystore.password	QDB_ACL_OIDC_TLS_KEYSTORE_PASSWORD_FILE
replication.object.store	QDB_REPLICATION_OBJECT_STORE_FILE
cold.storage.object.store	QDB_COLD_STORAGE_OBJECT_STORE_FILE
backup.object.store.*	QDB_BACKUP_OBJECT_STORE_*_FILE

For Kubernetes-specific examples, see the Kubernetes deployment guide.

Reloadable settings

Certain configuration settings can be reloaded without having to restart the server. To reload a setting, edit its value in the server.conf file and then run the reload_config SQL function:

Reload server configuration

SELECT reload_config();

If the value was reloaded successfully, the reload_config function returns true and a message is printed to the server log:

2025-01-02T09:52:40.833848UTC I i.q.DynamicPropServerConfiguration reloaded config option [update, key=http.net.connection.limit, old=100, new=200]

Each key has a reloadable property that indicates whether the key can be reloaded. If yes, the reload_config function can be used to reload the configuration.

All reloadable properties can be also queried from the server:

Query reloadable properties

(SHOW PARAMETERS) WHERE reloadable = true;

Command-line options

QuestDB may be started, stopped and passed configuration options from the command line. On Windows, the QuestDB server can also start an interactive session.

Options

The following sections describe the options that may be passed to QuestDB when starting the server from the command line.

Linux

./questdb.sh [start|stop|status] [-d dir] [-f] [-n] [-t tag]

macOS (Homebrew)

questdb [start|stop|status] [-d dir] [-f] [-n] [-t tag]

Windows

questdb.exe [start|stop|status|install|remove] \
  [-d dir] [-f] [-j JAVA_HOME] [-t tag]

Start

start - starts QuestDB as a service.

Option	Description
-d	Expects a dir directory value which is a folder that will be used as QuestDB's root directory. For more information and the default values, see the default root section below.
-t	Expects a tag string value which will be as a tag for the service. This option allows users to run several QuestDB services and manage them separately. If this option is omitted, the default tag will be questdb.
-f	Force re-deploying the Web Console. Without this option, the Web Console is cached and deployed only when missing.
-n	Do not respond to the HUP signal. This keeps QuestDB alive after you close the terminal window where you started it.
-j	Windows only! This option allows to specify a path to JAVA_HOME.

note

• When running multiple QuestDB services, a tag must be used to disambiguate between services for start and stop commands. There will be conflicting ports and root directories if only the tag flag is specified when starting multiple services. Each new service should have its own config file or should be started with separate port and root directory options.

• When running QuestDB as Windows service you can check status in both:

  • Windows Event Viewer - look for events with "QuestDB" source in Windows Logs | Application .
  • service log file - $dataDir\log\service-%Y-%m-%dT%H-%M-%S.txt (default is C:\Windows\System32\qdbroot\log\service-%Y-%m-%dT%H-%M-%S.txt )

Linux

./questdb.sh start [-d dir] [-f] [-n] [-t tag]

macOS (Homebrew)

questdb start [-d dir] [-f] [-n] [-t tag]

Windows

questdb.exe start [-d dir] [-f] [-j JAVA_HOME] [-t tag]

Default root directory

By default, QuestDB's root directory will be the following:

Linux

$HOME/.questdb

macOS (Homebrew)

Path on Macs with Apple Silicon (M1 or M2) chip:

/opt/homebrew/var/questdb

Path on Macs with Intel chip:

/usr/local/var/questdb

Windows

C:\Windows\System32\qdbroot

Stop

stop - stops a service.

Option	Description
-t	Expects a tag string value which to stop a service by tag. If this is omitted, the default tag will be questdb

Linux

./questdb.sh stop

macOS (Homebrew)

questdb stop

Windows

questdb.exe stop

Status

status - shows the status for a service.

Option	Description
-t	Expects a tag string value which to stop a service by tag. If this is omitted, the default will be questdb

Linux

./questdb.sh status

macOS (Homebrew)

questdb status

Windows

questdb.exe status

Install (Windows)

install - installs the Windows QuestDB service. The service will start automatically at startup.

questdb.exe install

Remove (Windows)

remove - removes the Windows QuestDB service. It will no longer start at startup.

questdb.exe remove

Interactive session (Windows)

You can start QuestDB interactively by running questdb.exe. This will launch QuestDB interactively in the active Shell window. QuestDB will be stopped when the Shell is closed.

Default root directory

When started interactively, QuestDB's root directory defaults to the current directory.

Stop

To stop, press Ctrl+C in the terminal or close it directly.

Config validation

The database startup phase checks for configuration issues, such as invalid or deprecated settings. Issues may be classified as advisories or errors. Advisory issues are logged without causing the database to stop its startup sequence: These are usually setting deprecation warnings. Configuration errors can optionally cause the database to fail its startup.

config.validation.strict

• Default: false
• Reloadable: no

When enabled, startup fails if there are configuration errors.

We recommend enabling strict validation.

Configuration reference

The full configuration reference is divided by subsystem. Each page lists every available property with its default value, whether it can be reloaded at runtime, and a description.

Parameters for specifying buffer and memory page sizes use the format n<unit>, where <unit> can be:

• m for MB
• k for kB

For example:

Setting maximum send buffer size to 2MB per TCP socket

http.net.connection.sndbuf=2m

Section	Description	Enterprise only
Cairo engine	SQL engine settings
COPY settings	CSV import and Parquet export
HTTP server	Web Console and REST API
IAM	Identity and Access Management	✓
Ingestion (ILP/HTTP)	InfluxDB Line Protocol settings
Logging & Metrics	Log levels and metrics
Materialized views	Materialized view refresh settings
Minimal HTTP server	Health check and metrics endpoint
OpenID Connect (OIDC)	OIDC integration	✓
Parallel SQL execution	Query parallelism settings
Postgres wire protocol	PostgreSQL wire protocol connections
Replication	High availability cluster replication	✓
Shared workers	Worker thread pools
Storage policy	Partition lifecycle management	✓
Telemetry	Anonymous usage telemetry
TLS encryption	TLS settings for all interfaces	✓
WAL table configurations	Write-Ahead Log settings