Integración continua (CI)

Descripción general del sistema de integración continua de ClickHouse

Cuando envías un pull request, el sistema de integración continua (CI) de ClickHouse ejecuta algunas comprobaciones automatizadas sobre tu código. Esto ocurre después de que un responsable del repositorio (alguien del equipo de ClickHouse) haya revisado tu código y haya añadido la etiqueta can be tested a tu pull request. Los resultados de las comprobaciones aparecen en la página del pull request de GitHub, como se describe en la documentación sobre comprobaciones de GitHub. Si una comprobación falla, puede que tengas que corregirla. Esta página ofrece una descripción general de las comprobaciones con las que te puedes encontrar y de lo que puedes hacer para corregirlas.

Si parece que el fallo de la comprobación no está relacionado con tus cambios, puede tratarse de un fallo transitorio o de un problema de infraestructura. Haz push de un commit vacío al pull request para reiniciar las comprobaciones de CI:

git commit --allow-empty
git push

Si no estás seguro de qué hacer, pide ayuda a un responsable del proyecto.

​

Fusionar con master

Verifica que la PR pueda fusionarse con master. Si no es así, fallará con el mensaje Cannot fetch mergecommit. Para corregir esta comprobación, resuelve el conflicto como se describe en la documentación de GitHub, o fusiona la rama master en la rama de tu pull request usando git.

​

Comprobación de la documentación

Intenta compilar el sitio web de documentación de ClickHouse. Puede fallar si has cambiado algo en la documentación. La causa más probable es que algún enlace interno de la documentación sea incorrecto. Ve al informe de la comprobación y busca mensajes ERROR y WARNING.

​

Comprobación de la descripción

Comprueba que la descripción de tu pull request se ajuste a la plantilla PULL_REQUEST_TEMPLATE.md. Tienes que especificar una categoría del changelog para tu cambio (por ejemplo, Corrección de errores) y escribir un mensaje claro para el usuario que describa el cambio para CHANGELOG.md

​

Imagen de Docker

Compila las imágenes de Docker del servidor de ClickHouse y de Keeper para verificar que se compilan correctamente.

​

Pruebas oficiales de la biblioteca de Docker

Ejecuta las pruebas de la biblioteca oficial de Docker para verificar que la imagen de Docker clickhouse/clickhouse-server funcione correctamente.

Para añadir nuevas pruebas, crea un directorio ci/jobs/scripts/docker_server/tests/$test_name y el script run.sh allí.

Puedes encontrar más detalles sobre las pruebas en la documentación de los scripts de jobs de CI.

​

Comprobación de marcador

Esta comprobación significa que el sistema de CI ha comenzado a procesar el pull request. Cuando tiene el estado ‘pending’, significa que aún no se han iniciado todas las comprobaciones. Una vez iniciadas todas las comprobaciones, el estado cambia a ‘success’.

​

Comprobación de estilo

Realiza varias comprobaciones de estilo en la base de código.

Comprobaciones básicas del job Style Check:

cpp

Realiza comprobaciones sencillas del estilo de código basadas en expresiones regulares mediante el script ci/jobs/scripts/check_style/check_cpp.sh (que también puede ejecutarse localmente). Si falla, corrige los problemas de estilo según la guía de estilo de código.

codespell, aspell

Comprueba si hay errores gramaticales y erratas.

mypy

Realiza la comprobación estática de tipos del código Python.

​

Ejecutar localmente el job de comprobación de estilo

El job completo de Style Check puede ejecutarse localmente en un contenedor Docker con:

python -m ci.praktika run "Style check"

Para ejecutar una comprobación específica (p. ej., la comprobación cpp):

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

Estos comandos descargan la imagen de Docker clickhouse/style-test y ejecutan el job en un entorno contenerizado. No se requieren dependencias aparte de Python 3 y Docker.

​

Ejecución de pruebas sin estado

Una instalación local de ClickHouse con la configuración predeterminada puede funcionar para algunos casos de prueba concretos, pero no puede ejecutar correctamente todas las consultas de prueba. En CI, cada job instala una configuración específica de ClickHouse (por ejemplo, almacenamiento S3 o réplicas paralelas), lo que puede ser engorroso de reproducir manualmente. Para evitarlo, puedes reproducir cualquier job de CI en local usando la misma orquestación que en CI, sin necesidad de configuración manual.

​

Requisitos previos

• Python 3 (solo la biblioteca estándar)
• Docker

Instala Docker en Ubuntu si es necesario y vuelve a iniciar sesión:

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

​

Ejecutar un job de CI localmente

Elige el nombre de cualquier job de un informe de CI y ejecútalo localmente:

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

• Pon siempre entre comillas el nombre del job exactamente como aparece en el informe de CI (puede contener espacios y comas), p. ej.: "Stateless tests (amd_debug, parallel)". Esto aplica la misma configuración de ClickHouse y ejecuta las mismas pruebas que en CI.
• La arquitectura y el tipo de compilación del nombre del job (p. ej., amd_debug) son etiquetas específicas de CI. Al ejecutarlo localmente, no tienen ningún efecto: el job usará el binario que proporciones, en la arquitectura en la que lo estés ejecutando. El nombre del job solo determina la configuración de ClickHouse y el conjunto de pruebas (salvo que se sobrescriba con --test).
• En CI, las pruebas funcionales se dividen en lotes para aprovechar mejor los recursos. Por ejemplo, "Stateless tests (amd_debug, parallel)" y "Stateless tests (amd_debug, sequential)" cubren conjuntamente todo el alcance: las pruebas seguras para ejecutarse en paralelo se ejecutan de forma concurrente, y el resto se ejecuta de forma secuencial. Esta división reduce el tiempo total de CI al maximizar el paralelismo siempre que sea posible. Para reproducir localmente todo el alcance de las pruebas, ejecuta ambos lotes.
• También hay un job de CI "Fast test" que ejecuta un conjunto limitado de pruebas funcionales para verificar la funcionalidad básica de ClickHouse: usa una compilación sin todos los módulos opcionales y es la forma más rápida de detectar regresiones. Puedes ejecutarlo localmente de la misma manera. Coloca tu binario de ClickHouse en una de las rutas de búsqueda predeterminadas (./ci/tmp/clickhouse, ./build/programs/clickhouse, o ./clickhouse); de lo contrario, el job intentará compilar ClickHouse primero:
  python -m ci.praktika run "Fast test"
  

