用途：在 CI 中针对真实 ClickHouse 实例运行集成测试，无需 mock 即可验证 schema 与查询行为。工作流会启动 clickhouse/clickhouse-server 容器、应用 schema，再运行单元与集成测试。
主要能力：产出四类文件——GitHub Actions 工作流、共享测试设置、集成/schema 测试文件，以及串联它们的 package.json 脚本。工作流核心是 services.clickhouse 块，含健康检查与测试前的 schema 应用步骤；共享设置 tests/setup-integration.ts 创建 @clickhouse/client，在 beforeAll 中 ping 以快速失败，测试间 TRUNCATE，afterAll 关闭；集成测试覆盖插入→聚合→断言、参数化查询与空结果；schema 测试通过 system.columns / system.tables 断言列类型与表引擎。可选通过 strategy.matrix 覆盖多个 ClickHouse 版本以发现行为漂移。
使用方式：先阅读现有 .github/workflows/ 与 package.json，再创建或编辑上述文件。工作流示例： services: clickhouse: image: clickhouse/clickhouse-server:latest ports: ["8123:8123", "9000:9000"] options: >- --health-cmd "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1" --health-interval 10s --health-timeout 5s --health-retries 5 在 package.json 添加 test、test:integration、test:ci 脚本。
适用场景：需要在 push/PR 时对真实 ClickHouse 做 schema 与查询验证的项目。
限制与前提：需启用 Actions 的 GitHub 仓库、依赖中含 @clickhouse/client、使用 vitest 或 jest。常见问题包括容器启动慢导致服务不健康（增加 health-retries）、未先运行 schema 步骤、共享状态导致测试顺序不稳定（用 beforeEach 加 TRUNCATE）、端口冲突（改用随机端口映射）。完整可运行示例见 references/implementation.md 与 references/examples.md。