Настройка

Целевые БД

Цель — это БД, в которую takt записывает результаты. Цель задаётся SQLAlchemy URL.

Поддерживаемые БД:

БД	URL	v0
SQLite	sqlite:///path.db	поддерживается, ничего ставить не нужно
MariaDB	mariadb+pymysql://user:password@host:3306/db	поддерживается, нужен pip install "takt-py[mariadb]"; mariadb://… тоже можно
MySQL		позже
PostgreSQL		позже
DuckDB		позже
ClickHouse		позже

URL любой другой БД — ошибка, и takt сообщает о ней до запуска бенчмарков.

В URL SQLite перед относительным путём три слэша, sqlite:///bench.db, а перед абсолютным — четыре, sqlite:////var/lib/bench.db. Просто путь к файлу, например bench.db, или sqlite://bench.db с двумя слэшами — неверный URL: takt завершается с кодом 2 и печатает invalid database URL с примером правильной записи. URL SQLite в памяти, например sqlite:// или sqlite:///:memory:, тоже ошибка: такая БД исчезает, когда takt завершается, поэтому хранить в ней результаты нельзя.

Откуда берутся цели

takt берёт цели из первого заданного источника, в таком порядке:

Приоритет	Источник	Пример
1	флаги --db, --target	--db sqlite:///a.db --target maria_ci
2	переменная окружения TAKT_DB	TAKT_DB="sqlite:///a.db mariadb+pymysql://u:p@h/bench"
3	takt.toml	см. ниже

• Источник с бо́льшим приоритетом полностью заменяет источники ниже, они не объединяются.
• Без флагов и без TAKT_DB takt берёт все цели из takt.toml.
• --db и --target в одной команде складываются.
• Одна и та же БД записывается один раз, остаётся первая запись. Для SQLite takt сравнивает полные пути к файлам, поэтому sqlite:///bench.db и sqlite:////home/me/bench.db, запущенные из /home/me, — одна цель. Для MariaDB takt не смотрит на драйвер, пользователя и пароль, а если порт не указан, считает его равным 3306, поэтому mariadb://u:p@db/bench и mariadb+pymysql://ci:pw@db:3306/bench — одна цель.
• takt compare только по файлам работает вообще без целей. Он даже не читает --db, --target, --config, TAKT_DB и takt.toml, поэтому ошибка там или отсутствующий драйвер MariaDB не мешают сравнить файлы.

takt.toml

takt читает takt.toml из текущего каталога. --config PATH указывает другой файл; на приоритет выше это не влияет.

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"

• Каждая таблица [targets.<имя>] — одна цель с одним ключом url.
• В имени цели можно использовать латинские буквы, цифры, _ и -.
• name_template — имя прогона по умолчанию (см. раздел «Имя прогона» ниже).
• Любой другой ключ — ошибка.

--target NAME выбирает цели из takt.toml по имени. Например, takt import result.json --target local --target maria_ci пишет в две из трёх целей выше. Если takt не нашёл takt.toml, --target завершается ошибкой error: unknown target '<имя>': no takt.toml in <каталог>; use --config PATH.

Переменные окружения

Переменная	Что делает
TAKT_DB	цели по умолчанию: один или несколько URL через пробел
TAKT_NAME	имя прогона или шаблон имени по умолчанию
XDG_CACHE_HOME	где лежит кеш версий схемы

Пустое значение считается незаданным.

Если неверно значение, которое вы не вводили в команде, ошибка начинается с его источника, чтобы было понятно, где его исправить:

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}

Имя прогона

Имя прогона — это подпись сохранённого результата. По нему потом удобно искать результат в takt compare.

takt берёт имя из первого заданного источника:

Приоритет	Источник
1	--name
2	TAKT_NAME
3	name_template в takt.toml

Значение — это шаблон. takt заменяет в нём такие подстановки:

Подстановка	Значение	Пример
{date}	дата UTC	2026-09-25
{datetime}	дата и время UTC	2026-09-25T13-46-01Z
{path}	имя файла результата без .json / .json.gz	takt-20260925T134601Z
{python_version}	версия Python из результата, иначе unknown	3.14.0 (64-bit)
{hostname}	имя хоста из результата, иначе unknown	bench-host
{hash}	первые 12 символов хеша результата	3fa2b1c4d5e6

• Текст без подстановок берётся как есть: --name "default 01.01.01".
• {{ и }} дают обычные фигурные скобки.
• Пробелы, табуляции и переводы строк в начале и в конце итогового имени takt убирает.
• Символ : в имени запрещён: compare использует его в записи имя:N.
• Ещё ошибки: пустое имя, имя длиннее 255 символов, неизвестная подстановка (ошибка перечисляет допустимые), а также формат или преобразование в подстановке, даже пустой формат: {date:%Y}, {date:}, {date!r}.
• takt проверяет текст шаблона до запуска бенчмарков. Так находятся пустое имя, : в тексте, неизвестная подстановка, {date:%Y}, {date:} и {date!r}.
• Лимит 255 символов и :, который пришёл из значения вроде {hostname}, {python_version} или {path}, проверяются только в итоговом имени, когда takt уже прочитал результат. У takt run это происходит после бенчмарков: takt ничего не пишет в БД, оставляет файл результата, печатает путь к нему и завершается с кодом 2. Загрузите этот файл через takt import с другим --name.
• Имя необязательно. Прогон без имени можно найти только по хешу.
• Имя не уникально: у нескольких прогонов может быть одно имя.
• Если загрузить тот же результат ещё раз с другим именем, сохранённое имя не изменится.

Кеш схемы

При run и import takt сам создаёт и обновляет свои таблицы в каждой цели. В SQLite обновление схемы идёт одной транзакцией: если оно упало, в БД остаются старые таблицы, а следующий run или import пробует обновить схему снова. Чтобы в следующий раз не проверять схему заново, takt запоминает версию схемы каждой цели в локальном кеше.

• Где лежит: $XDG_CACHE_HOME/takt/, по умолчанию ~/.cache/takt/.
• Что хранит: версию схемы для каждой цели. takt хранит хеш URL, а не сам URL, поэтому пароли в кеш не попадают.
• Кеш можно удалить в любой момент. takt просто заново проверит схему каждой цели и создаст кеш снова.
• Если takt не может прочитать или записать кеш, например когда домашний каталог в контейнере или в CI доступен только для чтения, он работает без кеша: проверяет схему каждой цели при каждом run и import, а результат всё равно записывается.