QuestDB's configuration can be set either:

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

About environment variables#

All options in the configuration file can be overridden using environment variables with the syntax:


Where <KEY_OF_THE_PROPERTY> is equal to the key name in uppercase characters, with all occurrences of . replaced with _. For example, the key shared.worker.count becomes QDB_SHARED_WORKER_COUNT.

If a key is set in both the server.conf file and via an environment variable, the latter will take precedence and the value in server.conf will be ignored.


Customizing the worker count via server.conf
Same as above using an environment variable

After changing the configuration, you will need to restart QuestDB in order for your modifications to take effect


Configuration file#

Logs can be controlled via a dedicated file, for example:

# list of configured writers
# file writer
# stdout

QuestDB will look for /qlog.conf on the classpath unless this name is overridden via a "system" property: -DquestdbLog=/something_else.conf.

Environment variables#

Values in that file can be overridden with environment variables. For example:

Value set in qlog.conf
Overriding the value using an environment variable


QuestDB logging can be quickly forced globally to DEBUG via either providing the java option -Debug or setting the environment variable QDB_DEBUG=true.

Available keys and default values#

Shared worker#

shared.worker.count2Number of worker threads shared across the application. Increasing this number will increase parallelism in the application at the expense of CPU resources.
shared.worker.affinityComma-delimited list of CPU ids, one per thread specified in "shared.worker.count". By default, threads have no CPU affinity.
shared.worker.haltOnErrorfalseToggle whether worker should stop on error.

Minimal HTTP server#

This server is useful for doing health checks on QuestDB over http. It will respond to every request with HTTP 200 unless QuestDB process dies.

http.min.enabledtrueEnable Minimal HTTP server.
http.min.bind.to0.0.0.0:9003IPv4 address and port of the server. 0 means it will bind to all network interfaces. Otherwise IP address must by one of the existing network adaptors

HTTP server#

