devgo.cn用过 ClickHouse 的人大概都有过这种经历：业务跑得好好的，突然要加一列、改排序键或者重建物化视图，你就得手动写一串 ALTER TABLE 或 CREATE MATERIALIZED VIEW 的 SQL。一次两次还行，次数多了就开始乱——谁改过什么、线上是不是和代码里的定义已经不一致了、历史数据要不要重放，全靠脑子记。再加上 ClickHouse 的 DDL 不少是有副作用的（比如改排序键要重写数据），一个手滑，几千万行就得重来。chkit 这个新出的开源工具，就是冲着这个痛点来的。它是一个 TypeScript 写的 ClickHouse schema 管理 CLI，思路和 Drizzle（Node 生态里很流行的 SQL 迁移工具）很像：你在代码里用 TS 定义好表、视图、物化视图和字典，它帮你生成可审查的 SQL 迁移文件，还能从终端或 CI 里检测线上 schema 是否和定义发生漂移。整个工作流是 define → generate → review → migrate → check，一环扣一环，把过去靠人肉的流程变成了自动化流水线。
先看它是怎么用的。项目里装两个包：CLI 叫 `chkit`，核心库叫 `@chkit/core`。你需要提供一个 `clickhouse.config.ts`，在里面指定 schema 目录、输出目录，还有数据库连接（通过 `CLICKHOUSE_URL`、`CLICKHOUSE_USER`、`CLICKHOUSE_PASSWORD` 和 `CLICKHOUSE_DB` 这些环境变量注入）。值得注意的一点是，它允许密码为空字符串但拒绝缺失，避免你误把空密码当成没配置。定义表很简单，从 `@chkit/core` 导入 `schema` 和 `table`，然后用普通 TS 对象描述列、引擎、主键、排序键和分区键。比如一个事件表：`engine: 'MergeTree'`，三列 `id`、`source`、`occurred_at`，`primaryKey: ['id']`，`partitionBy: 'toYYYYMM(occurred_at)'`。写完定义，跑 `chkit generate --name create-events`，它会在 `chkit/migrations` 目录下生成一个 .sql 文件，内容是标准的 CREATE TABLE 语句。接下来 `chkit migrate --json` 预览未应用的迁移，确认没问题后 `--apply` 真正执行。最后 `chkit status --json` 看当前状态，`chkit check --strict --json` 做严格校验——如果有待迁移、checksum 变了或线上有漂移，它会以非零退出码失败，正好用来当 CI 的门禁。
这套流程的好处是迁移文件是生成且可审查的，你可以在提交前打开 SQL 看一眼，和手工写的区别不大，但生成逻辑是确定性的，不容易漏掉 `ON CLUSTER` 或者 `ENGINE =` 这类细节。而且它把迁移历史和当前 schema 的快照（存在 `chkit/meta/snapshot.json`）一并提交到 Git，这样团队里任何人都能知道线上到底长什么样。对于已经跑着的生产库，它还提供了“采用”指南，不是让你重新生成一套 schema 覆盖，而是先把现有表导进来，建立迁移基线，之后再走增量迁移。这非常实用——很多工具都只处理从零开始的绿地项目，生产环境的存量数据库才是大多数人的真实处境。
chkit 还带了一组插件，覆盖常见场景。`@chkit/plugin-pull` 能把线上 schema 直接导入成 TS 定义，反过来同步；`@chkit/plugin-codegen` 能根据表结构生成 TypeScript 行类型和 Zod 校验 schema，省得手写重复的类型定义；`@chkit/plugin-backfill` 是 beta 功能，专门做带检查点的分区/排序键回填——就是那种把老数据按新规则重排、重放到物化视图里的操作，它能把回填切成小块，每块完成后留个进度标记，失败还能续跑，比一次性大事务稳妥太多。另外还有 `@chkit/plugin-obsessiondb`，连的是他们自己家的 ObsessionDB 服务；Python 支持也在 alpha 阶段，叫 `chkit-py`。
最让我意外的是它对数据安全的态度。文档里明确说“永远不要修改已经记录为 applied 的 SQL”，而且为“改变排序键或分区键”这类危险操作准备了专门的“数据保留迁移”教程，要求你审查数据复制和恢复计划之后再执行。这种谨慎不是每个迁移工具都有——很多工具只关心 SQL 能不能跑通，不关心数据会不会丢。另外，在生成最初迁移时，如果目标库已经存在，它生成的 SQL 会包含 `CREATE DATABASE`，但你可以在应用前把那句删掉，只保留建表语句，避免权限问题。这些细节说明作者是真在生产环境用过 ClickHouse 的。
对普通开发者来说，chkit 最直接的价值是把 ClickHouse 的 schema 管理从“手写 SQL 加人肉记忆”提升到“代码即定义、迁移可评审、漂移可检测”的现代工程化层次。适用场景很清晰：你的团队已经在用 TypeScript 写后端，或者你维护多个 ClickHouse 环境需要统一管理，又或者你经常要改表结构怕出事故——都可以试试。需要注意的坑是：和 Drizzle 类似，它目前只支持通过 HTTP(S) 接口连 ClickHouse，需要 Node.js 22+，而且工具本身还在发展，backfill 插件还是 beta，生产环境用的话先在小库上验证。整体看下来，chkit 把 ClickHouse 的 schema 生命周期管理拉到了和 Postgres 生态（比如 Prisma、Drizzle）同一水平线，值得关注。
内容与图片版权归原作者所有 · 原文: https://github.com/obsessiondb/chkit