Qué cambia cuando tu schema de ClickHouse® es código
Si trabajas con Postgres o MySQL, seguramente llevas años sin escribir una migración a mano. Tocas un fichero de schema, una herramienta calcula el diff, genera el SQL y te tumba la CI si producción se ha desviado por su cuenta de lo que dice el repo. Es la versión aburrida y resuelta de gestionar un schema. Y que algo que modifica tu base de datos sea aburrido es lo mejor que se puede decir de ello.
Ahora abre tu proyecto de ClickHouse®. Vuelta a escribir DDL a mano, a revisar diffs a ojo y a enterarte del drift cuando una query peta en producción.
No es que ClickHouse no tenga herramientas de migración, es que ninguna se ha convertido en la opción por defecto, la que un equipo coge sin pensar, como pasa en el mundo relacional. Casi todo lo que hay son SQL runners: aplican los ficheros que escribes y registran cuáles se han ejecutado, pero el que calcula el diff sigues siendo tú. Tú decides qué ha cambiado, y tú rezas para que dev y prod no se hayan desincronizado.
Nos cansamos de ser el motor de diffs. Así que hicimos CHKit, y lo publicamos como open source. Este post no es un tour de features. Va de lo que cambia de verdad en tu día a día cuando el schema de ClickHouse vive en código.
Por qué lo hicimos
En nuestra empresa anterior, Numia, teníamos ClickHouse a escala de casi un petabyte, detrás de APIs en tiempo real sobre datos de blockchain. El motor casi nunca era el problema. El problema era todo lo demás, y la gestión del schema estaba entre lo primero de la lista.
Cada cambio era DDL escrito a mano y revisado a ojo. La forma real de una tabla era la que saliera de aplicar el montón de ficheros de migración. Un ALTER lanzado a mano en mitad de un incidente nunca acababa en control de versiones, y nada nos avisaba de que el código y la base de datos ya no coincidían. Escribimos un montón de tooling para ir tapando el problema: health checks, scripts, guardarraíles.
Pero el problema del schema seguía ahí, y la causa de fondo era que no teníamos schema-as-code como en Postgres. Y lo construimos nosotros. Si quieres la versión larga de por qué, y de por qué decidimos liberarlo, tienes un post complementario en el blog de CHKit. Aquí me quiero centrar en lo práctico.
Tu schema de ClickHouse como código
chkit define tus tablas, vistas y vistas materializadas de ClickHouse en TypeScript (Python, muy pronto). Esta es una tabla real, con lo que de verdad configuras en producción:
import { schema, table } from '@chkit/core'
const events = table({
database: 'analytics',
name: 'events',
columns: [
{ name: 'id', type: 'UInt64' },
{ name: 'org_id', type: 'String' },
{ name: 'event', type: 'LowCardinality(String)' },
{ name: 'received_at', type: 'DateTime64(3)' },
{ name: 'payload', type: 'String', codec: [{ kind: 'ZSTD', level: 3 }] },
],
engine: 'MergeTree()',
orderBy: ['org_id', 'received_at'],
primaryKey: ['org_id', 'received_at'],
partitionBy: 'toYYYYMM(received_at)',
ttl: 'received_at + INTERVAL 90 DAY',
})
export default schema(events)
Ese es el estado deseado de tu base de datos, con tipos comprobados y listo para revisar en un pull request. Alrededor hay un ciclo de tres comandos. chkit generate compara tus definiciones con el último snapshot y escribe un fichero SQL con la migración. chkit migrate --apply ejecuta las migraciones pendientes. chkit drift inspecciona la base de datos en vivo y te dice en qué difiere de tu código. Otros dos se ganan su sitio en CI: chkit check rompe el build si hay migraciones pendientes, drift o una migración editada, y chkit codegen genera tipos de fila en TypeScript a partir de las mismas definiciones.
No es un ORM. Las queries las sigues escribiendo tú en SQL. CHKit se ocupa del schema, las migraciones y los guardarraíles, y de nada más.
Una cosa, para ser claros: está en beta. La CLI y el DSL de schema son estables y ya mueven nuestras cargas de producción, pero antes de la 1.0 aún puede haber algún breaking change menor. La referencia completa está en la documentación de chkit.
Qué cambia cuando el schema es código
Esta es la parte que importa, y la razón de que esto merezca un post.
Dejas de escribir migraciones a mano
Cambias el TypeScript y lanzas chkit generate. Compara el estado nuevo con el anterior, calcula las operaciones necesarias y en qué orden, y te escribe el SQL. Si no ha cambiado nada, no escribe nada.
El fichero de migración deja de ser algo que redactas y pasa a ser algo que revisas. Tu trabajo ya no es «escribir el ALTER correcto para este cambio», sino «leer lo que propone CHKit y darle el visto bueno». En un schema que se toca a menudo, es la diferencia entre una tarde con lupa y un pull request de treinta segundos.
El drift pasa a bloquear la CI en vez de darte un susto a las 3 de la mañana
Solo por esto ya merece la pena la herramienta.
El fallo siempre es el mismo. Alguien arregla un incidente a las 3 de la mañana lanzando un ALTER directamente contra producción. Funciona. Se cierra el incidente. El cambio nunca llega a un fichero de migración, y a partir de ahí tu repo y tu base de datos no coinciden, sin que nadie se entere, hasta que semanas después un deploy hace algo que nadie sabe explicar.
chkit drift lee la base de datos en vivo y la compara, columna a columna, con tu código. Detecta la columna que falta, el TTL que alguien cambió y la sorting key que no es la que tu repo cree. Mete chkit check en la CI y esa comparación se ejecuta en cada pull request, así que el ALTER de las 3 de la mañana aparece a la mañana siguiente como una diferencia concreta, con nombre y apellidos, y no como la vaga sensación de que algo no cuadra. No se trata de que la gente deje de tocar producción. Lo va a seguir haciendo. Se trata de que la base de datos ya no pueda ocultarte nada.
Los cambios destructivos no se cuelan, y los estructurales se ven venir
Bajo «cambio de schema» se esconden dos problemas distintos, y ClickHouse los trata de forma muy diferente.
Algunos cambios son ediciones de metadatos baratas: añadir una columna, cambiar un TTL, añadir un índice. Otros reescriben la tabla. Cambiar el engine, el ORDER BY, el particionado o la clave primaria no se puede hacer sobre la tabla existente. ClickHouse no tiene ALTER para eso. La única vía es crear una tabla nueva, copiar los datos e intercambiarlas. Si alguna vez has cambiado la sorting key de una tabla grande y has acabado pasándote la tarde con INSERT SELECT, sabes perfectamente de qué hablo. (Explicamos por qué el orden de la sorting key importa tanto en nuestro post sobre optimización de queries.)
CHKit clasifica cada operación de un plan como safe, caution o danger, y distingue las reescrituras estructurales de las ediciones que se aplican sobre la propia tabla. Un DROP COLUMN, un DROP TABLE, cualquier cosa que destruya datos, se marca como danger y se bloquea. En un terminal interactivo te pide confirmación. En CI termina con un código de salida distinto de cero y no ejecuta nada salvo que pases explícitamente --allow-destructive. Ese control también analiza el SQL escrito a mano, no solo las migraciones que ha generado CHKit, por lo que no hay forma de colarle un DROP a pelo.
Los tipos de tu aplicación dejan de desincronizarse del schema
chkit codegen genera tipos de fila en TypeScript a partir de las mismas definiciones de las que salen tus tablas. Añade chkit codegen --check a la CI y el build fallará en cuanto los tipos de la aplicación y el schema de la base de datos se desincronicen. Es el mismo problema de drift de antes, una capa más arriba, y se resuelve igual.
¿Qué no hace CHKit?
Un post de lanzamiento que solo cuenta lo bueno es marketing. Estos son los límites.
CHKit gestiona el schema, es decir, DDL. No mueve tus datos. Hay un plugin opcional de backfill para copias por ventanas de tiempo con checkpoints, pero tienes que activarlo tú, no forma parte del ciclo básico de migrate, y no hace fácil lo difícil. Reestructurar una tabla grande sigue siendo una migración de datos en toda regla que tienes que planificar. Con eso se pelea todo el mundo en este terreno.
Además, por defecto genera DDL para un solo nodo. Si tienes un cluster replicado con Keeper, la replicación la gestionas tú (tenemos previsto añadirlo próximamente). Y un par de comodidades, como el uniqueKey gestionado, solo funcionan con el engine de ObsessionDB. CHKit funciona con cualquier ClickHouse, pero lo exclusivo de Cloud es exactamente eso, exclusivo.
Por último, CHKit no puede deshacer una mutación de ClickHouse. Lo que sí hace es avisarte, antes de que ejecutes nada, de que ese cambio de apariencia inocente en tu diff es en realidad una reescritura completa de la tabla. Los datos se van a mover igual. Solo que ya no te enteras un viernes por la tarde.
La regla que conviene recordar
Si te quedas con una sola idea, que sea esta: schema-as-code compensa en cuanto más de una persona, o más de un entorno, puede modificar tus tablas. Un solo ingeniero con un solo cluster puede apañarse con una carpeta de migraciones y buenos hábitos. Un equipo con staging y prod separados, y una pipeline de CI capaz de lanzar un ALTER, no. Ahí es donde el drift deja de ser una hipótesis.
Y cuando un diff vuelva marcado como danger o estructural, para y léelo. Es CHKit diciéndote que ese cambio mueve datos. Yo planificaría el backfill antes de aprobarlo, siempre, en lugar de descubrir la reescritura en producción.
El mundo relacional dejó de escribir migraciones a mano hace mucho tiempo. ClickHouse no tiene por qué ser la excepción.
Pruébalo
CHKit tiene licencia MIT y funciona con cualquier ClickHouse: Cloud, Altinity, self-hosted y ObsessionDB. Puedes montar un proyecto a partir de un ejemplo funcional con un solo comando:
npm create chkit@latest
El código está en GitHub. Si usas ClickHouse y sigues gestionando el schema a mano, lo hemos hecho para que dejes de hacerlo. Y si quieres ClickHouse gestionado sin el peaje operativo que dio origen a toda esta historia, a eso nos dedicamos en ObsessionDB.
Nos encantaría saber cómo gestionas hoy los cambios de schema en ClickHouse, sobre todo el drift y los ALTER destructivos. Abre un issue y cuéntanos qué echas en falta.
Seguir Leyendo
Publicado originalmente en obsessionDB. Lee el artículo original aquí.
ClickHouse is a registered trademark of ClickHouse, Inc. https://clickhouse.com