http.enabledtrueEnable HTTP server.
http.connection.pool.initial.capacity16Initial size of pool of reusable objects that hold connection state. The pool should be configured to maximum realistic load so that it does not resize at runtime.
http.connection.string.pool.capacity128Initial size of the string pool shared by HttpHeaderParser and HttpMultipartContentParser.
http.multipart.header.buffer.size512HeaderParser buffer size in bytes.
http.multipart.idle.spin.count10_000How long the code accumulates incoming data chunks for column and delimiter analysis.
http.receive.buffer.size1mSize of receive buffer.
http.request.header.buffer.size64kSize of internal buffer allocated for HTTP request headers. The value is rounded up to the nearest power of 2. When HTTP request contains headers that exceed the buffer size server will disconnect the client with HTTP error in server log.
http.response.header.buffer.size32kSize of the internal response buffer. The value will be rounded up to the nearest power of 2. The buffer size should be large enough to accommodate max size of server response headers.
http.worker.count0Number of threads in private worker pool. When value is 0, HTTP server will be using shared worker pool of the server. Values above 0 switch on private pool.
http.worker.affinitycomma separated list of CPU core indexes. The number of items of this list must be equal to the worker count.
http.worker.haltOnErrorfalseFlag that indicates if worker thread must shutdown on unhandled error. We strongly recommend not to change default value.
http.send.buffer.size2mSize of the internal send buffer. The larger than buffer size the fewer IO interruptions server is making at expense of memory usage per connection. There is a limit of send buffer size after which increasing it stops being useful in terms of performance. 2MB seems to be optimal value.
http.static.index.file.nameindex.htmlName of index file for the Web Console.
http.frozen.clockfalseSets the clock to always return zero. This configuration parameter is used for internal testing.
http.allow.deflate.before.sendfalseEnable / disable Gzip compression of outgoing data.
http.keep-alive.timeout5Used together with http.keep-alive.max to set the value of HTTP Keep-Alive response header. This instructs browser to keep TCP connection open. Has to be 0 when http.version is set to HTTP/1.0.
http.keep-alive.max10_000See http.keep-alive.timeout. Has to be 0 when http.version is set to HTTP/1.0.
http.static.pubic.directorypublicThe name of directory for public web site. number of simultaneous TCP connection to the HTTP server. The rationale of the value is to control server memory consumption. IO event queue capacity (EPoll, KQqueu, Select). Size of these queues must be larger than IO queue of HTTP server. Size of this queue must be larger than Queue size smaller than active connection max will substantially slow down the server by increasing wait times. Queue larger than connection max reduces wait time to 0. connection idle timeout in milliseconds. Connection is closed by HTTP server when this timeout lapses. queue size. This is also related to in a way that sizes larger than connection max remove any waiting. argument value for listen() call. send buffer size on each TCP socket. If value is -1 socket send buffer remains unchanged from OS default. receive buffer size on each TCP socket. If value is -1 socket receive buffer remains unchanged from OS default. of date adaptor pool. This should be set to the anticipated maximum number of DATE fields a text input can have. The pool is assigned to connection state and is reused alongside of connection state object.
http.text.json.cache.limit16384JSON parser cache limit. Cache is used to compose JSON elements that have been broken up by TCP protocol. This value limits the maximum length of individual tag or tag value.
http.text.json.cache.size8192Initial size of JSON parser cache. The value must not exceed http.text.json.cache.limit and should be set to avoid cache resizes at runtime.
http.text.max.required.delimiter.stddev0.1222dThe maximum standard deviation value for the algorithm that calculates text file delimiter. Usually when text parser cannot recognise the delimiter it will log the calculated and maximum standard deviation for the delimiter candidate.
http.text.max.required.line.length.stddev0.8Maximum standard deviation value for the algorithm that classifies input as text or binary. For the values above configured stddev input will be considered binary.
http.text.metadata.string.pool.capacity128The initial size of pool for objects that wrap individual elements of metadata JSON, such as column names, date pattern strings and locale values.
http.text.roll.buffer.limit4mThe limit of text roll buffer. See http.text.roll.buffer.size for description.
http.text.roll.buffer.size1024Roll buffer is a structure in text parser that holds a copy of a line that has been broken up by TCP. The size should be set to the maximum length of text line in text input.
http.text.lexer.string.pool.capacity64The initial capacity of string fool, which wraps STRING column types in text input. The value should correspond to the maximum anticipated number of STRING columns in text input.
http.text.timestamp.adapter.pool.capacity64Size of timestamp adaptor pool. This should be set to the anticipated maximum number of TIMESTAMP fields a text input can have. The pool is assigned to connection state and is reused alongside of connection state object
http.text.utf8.sink.size4096Initial size of UTF-8 adaptor sink. The value should correspond the maximum individual field value length in text input
http.json.query.connection.check.frequency1_000_000The value to throttle check if client socket has been disconnected. It is not recommended to change this value
http.json.query.float.scale10The scale value of string representation of FLOAT values
http.json.query.double.scale12The scale value of string representation of DOUBLE values
http.bind.to0.0.0.0:9000IP address and port of HTTP server. 0 means that http server will bind to all network interfaces. You can specify IP address of any individual network interface on your system HTTP read only mode when true, which disables commands which modify the data or data structure. the number of response rows over HTTP. to turn on terminating SQL processing if the HTTP connection is closed, the mechanism affects performance so the connection is only checked after calls are made to the check method. The mechanism also reads from the input stream and discards it since some HTTP clients send this as a keep alive in between requests, denotes the size of the buffer for this.
http.server.keep.alivetrueIf set to false, the server will disconnect the client after completion of each request.
http.versionHTTP/1.1Protocol version, other supported value is HTTP/1.0.

Cairo engine#