​

Ejecutar pruebas específicas dentro de un job de CI

Con --test, el job prepara la misma configuración de ClickHouse que se usa en CI, pero ejecuta solo las pruebas seleccionadas:

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

• Puedes pasar varios nombres de pruebas:
  python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
    --test 00001_select1 00002_log_and_exception_messages_formatting
  
• Consejo: Si te sirve cualquier configuración de ClickHouse y solo necesitas ejecutar pruebas específicas, usa el alias functional en lugar del nombre completo del job:
  python -m ci.praktika run functional --test 00001_select1
  

​

Opciones adicionales de personalización

• --path PATH — ruta personalizada al binario de ClickHouse. De forma predeterminada, el ejecutor busca en este orden: ./ci/tmp/clickhouse, ./build/programs/clickhouse, ./clickhouse.
• --count N — repite cada prueba N veces.
• --workers N — reemplaza el cálculo automático del número de workers en paralelo en función de la capacidad de la máquina.

​

Comprobación de compilación

Compila ClickHouse en distintas configuraciones para usarlo en los pasos siguientes.

​

Ejecutar compilaciones en local

La compilación puede ejecutarse localmente en un entorno similar al de CI mediante:

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

No se requieren más dependencias que Python 3 y Docker.

​

Jobs de compilación disponibles

Los nombres de los jobs de compilación son exactamente los que aparecen en el informe de CI:

Compilaciones AMD64:

• Build (amd_debug) - Compilación de depuración con símbolos
• Build (amd_release) - Compilación optimizada de release
• Build (amd_asan) - Compilación con Address Sanitizer
• Build (amd_tsan) - Compilación con Thread Sanitizer
• Build (amd_msan) - Compilación con Memory Sanitizer
• Build (amd_ubsan) - Compilación con Undefined Behavior Sanitizer
• Build (amd_binary) - Compilación rápida de release sin Thin LTO
• Build (amd_compat) - Compilación de compatibilidad para sistemas más antiguos
• Build (amd_musl) - Compilación con musl libc
• Build (amd_darwin) - Compilación para macOS
• Build (amd_freebsd) - Compilación para FreeBSD

Compilaciones ARM64:

• Build (arm_release) - Compilación optimizada de release para ARM64
• Build (arm_asan) - Compilación con Address Sanitizer para ARM64
• Build (arm_coverage) - Compilación para ARM64 con instrumentación de cobertura
• Build (arm_binary) - Compilación rápida de release para ARM64 sin Thin LTO
• Build (arm_darwin) - Compilación para macOS ARM64
• Build (arm_v80compat) - Compilación de compatibilidad para ARMv8.0

Otras arquitecturas:

• 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

Si el job se completa correctamente, los resultados de la compilación estarán disponibles en el directorio <repo_root>/ci/tmp/build.

Nota: En las compilaciones que no pertenecen a la categoría “Otras arquitecturas” (que usan compilación cruzada), la arquitectura de la máquina local debe coincidir con el tipo de compilación para generar la compilación solicitada por BUILD_JOB_NAME.

​

Ejemplo

Para ejecutar una compilación local en modo depuración:

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

Si el método anterior no le funciona, use las opciones de cmake del registro de compilación y siga el proceso general de compilación.

​

Pruebas funcionales sin estado

Ejecuta pruebas funcionales sin estado para binarios de ClickHouse compilados con varias configuraciones: release, debug, con sanitizers, etc. Consulta el informe para ver qué pruebas fallan y, a continuación, reproduce el fallo localmente como se describe aquí. Ten en cuenta que debes usar la configuración de compilación correcta para reproducirlo: una prueba puede fallar con AddressSanitizer, pero pasar en Debug. Descarga el binario desde la página de comprobaciones de compilación de CI o compílalo localmente.

​

Pruebas de integración

Ejecuta las pruebas de integración.

​

Comprobación de validación de correcciones de errores

Comprueba que haya una prueba nueva (funcional o de integración) o alguna prueba modificada que falle con el binario compilado en la rama master. Esta comprobación se activa cuando la pull request tiene la etiqueta “pr-bugfix”.

​

Prueba de estrés

Ejecuta pruebas funcionales sin estado de forma concurrente desde varios clientes para detectar errores de concurrencia. Si falla:

• Primero, corrige todos los demás fallos de las pruebas;
  • Consulta el informe para encontrar los logs del servidor y revísalos para identificar posibles causas del error.

​

Comprobación de compatibilidad

Verifica que el binario clickhouse funcione en distribuciones con versiones antiguas de libc. Si falla, pide ayuda a un mantenedor.

​

AST fuzzer

Ejecuta consultas generadas aleatoriamente para detectar errores del programa. Si falla, pide ayuda a un responsable del proyecto.

​

Pruebas de rendimiento

Mide los cambios en el rendimiento de las consultas. Esta es la comprobación más larga y tarda algo menos de 6 horas en ejecutarse. El informe de pruebas de rendimiento se describe en detalle aquí.