Перейти к основному содержимому
Перейти к основному содержимому

Непрерывная интеграция (CI)

Когда вы отправляете pull request, для вашего кода выполняются автоматические проверки системой ClickHouse непрерывной интеграции (CI). Это происходит после того, как мейнтейнер репозитория (кто‑то из команды ClickHouse) просмотрел ваш код и добавил к вашему pull request метку can be tested. Результаты проверок перечислены на странице pull request в GitHub, как описано в документации по проверкам GitHub. Если проверка завершилась с ошибкой, возможно, вам потребуется её исправить. На этой странице приведён обзор проверок, с которыми вы можете столкнуться, и того, что можно сделать для их исправления.

Если кажется, что сбой проверки не связан с вашими изменениями, это может быть временной ошибкой или проблемой с инфраструктурой. Запушьте пустой коммит в pull request, чтобы перезапустить проверки CI:

git commit --allow-empty
git push

Если вы не уверены, как поступить, обратитесь за помощью к мейнтейнеру проекта.

Объединение с master​

Проверяет, что PR может быть объединён с веткой master. Если это невозможно, проверка завершится с ошибкой Cannot fetch mergecommit. Чтобы пройти эту проверку, разрешите конфликт, как описано в документации GitHub, или выполните слияние ветки master в ветку вашего pull request с помощью git.

Проверка документации​

Эта проверка пытается собрать сайт документации ClickHouse. Она может завершиться с ошибкой, если вы изменили что-то в документации. Наиболее вероятная причина — некорректная перекрёстная ссылка в документации. Перейдите к отчёту проверки и найдите сообщения ERROR и WARNING.

Проверка описания​

Убедитесь, что описание вашего pull request соответствует шаблону PULL_REQUEST_TEMPLATE.md. Вы должны указать категорию изменения для changelog (например, Bug Fix) и написать понятное пользователю сообщение, описывающее изменение, для CHANGELOG.md

Docker-образ​

Собирает Docker-образы сервера ClickHouse и Keeper, чтобы проверить, что они корректно собираются.

Тесты официальной библиотеки Docker​

Запускает тесты из официальной библиотеки Docker, чтобы проверить, что Docker-образ clickhouse/clickhouse-server работает корректно.

Чтобы добавить новые тесты, создайте каталог ci/jobs/scripts/docker_server/tests/$test_name и скрипт run.sh в нём.

Дополнительные сведения о тестах можно найти в документации по скриптам заданий CI.

Проверка маркера​

Эта проверка означает, что система CI начала обрабатывать pull request. Когда у неё статус «pending», это означает, что ещё не все проверки были запущены. После того как все проверки будут запущены, её статус изменится на «success».

Проверка стиля​

Выполняет различные проверки стиля кода.

В задаче Style Check выполняются следующие базовые проверки:

cpp​

Выполняет простые проверки стиля кода на основе регулярных выражений с помощью скрипта ci/jobs/scripts/check_style/check_cpp.sh (его также можно запускать локально).
Если проверка завершается с ошибкой, исправьте проблемы со стилем в соответствии с руководством по стилю кода.

codespell, aspell​

Проверяют грамматические ошибки и опечатки.

mypy​

Выполняет статическую проверку типов для кода на Python.

Запуск задачи проверки стиля локально​

Всю задачу Style Check можно запустить локально в Docker-контейнере с помощью:

python -m ci.praktika run "Style check"

Чтобы выполнить отдельную проверку (например, проверку cpp):

python -m ci.praktika run "Style check" --test cpp

Эти команды скачивают Docker-образ clickhouse/style-test и запускают задачу в контейнеризованной среде. Дополнительные зависимости не требуются — достаточно Python 3 и Docker.

Запуск stateless-тестов​

