Skip to content

Configuration

Every setting of tamarackdb-server. The settings of tamarackdb-backup are in Backup and Import.

Sources

A setting comes from, in this order:

  1. A TOML file, passed with --config (config.toml in the working directory by default), under a [server] section.
  2. A TAMARACKDB_* environment variable.
  3. 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 of tamarackdb-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.toml

Settings

KeyEnvironment variableDefaultWhat it sets
socketPathTAMARACKDB_SOCKET_PATH/run/tamarackdb/tamarackdb.sockThe unix socket to listen on
socketModeTAMARACKDB_SOCKET_MODE"0600"The socket’s permissions, as an octal string
bindAddressTAMARACKDB_BIND_ADDRESS127.0.0.1The address to listen on over TCP
portTAMARACKDB_PORT8085The port to listen on over TCP
authTokenFileTAMARACKDB_AUTH_TOKEN_FILEnoneThe file holding the Bearer token. Setting it turns authentication on (see Security)
allowNoAuthTAMARACKDB_ALLOW_NO_AUTHfalseWhether the server may listen over TCP on an address other than loopback without authTokenFile. Ignored on the unix socket
dataDirTAMARACKDB_DATA_DIRdataThe directory holding the database file, tamarackdb.sqlite
logLevelTAMARACKDB_LOG_LEVELinfoThe lowest level logged: debug, info, warning, or error
devModeTAMARACKDB_DEV_MODEfalseTurns on DELETE /events and the profiling endpoints
defaultEventsPerPageTAMARACKDB_DEFAULT_EVENTS_PER_PAGE10000The limit of a QUERY /events that leaves it out
maxEventsPerPageTAMARACKDB_MAX_EVENTS_PER_PAGE10000The highest limit a QUERY /events may ask for
maxEventSizeTAMARACKDB_MAX_EVENT_SIZE65536 (64 KiB)The largest event, in bytes
maxProjectionSizeTAMARACKDB_MAX_PROJECTION_SIZE65536 (64 KiB)The largest projection, in bytes
maxEventsPerTxTAMARACKDB_MAX_EVENTS_PER_TX100The most events one transaction writes
maxReadsPerTxTAMARACKDB_MAX_READS_PER_TX100The most reads of events in one transaction
maxProjectionsPerTxTAMARACKDB_MAX_PROJECTIONS_PER_TX500The most projections one transaction writes
maxProjectionsPerWriteTAMARACKDB_MAX_PROJECTIONS_PER_WRITE500The most projections in one POST /projections
maxEventsPerTxReadTAMARACKDB_MAX_EVENTS_PER_TX_READ10000The most events one read of a transaction returns
maxRequestBodySizeTAMARACKDB_MAX_REQUEST_BODY_SIZE8388608 (8 MiB)The largest request body, in bytes
maxQueuedWritesTAMARACKDB_MAX_QUEUED_WRITES100The most writes waiting for their turn at once
readPoolSizeTAMARACKDB_READ_POOL_SIZE8How many reads run at once
txIdleTimeoutTAMARACKDB_TX_IDLE_TIMEOUT60How long, in seconds, a transaction lives without a call
maxOpenTxTAMARACKDB_MAX_OPEN_TX1000The most transactions open at once

Listening

  • By default, the server listens on the unix socket at socketPath. Setting bindAddress or port switches it to TCP. A socketPath that is set wins over both.
  • The socket’s directory must exist and be writable by the server’s user. Under systemd, RuntimeDirectory creates 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 defaultEventsPerPage can’t exceed maxEventsPerPage. The server refuses to start otherwise.
  • Set defaultEventsPerPage so 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 readPoolSize reads at once, each of maxEventsPerPage (or maxEventsPerTxRead) events of maxEventSize bytes: 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.
  • txIdleTimeout only ends transactions the application forgot. A transaction that keeps making calls lives as long as it needs.
  • Past maxOpenTx, POST /tx gets 503 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.
  • maxQueuedWrites bounds how many writes wait at once. One more gets 503 WriteQueueFull. Set it from how many writes the application sends at once.