Configuration

SereneDB is configured via command-line options or a configuration file. All options can be passed as --section.option value on the command line or set in a JSON configuration file.

Using a configuration file

serened --configuration /etc/serenedb/serened.conf

The configuration file uses JSON format:

{
  "database": {
    "directory": "/var/lib/serenedb"
  },
  "server": {
    "endpoint": ["pgsql+tcp://0.0.0.0:7890"]
  }
}

Common options

The most frequently used options for getting started:

Option	Default	Description
--database.directory	/var/lib/serenedb	Path to the database directory
--server.endpoint	pgsql+tcp://127.0.0.1:7890	Server endpoint (e.g., pgsql+tcp://0.0.0.0:7890)
--log.level	info	Log level: fatal, error, warning, info, debug, trace
--log.output	—	Log destination (e.g., file:///var/log/serenedb/serened.log)
--temp.path	—	Path for temporary files

Example: start with custom port and data directory

serened --database.directory /data/serenedb --server.endpoint pgsql+tcp://0.0.0.0:7890

---

Database

Option	Type	Default	Description
--database.directory	string	/var/lib/serenedb	Path to the database directory
--database.auto-upgrade	boolean	false	Perform a database upgrade if necessary
--database.required-directory-state	string	any	Required state of the database directory at startup (non-existing, existing, empty, populated, any)

Server

Option	Type	Default	Description
--server.endpoint	string	pgsql+tcp://127.0.0.1:7890	Endpoint for client requests
--server.io-threads	uint64	8	Number of threads for I/O
--server.maximal-threads	uint64	0	Maximum request handling threads (0 = auto, default 64)
--server.maximal-queue-size	uint64	4096	Request queue size
--server.authentication	boolean	true	Enable authentication for client requests
--server.jwt-secret-keyfile	string	—	File containing the JWT secret for authentication
--server.harden	boolean	false	Lock down APIs that reveal version/internals for non-admin users
--server.statistics	boolean	false	Enable statistics gathering and APIs

Search

Option	Type	Default	Description
--search.commit-threads	uint32	0	Upper limit for commit threads (0 = auto)
--search.consolidation-threads	uint32	0	Upper limit for consolidation threads (0 = auto)
--search.default-parallelism	uint32	1	Default parallelism for search queries
--search.execution-threads-limit	uint32	0	Maximum threads for processing search indexes during queries

Logging

Option	Type	Default	Description
--log.level	string	info	Log level per topic. Use --log.level topic=level for specific topics
--log.output	string	—	Log destination (e.g., file:///var/log/serenedb/serened.log)
--log.use-json-format	boolean	false	Use JSON format for log output
--log.color	boolean	true	Use colors for TTY logging
--log.time-format	string	utc-datestring-micros	Time format in logs

Available log levels: fatal, error, warning, info, debug, trace

RocksDB (storage engine)

Options for tuning the underlying RocksDB storage engine. Most defaults are suitable for general use.

Memory

Option	Type	Default	Description
--rocksdb.block-cache-size	uint64	auto	Size of block cache in bytes
--rocksdb.write-buffer-size	uint64	67108864 (64 MB)	Data to build up in memory before flushing to disk
--rocksdb.max-write-buffer-number	uint64	4	Maximum write buffers in memory
--rocksdb.total-write-buffer-size	uint64	auto	Maximum total size of write buffers

Compaction

Option	Type	Default	Description
--rocksdb.compaction-style	string	level	Compaction style (level, others are experimental)
--rocksdb.compression-type	string	lz4	Compression algorithm
--rocksdb.max-parallel-compactions	uint64	2	Maximum parallel compaction jobs
--rocksdb.max-subcompactions	uint32	4	Maximum concurrent sub-jobs per compaction
--rocksdb.level0-compaction-trigger	int64	2	Number of level-0 files that triggers compaction
--rocksdb.target-file-size-base	uint64	67108864 (64 MB)	Target file size for compaction

WAL

Option	Type	Default	Description
--rocksdb.wal-directory	string	—	Absolute path for WAL files (default: journals/ inside database directory)
--rocksdb.max-total-wal-size	uint64	268435456 (256 MB)	Maximum total WAL size before forcing a flush
--rocksdb.sync-interval	uint64	100	Interval for automatic disk syncs in milliseconds (0 = off)

Disk

Option	Type	Default	Description
--rocksdb.minimum-disk-free-bytes	uint64	16777216 (16 MB)	Minimum free disk bytes for healthy status (0 = disable)
--rocksdb.minimum-disk-free-percent	double	0.01	Minimum free disk percentage for healthy status (0 = disable)

SSL/TLS

Option	Type	Default	Description
--ssl.keyfile	string	—	Keyfile for secure connections
--ssl.cafile	string	—	CA file for secure connections
--ssl.protocol	uint64	9	SSL protocol (5 = TLSv1.2, 6 = TLSv1.3, 9 = generic TLS negotiated)
--ssl.cipher-list	string	HIGH:!EXPORT:!aNULL@STRENGTH	SSL ciphers to use

All options

To see all available options including hidden and advanced ones:

serened --help
serened --dump-options