Локально установленный ClickHouse с настройками по умолчанию может подходить для отдельных тестовых сценариев, но не позволяет корректно выполнять все тестовые запросы. В CI для каждой задачи используется определенная конфигурация ClickHouse (например, хранилище S3, Parallel Replicas), и вручную воспроизвести ее может быть затруднительно. Чтобы этого избежать, вы можете локально воспроизвести любую задачу CI, используя ту же оркестрацию, что и в CI, — ручная настройка не требуется.

Предварительные требования​

  • Python 3 (только стандартная библиотека)
  • Docker

При необходимости установите Docker в Ubuntu и снова войдите в систему:

sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker "$USER"
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "ip6tables": true
}
EOF
sudo systemctl restart docker

Запустите задание CI локально​

Выберите любое название задания из отчёта CI и запустите его локально:

python -m ci.praktika run "<JOB_NAME>"
  • Всегда указывайте имя задания в кавычках и в точности так, как оно приведено в отчёте CI (оно может содержать пробелы и запятые), например: "Stateless tests (amd_debug, parallel)". Это позволит использовать ту же конфигурацию ClickHouse и запустить те же тесты, что и в CI.
  • Архитектура и тип сборки в имени задания (например, amd_debug) — это специфичные для CI метки. При локальном запуске они ни на что не влияют: задание будет использовать тот бинарный файл, который вы укажете, и ту архитектуру, на которой выполняется запуск. Имя задания определяет только конфигурацию ClickHouse и набор тестов (если не переопределено с помощью --test).
  • В CI функциональные тесты разделены на группы для более эффективного использования ресурсов. Например, "Stateless tests (amd_debug, parallel)" и "Stateless tests (amd_debug, sequential)" вместе охватывают весь объём: тесты, безопасные для параллельного выполнения, запускаются одновременно, а остальные — последовательно. Такое разделение сокращает общее время выполнения в CI, максимально используя параллелизм там, где это возможно. Чтобы локально воспроизвести полный объём тестов, запустите обе группы.
  • Также есть задание CI "Fast test", которое запускает ограниченный набор функциональных тестов для проверки базовой работоспособности ClickHouse — оно использует сборку не со всеми необязательными модулями и является самым быстрым способом выявить регрессии. Его можно запустить локально таким же образом. Поместите бинарный файл ClickHouse в один из путей поиска по умолчанию (./ci/tmp/clickhouse, ./build/programs/clickhouse или ./clickhouse) — в противном случае задание сначала попытается собрать ClickHouse: 
    python -m ci.praktika run "Fast test"

Запуск определённых тестов в рамках задачи CI​

С параметром --test задача подготавливает такую же конфигурацию ClickHouse, как используется в CI, но запускает только выбранные тесты:

python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1
  • Можно передать несколько имён тестов: 
    python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1 00002_log_and_exception_messages_formatting
  • Совет: если подходит любая конфигурация ClickHouse и вам нужно запустить только определённые тесты, используйте псевдоним functional вместо полного имени задачи: 
    python -m ci.praktika run functional --test 00001_select1

Дополнительные параметры настройки​

  • --path PATH — пользовательский путь к исполняемому файлу ClickHouse. По умолчанию средство запуска ищет его в следующем порядке: ./ci/tmp/clickhouse, ./build/programs/clickhouse, ./clickhouse.
  • --count N — повторить каждый тест N раз.
  • --workers N — переопределить автоматически вычисляемое количество параллельных процессов на основе ресурсов машины.

Проверка сборки​

Выполняет сборку ClickHouse в различных конфигурациях для использования на следующих шагах.

Локальный запуск сборки​

Сборку можно запустить локально в среде, имитирующей CI, с помощью:

python -m ci.praktika run "<BUILD_JOB_NAME>"

Помимо Python 3 и Docker, никаких дополнительных зависимостей не требуется.

Доступные задания сборки​

Имена заданий сборки указаны в точности так, как они отображаются в отчёте CI:

