Docs

Configuration

kova.toml sets the port, the data directory, and the optional security, replica, and shard sections.

The server reads kova.toml from the working directory. Point KOVA_CONFIG at another file to load a different profile. Every key can also be set with an environment variable. The environment wins over the file, and the file wins over the built-in default.

Sections you leave commented stay off. A default file is one process, security off, no replicas, no shards.

Listener

Key Default Environment

port 27018 KOVA_PORT

max_connections 128 KOVA_MAX_CONNECTIONS

max_connection_idle_ms 0, idle close off KOVA_MAX_CONNECTION_IDLE_MS

log_level info KOVA_LOG_LEVEL (debug, info, warn, error)

warn_on_non_mongo_queries true KOVA_WARN_NON_MONGO_QUERIES

Key	Default	Environment
`port`	27018	`KOVA_PORT`
`max_connections`	128	`KOVA_MAX_CONNECTIONS`
`max_connection_idle_ms`	0, idle close off	`KOVA_MAX_CONNECTION_IDLE_MS`
`log_level`	`info`	`KOVA_LOG_LEVEL` (`debug`, `info`, `warn`, `error`)
`warn_on_non_mongo_queries`	true	`KOVA_WARN_NON_MONGO_QUERIES`

Past max_connections the listener accepts the socket, replies with an error, and closes it. That socket is not counted in connectionsActive. KOVA_LOG_LEVEL=debug kova raises the log level for that run.

The warning flag logs a WARN when a query uses a Kova extension such as $text.$boost or $text.$decay, or an operator the engine does not implement. Set it to false to silence those lines. The query still runs when the extension is supported.

Search

[search]
analyzer = "default"
stopwords = []

default splits on punctuation and whitespace, then lowercases. en_stem adds English stemming. stopwords is an extra list removed at index time and at query time. The analyzer is fixed when the text index is built.

Storage

Key Default What it changes

data_dir data Root for pages, the log, and replica state. Environment KOVA_DATA_DIR.

page_size 16384 Page envelope in bytes. The payload inside is zstd-compressed, so the file is often shorter. KOVA_PAGE_SIZE.

buffer_pool_pages 4096 Pages kept in RAM per partition. KOVA_BUFFER_POOL_PAGES.

wal_fsync true Flush every log append before the page changes. KOVA_WAL_FSYNC.

wal_segment_bytes 16777216 Roll the log to a new file around this size.

checkpoint_every 128 Snapshot after this many mutations. Shutdown also checkpoints. 0 disables the periodic snapshot.

Key	Default	What it changes
`data_dir`	`data`	Root for pages, the log, and replica state. Environment `KOVA_DATA_DIR`.
`page_size`	16384	Page envelope in bytes. The payload inside is zstd-compressed, so the file is often shorter. `KOVA_PAGE_SIZE`.
`buffer_pool_pages`	4096	Pages kept in RAM per partition. `KOVA_BUFFER_POOL_PAGES`.
`wal_fsync`	true	Flush every log append before the page changes. `KOVA_WAL_FSYNC`.
`wal_segment_bytes`	16777216	Roll the log to a new file around this size.
`checkpoint_every`	128	Snapshot after this many mutations. Shutdown also checkpoints. 0 disables the periodic snapshot.

Give each process its own data_dir when you run more than one. Sharing a directory between two processes corrupts the pages.

Sections that start off

[security], [replication], and [sharding] are commented in the shipped file. Uncomment a section only when you want that behavior. The pages for them have the keys and a worked layout:

[feed] is reserved for a later release. Leaving it out changes nothing. The intended keys are on Feed.