Configuration
Every setting of tamarackdb-server. The settings of tamarackdb-backup are in
Backup and Import.
Sources
A setting comes from, in this order:
- A TOML file, passed with
--config(config.tomlin the working directory by default), under a[server]section. - A
TAMARACKDB_*environment variable. - A built-in default.
- The file wins over the environment. It’s optional: in Docker, environment variables are enough.
- An unknown key stops the server at startup, with an error naming it.
- The same file can hold the
[backup]section oftamarackdb-backup. Each binary reads only its own section.
Generate a starter file, with every setting at its default:
tamarackdb-server --default-config > config.toml
tamarackdb-backup --default-config >> config.tomlSettings
| Key | Environment variable | Default | What it sets |
|---|---|---|---|
socketPath | TAMARACKDB_SOCKET_PATH | /run/tamarackdb/tamarackdb.sock | The unix socket to listen on |
socketMode | TAMARACKDB_SOCKET_MODE | "0600" | The socket’s permissions, as an octal string |
bindAddress | TAMARACKDB_BIND_ADDRESS | 127.0.0.1 | The address to listen on over TCP |
port | TAMARACKDB_PORT | 8085 | The port to listen on over TCP |
authTokenFile | TAMARACKDB_AUTH_TOKEN_FILE | none | The file holding the Bearer token. Setting it turns authentication on (see Security) |
allowNoAuth | TAMARACKDB_ALLOW_NO_AUTH | false | Whether the server may listen over TCP on an address other than loopback without authTokenFile. Ignored on the unix socket |
dataDir | TAMARACKDB_DATA_DIR | data | The directory holding the database file, tamarackdb.sqlite |
logLevel | TAMARACKDB_LOG_LEVEL | info | The lowest level logged: debug, info, warning, or error |
devMode | TAMARACKDB_DEV_MODE | false | Turns on DELETE /events and the profiling endpoints |
defaultEventsPerPage | TAMARACKDB_DEFAULT_EVENTS_PER_PAGE | 10000 | The limit of a QUERY /events that leaves it out |
maxEventsPerPage | TAMARACKDB_MAX_EVENTS_PER_PAGE | 10000 | The highest limit a QUERY /events may ask for |
maxEventSize | TAMARACKDB_MAX_EVENT_SIZE | 65536 (64 KiB) | The largest event, in bytes |
maxProjectionSize | TAMARACKDB_MAX_PROJECTION_SIZE | 65536 (64 KiB) | The largest projection, in bytes |
maxEventsPerTx | TAMARACKDB_MAX_EVENTS_PER_TX | 100 | The most events one transaction writes |
maxReadsPerTx | TAMARACKDB_MAX_READS_PER_TX | 100 | The most reads of events in one transaction |
maxProjectionsPerTx | TAMARACKDB_MAX_PROJECTIONS_PER_TX | 500 | The most projections one transaction writes |
maxProjectionsPerWrite | TAMARACKDB_MAX_PROJECTIONS_PER_WRITE | 500 | The most projections in one POST /projections |
maxEventsPerTxRead | TAMARACKDB_MAX_EVENTS_PER_TX_READ | 10000 | The most events one read of a transaction returns |
maxRequestBodySize | TAMARACKDB_MAX_REQUEST_BODY_SIZE | 8388608 (8 MiB) | The largest request body, in bytes |
maxQueuedWrites | TAMARACKDB_MAX_QUEUED_WRITES | 100 | The most writes waiting for their turn at once |
readPoolSize | TAMARACKDB_READ_POOL_SIZE | 8 | How many reads run at once |
txIdleTimeout | TAMARACKDB_TX_IDLE_TIMEOUT | 60 | How long, in seconds, a transaction lives without a call |
maxOpenTx | TAMARACKDB_MAX_OPEN_TX | 1000 | The most transactions open at once |
Listening
- By default, the server listens on the unix socket at
socketPath. SettingbindAddressorportswitches it to TCP. AsocketPaththat is set wins over both. - The socket’s directory must exist and be writable by the server’s user. Under systemd,
RuntimeDirectorycreates it (see Install). - The server speaks plain HTTP. Reaching it from another host is in Security.
Limits
- The size and count limits are a cautious starting point. Find the right values in development, with the application’s data, and use the same ones in production. Every error from a limit names the setting to raise.
- Every limit must be positive, and
defaultEventsPerPagecan’t exceedmaxEventsPerPage. The server refuses to start otherwise. - Set
defaultEventsPerPageso that a page reads in under a second. A longer read keeps the WAL file from being emptied (see Monitoring). - The server loads a read in memory before it sends it. At worst, it holds
readPoolSizereads at once, each ofmaxEventsPerPage(ormaxEventsPerTxRead) events ofmaxEventSizebytes: about 5 GiB with the defaults. A page of 10,000 events of about 1 KB takes about 10 MB. - A client has one minute to send a request, its body included. Past that, the server closes the connection without an answer. This limit is fixed.
txIdleTimeoutonly ends transactions the application forgot. A transaction that keeps making calls lives as long as it needs.- Past
maxOpenTx,POST /txgets503 TooManyTransactions. The open transactions go on. A commit still writing counts as open.
Write queue
Writes are served one at a time, in the order they arrive: transaction commits, POST /projections, bulk deletes of
events and projections, POST /pause, POST /resume, and POST /optimize. Reads never wait.
- A write usually holds its turn a few milliseconds, so the queue stays short.
- A large write, such as a projection rebuild in one request, makes the others wait that long.
maxQueuedWritesbounds how many writes wait at once. One more gets503 WriteQueueFull. Set it from how many writes the application sends at once.