Сборки AMD64:

  • Build (amd_debug) - отладочная сборка с символами
  • Build (amd_release) - оптимизированная релизная сборка
  • Build (amd_asan) - сборка с Address Sanitizer
  • Build (amd_tsan) - сборка с Thread Sanitizer
  • Build (amd_msan) - сборка с Memory Sanitizer
  • Build (amd_ubsan) - сборка с Undefined Behavior Sanitizer
  • Build (amd_binary) - быстрая релизная сборка без Thin LTO
  • Build (amd_compat) - совместимая сборка для более старых систем
  • Build (amd_musl) - сборка с musl libc
  • Build (amd_darwin) - сборка для macOS
  • Build (amd_freebsd) - сборка для FreeBSD

Сборки ARM64:

  • Build (arm_release) - оптимизированная релизная сборка ARM64
  • Build (arm_asan) - сборка ARM64 с Address Sanitizer
  • Build (arm_coverage) - сборка ARM64 с инструментированием для покрытия
  • Build (arm_binary) - быстрая релизная сборка ARM64 без Thin LTO
  • Build (arm_darwin) - сборка macOS ARM64
  • Build (arm_v80compat) - сборка совместимости ARMv8.0

Другие архитектуры:

  • Build (ppc64le) - PowerPC, 64-бит, порядок байтов Little Endian
  • Build (riscv64) - RISC-V, 64-бит
  • Build (s390x) - IBM System/390, 64-бит
  • Build (loongarch64) - LoongArch, 64-бит

Если задание выполнено успешно, результаты сборки будут доступны в каталоге <repo_root>/ci/tmp/build.

Примечание: Для сборок, не относящихся к категории «Другие архитектуры» (сборки из категории «Другие архитектуры» используют кросс-компиляцию), архитектура вашей локальной машины должна совпадать с типом сборки, чтобы она была выполнена так, как запрошено в BUILD_JOB_NAME.

Пример​

Чтобы запустить локальную debug-сборку:

python -m ci.praktika run "Build (amd_debug)"

Если описанный выше подход вам не подходит, используйте параметры cmake из лога сборки и следуйте общему процессу сборки.

Functional stateless tests​

Запускает функциональные stateless-тесты для бинарных файлов ClickHouse, собранных в различных конфигурациях — release, debug, с санитайзерами и т. д. Изучите отчёт, чтобы увидеть, какие тесты завершаются с ошибкой, затем воспроизведите сбой локально, как описано здесь. Обратите внимание, что для воспроизведения необходимо использовать правильную конфигурацию сборки — тест может падать под AddressSanitizer, но проходить в Debug. Скачайте бинарный файл со страницы проверок сборки CI или соберите его локально.

Интеграционные тесты​

Выполняет интеграционные тесты.

Проверка исправления ошибки​

Проверяет, что либо добавлен новый тест (функциональный или интеграционный), либо есть изменённые тесты, которые падают при использовании бинарника, собранного из ветки master. Эта проверка запускается, когда у pull request есть метка "pr-bugfix".

Стресс-тест​

Запускает функциональные тесты без сохранения состояния одновременно с нескольких клиентов для выявления ошибок, связанных с конкурентным выполнением. Если тест завершился неуспешно:

  • Сначала исправьте все остальные ошибки тестов;
    • Ознакомьтесь с отчетом, найдите журналы сервера и проверьте их на возможные причины ошибки.

Проверка совместимости​

Проверяет, запускается ли бинарный файл clickhouse на дистрибутивах со старыми версиями libc. Если проверка не проходит, обратитесь за помощью к мейнтейнеру.

AST fuzzer​

Выполняет случайно сгенерированные запросы для обнаружения ошибок в программе. Если он завершится с ошибкой, обратитесь за помощью к мейнтейнеру.

Тесты производительности​

Измеряйте, как изменяется производительность запросов. Это самая длительная проверка, она занимает чуть меньше 6 часов. Отчёт о тестах производительности подробно описан здесь.