TrtlDB

TrtlDb is a globally replicated key-value store that uses anti-entropy for eventually consistent replication that minimizes egress costs, maximizes availability, and is partition tolerant. It exposes unary and streaming APIs for data access and is secured via mTLS connections. Its environment variables are prefixed with the TRTL_ tag. The primary configuration is as follows:

Database

Internally, trtl uses a log-structured merge tree embedded database such as LevelDB to store its pages on disk. This embedded database is configured as follows:

The TRTL_DATABASE_URL is a standard DSN with a scheme, host, path, and query parameters. Trtl should always have access to a locally embedded database such as LevelDB. When connecting to a LevelDB, the path to the directory on disk where the leveldb should be stored must be passed to the DSN. To specify a relative path, use three slashes: leveldb:///relpath/to/db, to specify an absolute path use four: leveldb:////abspath/to/db.

Replica Config

TrtlDB is a globally replicated database and the replica config provides metadata about the TrtlDB instance for replication purposes while also setting parameters for replication. Replication is configured as follows:

If TRTL_REPLICA_ENABLED is true then TRTL_REPLICA_PID, TRTL_REPLICA_REGION, and TRTL_REPLICA_NAME are required to identify the unique replica in the system.

Replication occurs with bilateral anti-entropy, meaning that after a jittered interval, each replica randomly selects a peer to synchronize with. This is also referred to as a gossip protocol. The TRTL_REPLICA_GOSSIP_INTERVAL and TRTL_REPLICA_GOSSIP_SIGMA describe a normal distribution of randomly selected synchronization intervals, providing jitter so that the network is not bursty.

Replica Identification Strategy

When deployed in a kubernetes cluster, a trtl process running in a container in a pod must identify itself to determine what replica it is so that it can configure itself correctly (particularly if the replica is part of a stateful set). The replica strategy configuration defines how a trtl process bootstraps itself as follows:

The strategies allow the process to identify its PID - either by processing a hostname (e.g. trtl-10) or by reading the pid from a file. The remainder of the replica can then be configured from the JSON file rather than directly from the environment.

MTLS Config

Connections to the TrtlDB are secured and authenticated using mTLS. The mTLS configuration is as follows:

If TRTL_INSECURE is false then the TRTL_MTLS_CHAIN_PATH and the TRTL_MTLS_CERT_PATH are both required.

Backups

The Backup manager is a background process that clones the embedded database pages into a zipped folder on disk that can be downloaded for backup purposes. Backups run periodically and can be run without interupting database processing since the backup takes a live snapshot of the database. Backups are configured as follows:

Sentry

TrtlDB uses Sentry to assist with error monitoring and performance tracing. Configure TrtlDB to use Sentry as follows:

Sentry is considered enabled if a DSN is configured. Performance tracing is only enabled if Sentry is enabled and track performance is set to true. If Sentry is enabled, an environment is required, otherwise the configuration will be invalid.

Note that the sentry.Config object has a field Repanic that should not be set by the user. This field is used to manage panics in chained interceptors.