Integração Contínua (CI) - ClickHouse Documentation

Quando você envia um pull request, algumas verificações automatizadas são executadas no seu código pelo sistema de integração contínua (CI) do ClickHouse. Isso acontece depois que um mantenedor do repositório (alguém da equipe do ClickHouse) analisa seu código e adiciona o rótulo can be tested ao seu pull request. Os resultados das verificações são exibidos na página do pull request no GitHub, como descrito na documentação sobre verificações do GitHub. Se uma verificação falhar, talvez seja necessário corrigi-la. Esta página apresenta uma visão geral das verificações que você pode encontrar e do que pode fazer para corrigi-las. Se parecer que a falha na verificação não está relacionada às suas alterações, pode ser uma falha transitória ou um problema de infraestrutura. Envie um commit vazio para o pull request para reiniciar as verificações de CI:

git commit --allow-empty
git push

Se não souber o que fazer, peça ajuda a um mantenedor.

Mesclar com master

Verifica se o PR pode ser mesclado na branch master. Caso contrário, a verificação falhará com a mensagem Cannot fetch mergecommit. Para corrigir essa verificação, resolva o conflito conforme descrito na documentação do GitHub ou faça o merge da branch master na branch do seu pull request usando git.

Verificação da documentação

Tenta compilar o site de documentação do ClickHouse. Ela pode falhar se você tiver alterado algo na documentação. O motivo mais provável é que algum link interno na documentação esteja incorreto. Acesse o relatório da verificação e procure as mensagens ERROR e WARNING.

Verificação da descrição

Verifique se a descrição do seu pull request está em conformidade com o modelo PULL_REQUEST_TEMPLATE.md. Você precisa especificar uma categoria de changelog para a sua alteração (por exemplo, correção de bug) e escrever uma mensagem compreensível para o usuário descrevendo a alteração em CHANGELOG.md

Imagem Docker

Compila as imagens Docker do servidor ClickHouse e do Keeper para verificar se foram compiladas corretamente.

Testes oficiais da biblioteca do Docker

Executa os testes da biblioteca oficial do Docker para verificar se a imagem Docker clickhouse/clickhouse-server funciona corretamente. Para adicionar novos testes, crie um diretório ci/jobs/scripts/docker_server/tests/$test_name e o script run.sh nele. Mais detalhes sobre os testes podem ser encontrados na documentação dos scripts de jobs de CI.

Verificação de marcador

Esta verificação indica que o sistema de CI começou a processar o pull request. Quando ela está com status ‘pending’, isso significa que ainda nem todas as verificações foram iniciadas. Depois que todas as verificações forem iniciadas, o status muda para ‘success’.

Style verificação

Executa várias verificações de estilo na base de código. Verificações básicas no job Style Verificação:

cpp

Executa verificações simples de estilo de código com base em regex usando o script ci/jobs/scripts/check_style/check_cpp.sh (que também pode ser executado localmente). Se falhar, corrija os problemas de estilo de acordo com o guia de estilo de código.

codespell, aspell

Verifique se há erros de gramática e de digitação.

mypy

Realiza a verificação estática de tipos em código Python.

Executando localmente o job Style Verificação

Todo o job Style Verificação pode ser executado localmente em um contêiner Docker com:

python -m ci.praktika run "Style check"

Para executar uma verificação específica (por exemplo, a verificação de cpp):

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

Esses comandos baixam a imagem Docker clickhouse/style-test e executam o job em um ambiente em contêiner. Não são necessárias dependências além de Python 3 e Docker.

Executando testes sem estado

Uma instalação local do ClickHouse com as configurações padrão pode funcionar para casos de teste específicos, mas não consegue executar corretamente todas as consultas de teste. Na CI, cada job instala uma configuração específica do ClickHouse (por exemplo, armazenamento S3, réplicas paralelas), o que pode ser trabalhoso reproduzir manualmente. Para evitar isso, você pode reproduzir localmente qualquer job da CI usando a mesma orquestração da CI — sem precisar de configuração manual.

Pré-requisitos

Python 3 (apenas a biblioteca padrão)
Docker

Instale o Docker no Ubuntu, se necessário, e faça login novamente:

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

Execute um job de CI localmente

Escolha o nome de qualquer job em um relatório de CI e execute-o localmente:

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

Sempre coloque o nome do job entre aspas exatamente como ele aparece no relatório de CI (ele pode conter espaços e vírgulas), por exemplo: "Stateless tests (amd_debug, parallel)". Isso define a mesma configuração do ClickHouse e executa os mesmos testes da CI.
A arquitetura e o tipo de build no nome do job (por exemplo, amd_debug) são rótulos específicos da CI. Ao executar localmente, eles não têm efeito — o job usará o binário que você fornecer, na arquitetura em que estiver rodando. O nome do job determina apenas a configuração do ClickHouse e o conjunto de testes (a menos que isso seja sobrescrito com --test).
Na CI, os testes funcionais são divididos em lotes para melhor aproveitamento de recursos. Por exemplo, "Stateless tests (amd_debug, parallel)" e "Stateless tests (amd_debug, sequential)" juntos cobrem todo o escopo: os testes seguros para paralelismo são executados de forma concorrente, e o restante é executado de forma sequencial. Essa divisão reduz o tempo total da CI ao maximizar o paralelismo sempre que possível. Para reproduzir localmente todo o escopo de testes, execute ambos os lotes.
Também existe um job de CI, "Fast test", que executa um escopo limitado de testes funcionais para verificar a funcionalidade básica do ClickHouse — ele usa uma build sem todos os módulos opcionais e é a forma mais rápida de detectar regressões. Você pode executá-lo localmente da mesma forma. Coloque o binário do ClickHouse em um dos caminhos de busca padrão (./ci/tmp/clickhouse, ./build/programs/clickhouse ou ./clickhouse) — caso contrário, o job tentará compilar o ClickHouse primeiro:
```
python -m ci.praktika run "Fast test"
```