cairo.sql.copy.rootnullInput root directory for backups.
cairo.sql.backup.rootnullOutput root directory for backups.
cairo.sql.backup.dir.datetime.formatnullDate format for backup directory.
cairo.sql.backup.dir.tmp.nametmpName of tmp directory used during backup.
cairo.sql.backup.mkdir.mode509Permission used when creating backup directories.
cairo.rootdbDirectory for storing db tables and metadata. This directory is inside the server root directory provided at startup.
cairo.commit.modenosyncHow changes to table are flushed to disk upon commit. Choices: nosync, async (flush call schedules update, returns immediately), sync (waits for flush to complete). of types table creation or insertion will be attempted. of map used. Options: fast (speed at the expense of storage), compact.
cairo.default.symbol.cache.flagfalseWhen true, symbol values will be cached on Java heap.
cairo.default.symbol.capacity256Specifies approximate capacity for SYMBOL columns. It should be equal to number of unique symbol values stored in the table and getting this value badly wrong will cause performance degradation. Must be power of 2.
cairo.file.operation.retry.count30Number of attempts to open files.
cairo.idle.check.interval300000Frequency of writer maintenance job in milliseconds.
cairo.inactive.reader.ttl-120000Frequency of reader pool checks for inactive readers in milliseconds.
cairo.inactive.writer.ttl-600000Frequency of writer pool checks for inactive writers in milliseconds.
cairo.index.value.block.size256Approximation of number of rows for a single index key, must be power of 2.
cairo.max.swap.file.count30Number of attempts to open swap files.
cairo.mkdir.mode509File permission mode for new directories.
cairo.parallel.index.threshold100000Minimum number of rows before allowing use of parallel indexation.
cairo.reader.pool.max.segments5Number of attempts to get TableReader.
cairo.spin.lock.timeout1_000_000Timeout when attempting to get BitmapIndexReaders in microseconds.
cairo.cache.rows16Number of rows for the query cache.
cairo.cache.blocks4Number of blocks for the query cache. of the CharacterStore. of the CharacterSequence pool.
cairo.column.pool.capacity4096Size of the Column pool in the SqlCompiler. factor for CompactMaps.
cairo.expression.pool.capacity8192Size of the ExpressionNode pool in SqlCompiler. factor for all FastMaps.
cairo.sql.join.context.pool.capacity64Size of the JoinContext pool in SqlCompiler.
cairo.lexer.pool.capacity2048Size of FloatingSequence pool in GenericLexer. capacity in FastMap and CompactMap.^31Number of map resizes in FastMap and CompactMap before a resource limit exception is thrown, each resize doubles the previous size. page size for FastMap and CompactMap.^31Memory max pages for CompactMap.
cairo.model.pool.capacity1024Size of the QueryModel pool in the SqlCompiler. page size for storing keys in LongTreeChain.
cairo.sql.sort.key.max.pages2^31Max number of pages for storing keys in LongTreeChain before a resource limit exception is thrown. page size for storing values in LongTreeChain.
cairo.sql.sort.light.value.max.pages2^31Max pages for storing values in LongTreeChain. page size of the slave chain in full hash joins.
cairo.sql.hash.join.value.max.pages2^31Max pages of the slave chain in full hash joins. of rows for LATEST BY. page size of the slave chain in light hash joins.
cairo.sql.hash.join.light.value.max.pages2^31Max pages of the slave chain in light hash joins. page size of file storing values in SortedRecordCursorFactory.
cairo.sql.sort.value.max.pages2^31Max pages of file storing values in SortedRecordCursorFactory. await timeout in nanos for stealing indexing work from other threads.
cairo.parallel.indexing.enabledtrueAllows parallel indexation. Works in conjunction with cairo.parallel.index.threshold. page size for JoinMetadata file.
cairo.sql.join.metadata.max.resizes2^31Number of map resizes in JoinMetadata before a resource limit exception is thrown, each resize doubles the previous size.
cairo.sql.analytic.column.pool.capacity64Size of AnalyticColumn pool in SqlParser.
cairo.sql.create.table.model.pool.capacity16Size of CreateTableModel pool in SqlParser.
cairo.sql.column.cast.model.pool.capacity16Size of CreateTableModel pool in SqlParser.
cairo.sql.rename.table.model.pool.capacity16Size of RenameTableModel pool in SqlParser.
cairo.sql.with.clause.model.pool.capacity128Size of WithClauseModel pool in SqlParser.
cairo.sql.insert.model.pool.capacity64Size of InsertModel pool in SqlParser.
cairo.sql.copy.model.pool.capacity32Size of CopyModel pool in SqlParser.
cairo.sql.copy.buffer.size2mSize of buffer used when copying tables.
cairo.sql.copy.formats.file/text_loader.jsonName of file with user's set of date and timestamp formats.

