{"_id":"@ai2robotics/ch-upgrade","name":"@ai2robotics/ch-upgrade","dist-tags":{"beta":"0.0.6","latest":"0.0.6"},"versions":{"0.0.6":{"name":"@ai2robotics/ch-upgrade","version":"0.0.6","description":"ClickHouse迁移工具","type":"module","bin":{"ch-upgrade":"dist/bin/index.js"},"main":"./dist/src/lib/config.js","types":"./dist/src/lib/config.d.ts","engines":{"node":">=18.0.0"},"dependencies":{"@clickhouse/client":"^1.3.0","chalk":"^5.3.0","commander":"^11.1.0","dotenv":"^17.2.3","fs-extra":"^11.2.0","prompts":"^2.4.2","zod":"^3.22.0"},"devDependencies":{"@types/fs-extra":"^11.0.4","@types/node":"^20.10.0","@types/prompts":"^2.4.9","@typescript-eslint/eslint-plugin":"^6.15.0","@typescript-eslint/parser":"^6.15.0","@vitest/ui":"^1.1.0","eslint":"^8.56.0","prettier":"^3.1.0","tsx":"^4.7.0","typescript":"^5.3.0","vitest":"^1.1.0"},"keywords":["clickhouse","migration","database","schema","cli","upgrade"],"author":"","license":"MIT","publishConfig":{"registry":"https://registry.npmjs.org/","access":"public"},"scripts":{"dev":"tsx bin/index.ts","build":"tsc -p tsconfig.build.json","build:watch":"tsc -p tsconfig.build.json --watch","test":"vitest","test:ui":"vitest --ui","test:integration":"vitest run --config vitest.integration.config.ts","lint":"eslint bin/**/*.ts src/**/*.ts","format":"prettier --write \"bin/**/*.ts\" \"src/**/*.ts\""},"_id":"@ai2robotics/ch-upgrade@0.0.6","_integrity":"sha512-btGbc2FBUrrF8pk7Q85XJeXHtQo+0IhpR+0IBiB81eQJmqjMkoWHzpYsVpfq48rTGMeI233KHH8WCRw41fxlQQ==","_resolved":"/tmp/42aebf6ebcd8d4aa7d5b43909cc99deb/ai2robotics-ch-upgrade-0.0.6.tgz","_from":"file:ai2robotics-ch-upgrade-0.0.6.tgz","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-btGbc2FBUrrF8pk7Q85XJeXHtQo+0IhpR+0IBiB81eQJmqjMkoWHzpYsVpfq48rTGMeI233KHH8WCRw41fxlQQ==","shasum":"eff250156ed766a3bfbeea609173b97f7eeea087","tarball":"https://registry.npmjs.org/@ai2robotics/ch-upgrade/-/ch-upgrade-0.0.6.tgz","fileCount":34,"unpackedSize":107897,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDx4TgiIgcb4Xrx8ODG8UTSqc1PbW0jAtKwE34qQqV2mgIgM9UMx0si9UpHGEttyPBp838ZH69sMhg0H144nu7Rrys="}]},"_npmUser":{"name":"ai2r-admin","email":"it@ai2robotics.com"},"directories":{},"maintainers":[{"name":"ai2r-admin","email":"it@ai2robotics.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ch-upgrade_0.0.6_1771918200346_0.4344169663786501"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-24T07:29:59.986Z","0.0.6":"2026-02-24T07:30:00.500Z","modified":"2026-02-24T07:30:00.743Z"},"maintainers":[{"name":"ai2r-admin","email":"it@ai2robotics.com"}],"description":"ClickHouse迁移工具","keywords":["clickhouse","migration","database","schema","cli","upgrade"],"license":"MIT","readme":"# ch-upgrade 🚀\n\n**ch-upgrade** 是一个专为 ClickHouse 设计的极简架构迁移工具\n\n[![ClickHouse](https://img.shields.io/badge/ClickHouse-Supported-blue.svg)](https://clickhouse.com/)\n\n---\n\n## 🌟 核心理念\n\n在 ClickHouse 场景下，传统的 ORM 迁移工具往往过于笨重且不适配。`ch-upgrade` 坚持：\n\n- **声明式目录结构**：每个迁移都是一个独立的上下文。\n- **配置与敏感信息分离**：连接信息仅通过环境变量传递，安全适配 CI/CD。\n- **确定性校验**：通过 SHA256 确保历史迁移文件不被非法篡改。\n- **ClickHouse 原生支持**：针对 ClickHouse 的 DDL 特性（无事务 DDL）优化。\n\n---\n\n## 🛠️ 快速开始\n\n### 1. 安装\n\n```bash\n# 使用 pnpm (推荐)\npnpm add -g ch-upgrade\n\n# 或使用 npm\nnpm install -g ch-upgrade\n```\n\n### 2. 初始化项目\n\n```bash\nch-upgrade init --with-example\n```\n\n这将在当前目录下生成：\n\n- `ch-upgrade.config.json`：基础配置文件。\n- `ch-upgrade/migrations/`：迁移文件存储目录。\n- `..._example/`：包含 `migration.sql` (Up) 和 `migration.rollback.sql` (Rollback) 的示例目录。\n\n### 3. 配置连接 (环境变量)\n\n`ch-upgrade` **禁止**在配置文件中存储密码。请通过 `.env` 文件或系统变量配置：\n\n```bash\n# .env 文件\nCLICKHOUSE_HOST=127.0.0.1\nCLICKHOUSE_PORT=8123\nCLICKHOUSE_USERNAME=default\nCLICKHOUSE_PASSWORD=your_password\nCLICKHOUSE_DATABASE=your_db\n```\n\n---\n\n## 🔄 工作流\n\n`ch-upgrade` 提供了一套清晰的开发到生产的闭环：\n\n### Step 1: 创建迁移\n\n```bash\nch-upgrade create add_user_index\n```\n\n自动生成目录：`ch-upgrade/migrations/20260128163000_add_user_index/`。\n\n### Step 2: 编写 SQL\n\n在生成的目录中编写你的逻辑。\n\n- `migration.sql`: 升级逻辑 (Up)\n- `migration.rollback.sql`: 回滚逻辑 (Rollback)\n\n### Step 3: 开发环境应用\n\n```bash\nch-upgrade migrate dev\n```\n\n执行所有待处理的迁移。\n\n### Step 4: 生产环境部署\n\n```bash\nch-upgrade migrate deploy\n```\n\n只读模式运行，仅执行已存在的脚本，禁止自动生成或修改文件。\n\n### Step 5: 查看状态\n\n```bash\nch-upgrade migrate status\n```\n\n---\n\n## 📂 架构说明\n\n### 目录结构\n\n```text\nch-upgrade/migrations/\n  └── 20260128100000_init_tables/\n      ├── migration.sql        # 必须：执行时的 SQL\n      └── migration.rollback.sql   # 可选：回滚时的 SQL\n```\n\n### 状态追踪表\n\n工具会在你的数据库中自动维护 `_clickhouse_migrations` 表：\n| 字段 | 说明 |\n| :--- | :--- |\n| `version` | 14位时间戳 (唯一标识) |\n| `name` | 迁移目录全名 |\n| `executed_at` | 执行时间 |\n| `checksum` | `migration.sql` 的 SHA256，用于检测篡改 |\n\n---\n\n## 📜 ClickHouse 迁移准则\n\n由于 ClickHouse 不支持事务性 DDL，请务必遵循以下最佳实践：\n\n1. **幂等性优先**：始终使用 `IF NOT EXISTS` 或 `IF EXISTS`。\n   ```sql\n   CREATE TABLE IF NOT EXISTS users (...) ENGINE = MergeTree() ORDER BY id;\n   ```\n2. **原子化变更**：一个迁移目录只做一件事（例如：创建一个表或添加一个索引）。\n3. **不要修改已执行的脚本**：如果你修改了已部署的 `migration.sql`，`migrate` 命令会因为 `checksum` 不匹配而报错并停止，以防止环境不一致。\n\n---\n\n## ⌨️ 命令详解\n\n| 命令               | 描述                                                    |\n| :----------------- | :------------------------------------------------------ |\n| `init`             | 初始化项目，生成配置和目录                              |\n| `create <desc>`    | 创建新的迁移目录模板                                    |\n| `migrate dev`      | 执行迁移（开发模式）                                    |\n| `migrate deploy`   | 执行迁移（生产模式，安全性更高）                        |\n| `migrate status`   | 查看已执行和待执行的迁移清单                            |\n| `migrate rollback` | 回滚最后一个迁移（执行对应的 `migration.rollback.sql`） |\n\n---\n","readmeFilename":"README.md","_rev":"1-fa8bf9f5eca3ff7488199f4a3587de12"}