2. Configuration#
2.1. QuasarDB Daemon#
Every server setting can be supplied in a JSON configuration file, as a
command-line argument, or as an environment variable. Packaged installations
typically use /etc/qdb/qdbd.conf; the exact location depends on the
installation method.
The dotted config-file names in the tables below identify paths in the nested
JSON document. For example, local.limiter.memory_statistics_refresh maps to
local → limiter → memory_statistics_refresh. Use qdbd
--gen-complete-config to generate a complete configuration, including the
defaults for the installed server version. qdbd --gen-config omits settings
that have their default value. The generated complete configuration is the
authoritative inventory; the tables below document commonly configured
settings and their equivalent config-file, command-line, and
environment-variable forms.
When the same setting is supplied through more than one form, command-line arguments take precedence over the configuration file, and the configuration file takes precedence over environment variables. Invalid configuration files and invalid combinations are rejected instead of being silently ignored.
2.1.1. License#
You can set a license either by file or by putting the license key as a string directly into your configuration.
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
Path to the license file. Ensure that it is readable by the account that
runs |
|
|
|
License key as a string. Supplying a key directly can expose it through process or configuration inspection; prefer a license file where appropriate. |
2.1.2. Parallelism#
Warning
Improper parallelism settings can reduce performance.
QuasarDB has been designed for multicore architectures. Queries coming from clients are processed in parallel across multiple partitions. Each partition is a thread pool that processes one or more shards (time-based data units) in parallel.
In most instances, you want to use the unified setting that gives a “budget” to let QuasarDB pick for you the right number of partitions and threads per partitions.
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
How many cores to allocate to process queries. The default of 0 will let QuasarDB pick a number depending on the computing resources available on the computer. |
|
|
|
Number of query-processing threads in each partition. |
It’s possible to have total control over the configuration in using the partitions_count and threads_per_partition settings. Partitions are
thread pools that process queries in parallel, with each partition able to perform one storage write at a time. If these values are not 0, the
parallelism setting will be ignored and QuasarDB will use the exact configured number of partitions and threads per partition. It is strongly
advised to set partitions_count and threads_per_partition to 0 and use the parallelism setting instead, which automatically determines
optimal values based on available CPU cores.
Note
The storage layer has its own thread settings, so its threads are additional to the query-processing allocation.
2.1.3. Storage#
Config File,Command-Line Argument & Environment Variable |
Description |
|---|---|
|
Specifies which storage engine to use. Accepted values: |
|
Root directory for RocksDB data. The daemon’s built-in default is
|
|
Location to the Write-Ahead-Log (WAL) folder. Defaults to empty, which will make it a subdirectory of the root directory called “wal”. |
|
An array in the form [{“path”: “path1”, “size”: size1}, {“path”: “path2”, “size”: size2}] which specified, which directory, in order should be used for storage. When a storage exceeds capacity, older data is moved to the next storage in the list. Actual usage may exceed the size specified. Size is specified in bytes. |
|
The compaction strategy to use. By default it is “leveled”, but “universal” is also accepted. Universal improves write amplification at the cost of space amplification. |
|
When this option is set to true, writes will not go to the Write-Ahead-Log (WAL), increasing performance at the cost of durability. Writes go to the WAL by default. Use this option with caution. |
|
Size, in bytes, of the Write-Ahead-Log (WAL). The WAL is where every update gets written and protects memtables against crashes. When the WAL is full, memtables are flushed to disk. If the WAL is too small, memtables may thus be flushed before they are full, impacting write speed. However, large WALs means increased memory usage and potentially higher compaction. Your WAL should be large enough to absorbs spikes, but cannot be used to compensate for a persistence layer too slow to absorb the load or memtables being too small. See |
|
How many threads will be dedicated to writing data to disk. Write-heavy
scenarios may benefit from a higher count. Defaults to |
|
Maximum RocksDB size in bytes. |
|
A path to a local disk to be used as a persistent cache. May increase performance when data is stored in a remote disk. |
|
The maximum size of the persistent cache, in bytes. Cannot be zero if the persistent cache path is specified. |
|
If your persistent cache is on an NVME, enabling this option may increase performance. |
|
Specifies additional configuration options to fine-tune RocksDB storage behavior. |
|
A map of column-family names to advanced RocksDB column options, including block-based table options. |
|
The percentage of configured storage capacity at which QuasarDB starts
warning about low disk space. Valid values are from |
|
The interval for synchronizing the read-only RocksDB-cloud with the master database. It cannot exceed 30 minutes - half the time it takes for deleted files. |
|
A boolean value indicating whether the storage engine should create a new database if it doesn’t already exist. When set to true, the storage engine will create a new database if one with the specified name is not found. |
|
A boolean value that, when set to true, disables automatic compaction of SST files in the storage engine. Compaction is a process that merges and optimizes data files to improve storage efficiency. Disabling auto-compaction means users must manually run cluster_compact in qdbsh often. This boosts write performance but can harm read performance. |
|
A boolean value that, when set to true, prevents the storage engine from synchronizing manifest files with disk. Manifest files are used to track the state of the SST files in the storage engine. |
|
Maximum number of RocksDB informational log files to retain. The default
is |
|
An integer representing the time interval, in milliseconds, after which log files in the storage engine will be rolled. Rolling involves closing the current log file and starting a new one to manage the size of log files. |
|
An integer specifying the maximum size of log files in the storage engine, in bytes. When a log file reaches this size, it will be rolled to a new file. |
|
A boolean value indicating whether to perform extra checks for data integrity and correctness. When enabled, the storage engine will perform additional validation to catch potential errors. |
|
A boolean value indicating whether to perform extra checks on data files for integrity and correctness. Similar to paranoid_checks, this option applies specifically to data files in the storage engine. |
|
The rate limit is specified in bytes per second; a value of 0 indicates that rate limiting is disabled. This rate limit applies to the amount of I/O allocated for flushing and compaction, with flushing operations prioritized over compaction |
|
A boolean value indicating whether the database should be opened in read-only mode. When set to true, write operations will be disallowed. |
|
Specifies the interval for emitting warnings about depleting disk space. This warning helps users take timely action to prevent running out of disk space. |
|
Should be increased if the daemon is under constant insertion pressure, and there is still available CPU: it increases the amount of threads the storage engine has available for background operations such as compaction. |
|
The number of threads allocated to high-priority operations such as flushes to disk. The default setting of 2 is sufficient for most cases. Increase if the server cannot keep up with the persistence layer. |
|
The AWS access key id to use for authentication. |
|
The secret key to use for authentication. You need both the access key and secret key set for authentication to work. |
|
Specifies a constant size for SST files within the SST file manager in cloud storage. The value is set to -1, indicating that the default size is used. |
|
Determines the number of objects listed in a single iteration when interacting with cloud storage. The value is set to 5000. |
|
Specifies the path to the SSL certificate authority (CA) certificate for secure communication with cloud storage. The value is an empty string. |
|
Controls SSL verification when communicating with cloud storage. The value is set to true. |
|
The size of the local SST cache, in bytes. The default value is |
|
The timeout used for cloud queries, in milliseconds. The default of 0 means that the cloud provider’s default will be used. |
|
Will create the bucket if it does not exist. |
|
The bucket name where to store the data. On AWS, the bucket name must be unique. If name is empty, the database will not upload its content to the cloud. |
|
The bucket name where to read the data from. On AWS, the bucket name must be unique. If name is empty, the database will not read its content from the cloud. |
|
The configuration file to use for authentication. When using a configuration file, |
|
Enabling this option leverages the parallelism of uploads and downloads of files to and from S3. This optimization enhances performance but necessitates increased memory usage for various buffers. |
|
The number of threads to be used by the AWS transfer manager. |
|
The buffer size for the AWS transfer manager. Files larger will be broken into smaller pieces, transfered in parallel. |
|
This configuration is intended for non-AWS S3 deployments. It allows you to specify a different hostname or IP address to communicate with, replacing the default AWS S3 endpoint. |
|
The section name in the configuration file with the |
|
AWS KMS key ID to use for S3 server-side encryption. Leave this string empty to use S3-managed server-side encryption when encryption is otherwise enabled by the storage integration. |
|
When enabled, this configuration utilizes EC2 instance metadata for automatic authentication credential resolution when communicating with the S3 bucket. It is typically recommended to set this to |
|
Quasardb will use |
|
The region where the bucket is located. |
|
A string either “none” or “aws” specifying your cloud provider to use to store the cloud data. |
For more information regarding RocksDB tuning refer to RocksDB Tuning Guide
2.1.3.1. Transient Storage Engine#
The transient storage engine is an in-memory storage option designed exclusively for automated testing environments. It provides no data persistence and keeps all data in memory.
Key characteristics:
No disk writes - all data stored in memory only
Faster write operations compared to RocksDB
Slower read operations due to less efficient indexing
All data lost on node restart or eviction
Not suitable for production use
Critical limitations:
All nodes in a cluster must use the same storage engine. Mixing transient and RocksDB nodes causes undefined behavior and data loss.
No statistics collection
No entry iteration support
Data evicted from memory is permanently lost
When to use:
Use transient storage only for automated test suites where data persistence is not required and you need a clean, ephemeral database instance.
For conceptual details, see Transient mode in Data Storage.
2.1.4. Networking#
The QuasarDB daemon uses TCP for network communications and listens to two ports. The primary port is configurable and is the port used by client applications. Its default value is 2836. The secondary port, is used for cluster discovery mechanisms and queries run on separate, higher priority partitions. This design ensures that when the server is busy processing queries, it can still service cluster management requests and preserve stability.
The value of the secondary port is set to the value of the primary port plus one (1). Thus, by default, the value of the secondary port is 2837.
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
Local address and port to bind to for accepting new connections. Can also refer to network adapter, e.g. |
|
|
|
Specify if the local address we bind to is not the same as other nodes or clients should use to connect to the daemon (e.g. when behind a NAT). Defaults to |
|
|
|
Time, in milliseconds, until an idle server socket can be recycled. The
default is |
|
|
|
Timeout for remote requests, in milliseconds. The default is |
|
|
|
Maximum accepted input message size, in bytes. The minimum is |
|
|
|
Configured maximum output message size, in bytes. The minimum is 1 KiB and the default is 128 MiB. This setting is currently retained for compatibility but is not enforced by the server. |
|
|
|
Enables publishing changes on the firehose endpoint. The default is
|
|
|
|
Endpoint on which the firehose publisher accepts subscribers. It is only
active when firehose publishing is enabled and defaults to
|
|
|
|
A string representing the name of the persisted firehose. The default is an empty string, which disables the persisted firehose. |
|
|
|
Persisted-firehose shard duration in milliseconds. The minimum is |
|
|
|
Enable replication. Enabled by default. |
|
|
|
Allows queries to use microindexes for selections and aggregations. Enabled by default and normally changed only for troubleshooting or testing. |
|
|
|
Specifies the number of threads used for publishing data to Firehose. The default value is 1. |
|
|
|
Controls whether the daemon checks for new versions. Enabled by default. |
|
|
|
Preferred setting for the maximum number of concurrent server
connections. |
|
|
|
Threshold in milliseconds for logging slow network operations. |
|
|
|
Soft limit for outbound connections to one address. The default is
|
2.1.5. Clustering#
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
Unique identifier for this node. See also: Node ID configuration. |
|
|
|
One or more peers that should be connected to to discover and bootstrap the cluster. Peers should be specified as a JSON array of tuples of address:port, e.g. |
|
|
|
Replication factor of data stored inside the cluster. It cannot be higher
than |
|
|
|
Maximum ACL cache duration in milliseconds. The default is |
|
|
|
Maximum number of ACL cache entries per node. The minimum is |
|
|
|
Allows ACL information to be fetched from other nodes. Enabled by default. |
|
|
|
An integer representing the maximum guaranteed duration of a transaction, in milliseconds. Transactions exceeding this interval are rolled back. The default value is 15,000 ms. |
|
|
|
Maximum number of entry versions retained for transaction history. The
minimum is |
|
|
|
Maximum wait between stabilizations, in milliseconds. It must be greater
than |
|
|
|
Minimum wait between stabilizations, in milliseconds. It must be greater
than |
|
|
|
Disables the Chord stabilization, finger-fixing, and peer services. This
is intended for specialized testing and should remain |
|
|
|
Enable or disable synchronization of data before joining the cluster. Enabling it might provoke spurious data downloads and higher disk usage. Disabling it on a clear node might result in missing historical data on this node. |
2.1.6. Security#
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
Boolean that determines whether security should be enabled. Valid values are |
|
|
|
Absolute location to the file that contains the QuasarDB users. Typically should be |
|
|
|
Absolute location to the cluster private key file. Typically should be |
|
|
|
Directory used to back up user credential files. The default is empty. |
|
|
|
Up to four client user-property key/value pairs that are prohibited from connecting to the cluster. |
|
|
|
Boolean that determines whether full stream encryption should be enabled, including both client-to-server and node-to-node cluster communication. Valid values are |
|
|
|
Allows the cluster to be remotely purged via an API call. False by default. |
|
|
|
Allows a node to be stopped remotely through an API call. Disabled by default. |
2.1.7. Performance tuning#
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
Deprecated per-partition session limit retained for compatibility. Use
|
|
|
|
The number of partitions (thread pools) for query processing. Each partition can perform one storage write at a time while handling multiple reads in parallel. Client connections are pinned to partitions. Use |
|
|
|
Number of high-priority partitions used for service traffic on the
secondary port. Valid values are |
|
|
|
Maximum number of RocksDB files kept open. |
|
|
|
Resident-memory threshold, in bytes, at which QuasarDB starts evicting
cached entries. |
|
|
|
Emergency resident-memory threshold, in bytes. At this limit QuasarDB
pauses processing and performs aggressive eviction. |
|
|
|
Hard memory limit as a percentage of the physical memory available to
the process. Valid values are |
|
|
|
Soft memory limit as a percentage of the physical memory available to
the process. Valid values are |
|
|
|
Maximum number of updated entries queued for asynchronous cache
trimming. The minimum is |
|
|
|
Maximum rows allowed in one table shard. |
|
|
|
The interval, in milliseconds, at which TBB allocator statistics are
refreshed. The default value is |
|
|
|
Number of entries selected in a soft-eviction pass. |
|
|
|
An integer representing the threshold (in bytes) above which memory allocations use huge pages, improving memory performance for large allocations. |
|
|
|
TBB allocator soft heap limit in bytes. |
|
|
|
When set to true, the TBB allocator uses huge pages for memory allocations to improve memory performance for large allocations. |
|
|
|
Number of shards used by the LRU2 cache. It must be a power of two from
|
2.1.8. Observability#
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
The maximum detail level for log output. Accepted values are
|
|
|
|
Directory for log files. The daemon’s built-in default is empty.
Packaged installations normally set it to |
|
|
|
Log flush interval in milliseconds. The minimum is |
|
|
|
Writes log messages to standard output. Enabled by default, although daemon-mode validation can adjust output behavior. |
|
|
|
Writes log messages to syslog on supported systems. Disabled by default. |
|
|
|
Enables logging in JSON file format. Required to display user properties. Disabled by default. |
|
|
|
Enables performance profiling from the server side, so that clients can start running performance traces. It has a small performance impact, and is disabled by default. |
|
|
|
Logs warning message when pushes increase shard volume by less than set percent. The default value is 0% - logging disabled. |
|
|
|
Enables runtime statistics collected server side. It has a small performance impact and is enabled by default. Statistics cannot be enabled with the transient storage engine. |
|
|
|
Time in milliseconds between normal statistics snapshots. The minimum is
|
2.1.9. Asynchronous time series inserter#
The asynchronous time series inserter buffers inserts in server memory. Use the options in this section to configure the pipelines.
Config File |
Command-Line Argument |
Environment Variable |
Description |
|---|---|---|---|
|
|
|
The number of asynchronous time series pipelines. The default is |
|
|
|
The maximum buffer size for each pipeline. The default is |
|
|
|
The maximum time between pipeline flushes. The default is |
2.2. QuasarDB Rest Server#
See quasardb REST API for detailed information on configuring the QuasarDB Rest Server, including available options for command line arguments, environmental variables, and JSON config files.
2.3. Docker#
As it can a bit tedious to edit a configuration file inside a Docker container, the bureau14/qdb docker container provides several environment variables you can use to configure the most common configuration options.
Below you find an overview of the different environment variables the image supports:
Variable |
Example usage |
|---|---|
|
$ docker run -d \
-e QDB_LOCAL_USER_LICENSE_KEY="$your_license_key" \
bureau14/qdb
|
|
$ docker run -d \
-v /path/to/my/qdb.key:/qdb.key \
-e QDB_LOCAL_USER_LICENSE_FILE=/qdb.key \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_NETWORK_LISTEN_ON=102836 \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_NETWORK_ADVERTISE_AS="172.16.64.8" \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_LOGGER_LOG_LEVEL=1 \
bureau14/qdb
|
|
$ docker run -d \
-v /my/qdb/log/output:/logs \
-e QDB_LOCAL_LOGGER_LOG_DIRECTORY="/logs" \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_GLOBAL_SECURITY_ENABLED=true \
\
-v /path/to/my/qdb/private.key:/private.key \
-e QDB_GLOBAL_SECURITY_CLUSTER_PRIVATE_FILE=/private.key \
\
-e QDB_GLOBAL_SECURITY_USER_LIST=... \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_GLOBAL_CLUSTER_REPLICATION_FACTOR=3 \
\
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_NETWORK_TOTAL_SERVER_SESSIONS=8192 \
\
bureau14/qdb
|
|
$ docker run -d \
--cpu-number=32 \
-e QDB_LOCAL_NETWORK_PARALLELISM=24 \
-e QDB_LOCAL_DEPOT_ROCKSDB_THREADS=8 \
-e QDB_LOCAL_DEPOT_ROCKSDB_HI_THREADS=1 \
\
bureau14/qdb
|
|
$ docker run -d
-e QDB_GLOBAL_CLUSTER_PUBLISH_FIREHOSE="true" \
\
bureau14/qdb
|
|
$ docker run -d
-e QDB_GLOBAL_CLUSTER_PUBLISH_FIREHOSE="true" \
-e QDB_LOCAL_NETWORK_FIREHOSE_PUBLISHING_THREADS=4 \
\
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_LIMITER_MAX_BYTES_SOFT=17179869184 \
-e QDB_LOCAL_LIMITER_MAX_BYTES_HARD=25769803776 \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_LIMITER_MAX_BYTES_SOFT=17179869184 \
-e QDB_LOCAL_LIMITER_MAX_BYTES_HARD=25769803776 \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_DEPOT_ROCKSDB_THREADS=8 \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_DEPOT_ROCKSDB_THREADS=16 \
-e QDB_LOCAL_DEPOT_ROCKSDB_HI_THREADS=2 \
bureau14/qdb
|
|
$ docker run -d \
-e QDB_LOCAL_DEPOT_ROCKSDB_CLOUD_PROVIDER="aws" \
bureau14/qdb
|
2.4. Configuring Short-Term Credentials for Amazon S3#
When connecting to Amazon S3 using short-term credentials, it’s essential to properly configure your application. This section guides you through the necessary steps and parameters.
2.4.1. Configuration Parameters#
You need to specify two configuration parameters in your application:
rocksdb.cloud.aws.config_file: The name of the configuration file.rocksdb.cloud.aws.config_file_section: The section name in the configuration file.
2.4.2. Format of the Configuration File#
Within the specified configuration file, you need to create a section (e.g., [section_name]) with three key-value pairs:
aws_access_key_id: Your AWS access key ID.aws_secret_access_key: Your AWS secret access key.aws_session_token: Your AWS session token (for short-term credentials).
2.4.3. QDBD Configuration#
This section explains how to configure your application for use with short-term credentials in a specific JSON format. It includes the following fields:
"aws": {
"config_file": "[credential file path]",
"config_file_section": "",
"bucket": {
"destination_bucket": "[bucket name]",
"path_prefix": "",
"region": "",
"source_bucket": "[bucket name]"
"use_instance_auth": false,
"provider": "aws",
"config_file": The path to the credential file."config_file_section": The section name in the credential file."bucket": Configuration related to the S3 bucket."use_instance_auth": A boolean value indicating whether to use instance authentication (set to false for local machines)."provider": The provider (in this case, “aws”).
2.4.4. Copying Credentials#
It also possible to copy/paste the credential file from either the Command Line or Programmatic Access. It’s a reminder to create a new credential file and not overwrite the default AWS credential file.