Configuration

Target databases

A target is a database where takt stores results. It is set with a SQLAlchemy URL.

Supported databases:

Database	URL	v0
SQLite	sqlite:///path.db	supported, needs nothing extra
MariaDB	mariadb+pymysql://user:password@host:3306/db	supported, needs pip install "takt-py[mariadb]"; mariadb://… also works
MySQL		later
PostgreSQL		later
DuckDB		later
ClickHouse		later

A URL of any other database is an error, and takt reports it before any benchmark runs.

A SQLite URL has three slashes before a relative path, sqlite:///bench.db, and four before an absolute one, sqlite:////var/lib/bench.db. A bare file path such as bench.db, or sqlite://bench.db with two slashes, is not a valid URL: takt stops with exit code 2 and prints invalid database URL with an example of the right form. An in-memory SQLite URL, such as sqlite:// or sqlite:///:memory:, is an error too: such a database disappears when takt exits, so it cannot keep results.

Where targets come from

takt takes targets from the first source that is set, in this order:

Priority	Source	Example
1	Flags --db, --target	--db sqlite:///a.db --target maria_ci
2	Environment variable TAKT_DB	TAKT_DB="sqlite:///a.db mariadb+pymysql://u:p@h/bench"
3	takt.toml	see below

• A source with a higher priority fully replaces the sources below it; they are not merged.
• Without flags and without TAKT_DB, takt uses all targets from takt.toml.
• --db and --target in one command add up.
• The same database is written only once, and the first spelling is kept. For SQLite takt compares the full file paths, so sqlite:///bench.db and sqlite:////home/me/bench.db, run from /home/me, are one target. For MariaDB takt ignores the driver, the user and the password, and takes a URL without a port as port 3306, so mariadb://u:p@db/bench and mariadb+pymysql://ci:pw@db:3306/bench are one target.
• takt compare with files only needs no targets at all. It does not even read --db, --target, --config, TAKT_DB or takt.toml, so a mistake there, or a missing MariaDB driver, does not stop a compare of files.

takt.toml

takt reads takt.toml from the current directory. --config PATH points to another file; it does not change the priority above.

name_template = "nightly {date}"

[targets.local]
url = "sqlite:///bench.db"

[targets.archive]
url = "sqlite:////var/lib/bench/archive.db"

[targets.maria_ci]
url = "mariadb+pymysql://user:password@db-host:3306/bench"

• Every [targets.<name>] table is one target with one key url.
• A target name may contain Latin letters, digits, _ and -.
• name_template is the default run name (see the "Run name" section below).
• Any other key is an error.

--target NAME picks targets from takt.toml by name. For example, takt import result.json --target local --target maria_ci writes to two of the three targets above. If takt finds no takt.toml, --target stops with error: unknown target '<name>': no takt.toml in <folder>; use --config PATH.

Environment variables

Variable	What it does
TAKT_DB	Default targets: one or more URLs separated by spaces
TAKT_NAME	Default run name or name template
XDG_CACHE_HOME	Where the schema version cache lives

An empty value counts as not set.

If a value that you did not type in the command is wrong, the error starts with its source, so you know where to fix it:

error: TAKT_DB: unsupported database 'postgresql'; supported in this version: mariadb, sqlite
error: TAKT_NAME: run name must not contain ':': 'run:1'
error: /home/me/proj/takt.toml: target 'pg': unsupported database 'postgresql'; supported in this version: mariadb, sqlite
error: /home/me/proj/takt.toml: name_template: invalid name template 'nightly {commit}': unknown placeholder {commit}; allowed: {date}, {datetime}, {path}, {python_version}, {hostname}, {hash}

Run name

A run name is a label for a stored result. You use it later in takt compare.

takt takes the name from the first source that is set:

Priority	Source
1	--name
2	TAKT_NAME
3	name_template in takt.toml

The value is a template. takt replaces these placeholders:

Placeholder	Value	Example
{date}	UTC date	2026-09-25
{datetime}	UTC date and time	2026-09-25T13-46-01Z
{path}	Result file name without .json / .json.gz	takt-20260925T134601Z
{python_version}	Python version from the result, otherwise unknown	3.14.0 (64-bit)
{hostname}	Host name from the result, otherwise unknown	bench-host
{hash}	First 12 characters of the result hash	3fa2b1c4d5e6

• Text without placeholders is used as is: --name "default 01.01.01".
• {{ and }} give literal braces.
• takt removes spaces, tabs and line breaks at the start and at the end of the final name.
• The character : is not allowed in a name, because compare uses it in name:N.
• These are errors too: an empty name, a name longer than 255 characters, an unknown placeholder (the error lists the allowed ones), and a format spec or conversion in a placeholder, even an empty one: {date:%Y}, {date:}, {date!r}.
• takt checks the template text before any benchmark runs. This finds an empty name, : in the text, an unknown placeholder, {date:%Y}, {date:} and {date!r}.
• The 255-character limit, and a : that comes from a value such as {hostname}, {python_version} or {path}, are checked only on the final name, after takt has read the result. With takt run this happens after the benchmarks: takt writes nothing to the databases, keeps the result file, prints its path and exits with code 2. Load that file with takt import and another --name.
• The name is optional. A run without a name can be found only by its hash.
• The name is not unique: several runs can have the same name.
• Importing the same result again with another name does not change the stored name.

Schema cache

takt creates and updates its tables in every target on run and import. On SQLite a schema update runs in one transaction: if it fails, the database keeps its old tables, and the next run or import tries the update again. To skip the schema check next time, takt remembers the schema version of every target in a local cache.

• Location: $XDG_CACHE_HOME/takt/, by default ~/.cache/takt/.
• Content: the schema version for every target. takt stores a hash of the URL, not the URL, so passwords do not get into the cache.
• You can delete the cache at any time. takt then checks the schema of every target again and recreates the cache.
• If takt cannot read or write the cache, for example when the home folder is read-only in a container or in CI, it works without the cache: it checks the schema of every target on every run and import, and the result is still written.