Executar testes específicos em um job de CI

Com --test, o job prepara um ambiente do ClickHouse idêntico ao usado na CI, mas executa apenas os testes selecionados:

python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1

Você pode informar vários nomes de teste:

python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1 00002_log_and_exception_messages_formatting

Dica: Se qualquer configuração do ClickHouse servir e você só precisar executar testes específicos, use o alias functional em vez do nome completo do job:
```
python -m ci.praktika run functional --test 00001_select1
```

Opções adicionais de personalização

--path PATH — caminho personalizado para o binário do ClickHouse. Por padrão, o runner procura nesta ordem: ./ci/tmp/clickhouse, ./build/programs/clickhouse, ./clickhouse.
--count N — repete cada teste N vezes.
--workers N — substitui o cálculo automático do número de workers paralelos com base na capacidade da máquina.

Verificação de build

Compila o ClickHouse em diferentes configurações para uso nas etapas seguintes.

Executando builds localmente

A build pode ser executada localmente em um ambiente semelhante ao de CI com:

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

Nenhuma dependência além de Python 3 e Docker é necessária.

Jobs de compilação disponíveis

Os nomes dos jobs de compilação são exatamente os mesmos exibidos no relatório de CI: Builds AMD64:

Build (amd_debug) - Build de depuração com símbolos
Build (amd_release) - Build de release otimizada
Build (amd_asan) - Build com Address Sanitizer
Build (amd_tsan) - Build com Thread Sanitizer
Build (amd_msan) - Build com Memory Sanitizer
Build (amd_ubsan) - Build com Undefined Behavior Sanitizer
Build (amd_binary) - Build de release rápida sem Thin LTO
Build (amd_compat) - Build de compatibilidade para sistemas mais antigos
Build (amd_musl) - Build com musl libc
Build (amd_darwin) - Build para macOS
Build (amd_freebsd) - Build para FreeBSD

Builds ARM64:

Build (arm_release) - Build de release otimizada para ARM64
Build (arm_asan) - Build ARM64 com Address Sanitizer
Build (arm_coverage) - Build ARM64 com instrumentação de cobertura
Build (arm_binary) - Build de release rápida para ARM64 sem Thin LTO
Build (arm_darwin) - Build ARM64 para macOS
Build (arm_v80compat) - Build de compatibilidade para ARMv8.0

Outras arquiteturas:

Build (ppc64le) - PowerPC de 64 bits Little Endian
Build (riscv64) - RISC-V de 64 bits
Build (s390x) - IBM System/390 de 64 bits
Build (loongarch64) - LoongArch de 64 bits

Se o job for concluído com sucesso, os resultados da compilação estarão disponíveis no diretório <repo_root>/ci/tmp/build. Observação: Para builds que não estejam na categoria “Outras arquiteturas” (que usam compilação cruzada), a arquitetura da sua máquina local deve corresponder ao tipo de build para gerar a compilação solicitada por BUILD_JOB_NAME.

Exemplo

Para executar uma build local de depuração:

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

Se a abordagem acima não funcionar para você, use as opções do cmake presentes no log de compilação e siga o processo geral de compilação.

Testes funcionais sem estado

Executa testes funcionais sem estado para binários do ClickHouse compilados em várias configurações — release, debug, com sanitizers etc. Consulte o relatório para ver quais testes falham e, em seguida, reproduza a falha localmente, conforme descrito aqui. Observe que é preciso usar a configuração de build correta para reproduzir — um teste pode falhar com o AddressSanitizer, mas passar em Debug. Baixe o binário na página de verificações de build do CI ou compile-o localmente.

Testes de integração

Executa os testes de integração.

Verificação de validação de correção de bug

Verifica se há um novo teste (funcional ou de integração) ou testes alterados que falham com o binário compilado na branch master. Esta verificação é acionada quando o pull request tem o rótulo “pr-bugfix”.

Teste de estresse

Executa testes funcionais sem estado em paralelo a partir de vários clientes para detectar erros relacionados à concorrência. Se falhar:

Corrija primeiro todas as outras falhas de teste;
- Consulte o relatório para localizar os logs do servidor e verifique-os em busca de possíveis causas do erro.

Verificação de compatibilidade

Verifica se o binário clickhouse roda em distribuições com versões antigas da libc. Se falhar, peça ajuda a um mantenedor.

AST fuzzer

Executa consultas geradas aleatoriamente para identificar erros no programa. Se falhar, peça ajuda a um mantenedor.

Testes de desempenho

Meça as mudanças no desempenho das consultas. Esta é a verificação mais demorada e leva pouco menos de 6 horas para ser executada. O relatório do teste de desempenho é descrito em detalhes aqui.

​Mesclar com master

​Verificação da documentação

​Verificação da descrição

​Imagem Docker

​Testes oficiais da biblioteca do Docker

​Verificação de marcador

​Style verificação

cpp

codespell, aspell

mypy

​Executando localmente o job Style Verificação

​Executando testes sem estado

​Pré-requisitos

​Execute um job de CI localmente

​Executar testes específicos em um job de CI

​Opções adicionais de personalização

​Verificação de build

​Executando builds localmente

​Jobs de compilação disponíveis

​Exemplo

​Testes funcionais sem estado

​Testes de integração

​Verificação de validação de correção de bug

​Teste de estresse

​Verificação de compatibilidade

​AST fuzzer

​Testes de desempenho