Postgres wire protocol#


InfluxDB line protocol (UDP)#

line.udp.join""Multicast address receiver joins. This values is ignored when receiver is in "unicast" mode.""IP address of the network interface to bind listener to and port. By default UDP receiver listens on all network interfaces.
line.udp.commit.rate1000000For packet bursts the number of continuously received messages after which receiver will force commit. Receiver will commit irrespective of this parameter when there are no messages.
line.udp.msg.buffer.size2048Buffer used to receive single message. This value should be roughly equal to your MTU size.
line.udp.msg.count10000Only for Linux. On Linix QuestDB will use recvmmsg(). This is the max number of messages to receive at once.
line.udp.receive.buffer.size8388608UDP socket buffer size. Larger size of the buffer will help reduce message loss during bursts.
line.udp.enabledtrueFlag to enable or disable UDP receiver.
line.udp.own.threadfalseWhen "true" UDP receiver will use its own thread and busy spin that for performance reasons. "false" makes receiver use worker threads that do everything else in QuestDB.
line.udp.own.thread.affinity-1-1 does not set thread affinity. OS will schedule thread and it will be liable to run on random cores and jump between the. 0 or higher pins thread to give core. This property is only valid when UDP receiver uses own thread.
line.udp.unicastfalseWhen true, UDP will me unicast. Otherwise multicast.
line.udp.timestampnInput timestamp resolution. Possible values are n, u, ms, s and h.
line.udp.commit.mode"nosync"Commit durability. Available values are "nosync", "sync" and "async".

InfluxDB line protocol (TCP)#

line.tcp.auth.db.pathPath which points to the authentication db file.
line.tcp.enabledtrueEnable or disable line protocol over TCP. address of the network interface to bind listener to and port. By default TCP receiver listens on all network interfaces.
line.tcp.timestampnInput timestamp resolution. Possible values are n, u, ms, s and h.
line.tcp.msg.buffer.size2048Size of the buffer read from queue. Maximum size of write request, regardless of the number of measurements.
line.tcp.max.measurement.size2048Maximum size of any measurement.
line.tcp.writer.queue.size128Size of the queue between network IO and writer jobs. Each queue entry represents a measurement.
line.tcp.worker.count0Number of dedicated worker threads assigned to write data. When 0, the writer jobs will use the shared pool.
line.tcp.worker.affinity0Comma-separated list of thread numbers which should be pinned for line protocol ingestion over TCP. Example line.tcp.worker.affinity=1,3,4.

Load balancing#

line.tcp.n.updates.per.load.balance10000Maximum number of updates in a given table since the last load balancing before triggering a new load balancing job.
line.tcp.max.load.ratio1.9Maximum load ratio (max loaded worker/min loaded worker) before QuestDB will attempt to rebalance the load between the writer workers.
line.tcp.max.uncommitted.rows1000Maximum number of uncommitted rows, note that rows will always be committed if they have been received ms ago. amount of time in between maintenance jobs, these will commit any uncommited data.


QuestDB sends telemetry data with information about usage which helps us improve the product over time. We do not collect any personally-identifying information, and we do not share any of this data with third parties.

telemetry.enabledtrueEnable / disable anonymous usage metrics collection.