1. 从一次真实的迁移翻车说起数据库迁移这件事说大不大说小也绝对不小。我见过太多团队在版本迭代时随手改表结构结果上线当天发现回滚脚本没写、字段类型对不上、索引忘了建最后只能半夜手动补 SQL。Claude Code 编写 SQL 脚本这个场景本质上解决的就是「迁移脚本从需求到可执行」这一段最容易出错的环节。具体来说当你需要给一张订单表加字段、改类型、拆表或者从 SQLite 原型迁到 PostgreSQL 生产库时传统做法是打开编辑器凭记忆写ALTER TABLE本地跑一遍看着没报错就提交。问题在于——你写的只是「正向脚本」回滚呢索引呢默认值对存量数据的影响呢这些往往要等到出问题才想起来。Claude Code 的价值在于它能根据你用自然语言描述的表结构变更需求一次性产出建表/改表、数据迁移、回滚三段式脚本并且你可以把这三段脚本分别丢进本地 SQLite 和 PostgreSQL 里跑通验证。整个过程不需要你记住每种数据库的 DDL 方言差异也不需要反复查文档确认ALTER COLUMN TYPE在 PostgreSQL 里要不要加USING子句。这篇文章适合谁如果你是后端开发、全栈工程师或者小团队里那个「顺便管数据库」的人手头没有专职 DBA但又需要保证迁移脚本可回滚、可验证那这套流程可以直接拿去用。我会给出可复制的 Claude Code 提示词模板、迁移脚本骨架以及逐条验证动作。同时说明如何通过 TaoToken 统一 Key/API 通道接入 Claude Code避免在多个工具之间反复配置密钥。2. 前置准备用 TaoToken 统一接入 Claude Code在开始写迁移脚本之前先把接入通道理顺。Claude Code 本身是一个命令行工具它需要调用 Anthropic 的模型 API。如果你同时还在用其他 AI 编码工具每个工具都配一遍 Key、记一遍环境变量切换起来很烦。TaoToken 的作用就是提供一个统一的 API 通道你只需要在 TaoToken 控制台创建一个 Key然后让 Claude Code 指向这个通道即可。2.1 获取 API Key打开 TaoToken 控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite登录后进入 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建一个新的 Key。建议按用途命名比如claude-code-migration方便后续排查是哪个工具在调用。创建完成后复制 Key它通常以sk-开头。这个 Key 就是你后续所有 Claude Code 请求的凭证。2.2 配置 Claude Code 指向 TaoTokenClaude Code 支持通过环境变量指定 API 端点。你需要在 shell 配置文件~/.bashrc、~/.zshrc或 Windows 的系统环境变量里设置两个变量export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_BASE_URLhttps://taotoken.net/api注意ANTHROPIC_BASE_URL后面不要加多余的路径TaoToken 的 API 入口就是https://taotoken.net/api。设置完成后执行source ~/.zshrc让配置生效然后运行claude --version确认 Claude Code 能正常启动。如果你用的是 Windows PowerShell对应的设置方式是$env:ANTHROPIC_API_KEY sk-你的TaoToken密钥 $env:ANTHROPIC_BASE_URL https://taotoken.net/api想把这些变量持久化可以在「系统属性 → 环境变量」里添加或者写入 PowerShell 的$PROFILE文件。2.3 验证通道是否打通在正式写迁移脚本前先用一个最小请求确认通道可用。进入 Claude Code 交互模式后输入一句简单的话比如「用一句话说明什么是数据库迁移」。如果能正常返回内容说明 Key 和端点都配置正确。如果报 401检查 Key 是否复制完整如果报连接超时检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api/末尾多了斜杠有时会导致路径拼接异常。这一步看起来简单但实际排障时很多「Claude Code 没反应」的问题都出在环境变量没生效或者端点写错。先把通道验证通过后面写脚本才不会把工具问题和脚本问题混在一起。3. 可复制配置让 Claude Code 产出三段式迁移脚本接入通道打通后接下来是核心环节如何给 Claude Code 下指令让它产出结构清晰、可直接执行的迁移脚本。这里的关键是提示词模板——你描述得越结构化它产出的脚本越接近生产可用。3.1 迁移需求描述模板不要只丢一句「帮我加个字段」。Claude Code 需要知道当前表结构、目标表结构、数据库类型、是否有存量数据、是否需要回滚。下面这个模板可以直接复制修改我需要为 PostgreSQL 数据库编写一组迁移脚本。 当前表结构 CREATE TABLE orders ( id SERIAL PRIMARY KEY, user_id INTEGER NOT NULL, amount NUMERIC(10,2) NOT NULL, status VARCHAR(20) DEFAULT pending, created_at TIMESTAMP DEFAULT NOW() ); 变更需求 1. 新增字段 currency VARCHAR(3) NOT NULL DEFAULT CNY 2. 将 status 字段改为枚举类型 order_status可选值 pending/paid/shipped/cancelled 3. 为 user_id 和 created_at 建立联合索引 4. 存量数据中 status 为 done 的记录需要更新为 shipped 请输出三段式脚本 - 第一段正向迁移脚本up.sql包含所有 DDL 和 DML - 第二段回滚脚本down.sql能完整撤销上述变更 - 第三段验证脚本verify.sql用于检查迁移后数据一致性 要求 - 每个语句加注释说明用途 - 考虑存量数据DEFAULT 值要能覆盖已有行 - 枚举类型创建要处理「已存在则跳过」的情况 - 回滚脚本要考虑字段删除后数据丢失的风险给出提示这个模板的要点在于把「当前状态」和「目标状态」都写清楚并明确要求三段式输出。Claude Code 拿到这样的输入产出的脚本通常已经具备 80% 的可用性你只需要微调。3.2 建表/改表脚本骨架Claude Code 产出的正向脚本结构一般如下。你可以把它作为检查清单看它有没有遗漏关键部分-- up.sql -- 1. 创建枚举类型幂等处理 DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname order_status) THEN CREATE TYPE order_status AS ENUM (pending, paid, shipped, cancelled); END IF; END$$; -- 2. 新增字段带默认值覆盖存量行 ALTER TABLE orders ADD COLUMN currency VARCHAR(3) NOT NULL DEFAULT CNY; -- 3. 数据清洗将旧状态映射到新枚举 UPDATE orders SET status shipped WHERE status done; -- 4. 修改字段类型PostgreSQL 需要 USING 子句 ALTER TABLE orders ALTER COLUMN status TYPE order_status USING status::order_status; -- 5. 创建联合索引 CREATE INDEX IF NOT EXISTS idx_orders_user_created ON orders (user_id, created_at);注意第 4 步的USING status::order_status这是 PostgreSQL 特有的语法。如果你让 Claude Code 同时生成 MySQL 版本它会用MODIFY COLUMN方言差异它自己能处理这也是用 AI 写迁移脚本比手写省心的地方。3.3 回滚脚本骨架回滚脚本不是简单地把ADD COLUMN改成DROP COLUMN。你要考虑字段删了数据就没了枚举类型删了其他表可能还在用。Claude Code 产出的回滚脚本通常会包含风险提示-- down.sql -- 警告执行前请确认没有其他表依赖 order_status 枚举类型 -- 警告删除 currency 字段将丢失该列所有数据建议先备份 -- 1. 删除索引 DROP INDEX IF EXISTS idx_orders_user_created; -- 2. 将 status 改回 VARCHAR ALTER TABLE orders ALTER COLUMN status TYPE VARCHAR(20) USING status::text; -- 3. 恢复旧状态值 UPDATE orders SET status done WHERE status shipped; -- 4. 删除新增字段 ALTER TABLE orders DROP COLUMN IF EXISTS currency; -- 5. 删除枚举类型确认无依赖后执行 DROP TYPE IF EXISTS order_status;这里有个实操细节回滚脚本里的UPDATE语句把shipped改回done只对迁移后没被业务修改过的数据有效。如果迁移后用户已经产生了新订单回滚时不能无差别执行。所以回滚脚本更适合在「迁移后立即发现问题」的窗口期内使用而不是当成万能后悔药。3.4 验证脚本骨架验证脚本是很多人会跳过的一步但恰恰是它能在本地跑通阶段帮你发现数据不一致-- verify.sql -- 1. 检查字段是否存在 SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_name orders AND column_name IN (currency, status); -- 2. 检查枚举类型定义 SELECT enumlabel FROM pg_enum WHERE enumtypid order_status::regtype ORDER BY enumsortorder; -- 3. 检查索引是否创建 SELECT indexname, indexdef FROM pg_indexes WHERE tablename orders; -- 4. 检查存量数据默认值填充 SELECT COUNT(*) AS missing_currency FROM orders WHERE currency IS NULL; -- 5. 检查状态值是否都在枚举范围内 SELECT DISTINCT status FROM orders WHERE status NOT IN (pending, paid, shipped, cancelled);第 4 和第 5 条查询返回 0 行才说明迁移在数据层面是干净的。如果第 4 条返回非零说明DEFAULT没生效或者有 NULL 值混入如果第 5 条返回了值说明枚举映射有遗漏。4. 验证请求在 SQLite 与 PostgreSQL 中跑通脚本写出来只是第一步真正让人放心的是「在本地跑一遍」。这里我建议用 SQLite 做快速语法验证用 PostgreSQL 做真实行为验证。两者结合既快又准。4.1 SQLite 快速验证SQLite 的好处是零配置一个文件就是一个库。你可以用 Python 脚本快速建一个测试库把 Claude Code 产出的脚本跑一遍看有没有语法错误import sqlite3 conn sqlite3.connect(:memory:) cursor conn.cursor() # 建初始表 cursor.executescript( CREATE TABLE orders ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, amount REAL NOT NULL, status TEXT DEFAULT pending, created_at TEXT DEFAULT CURRENT_TIMESTAMP ); INSERT INTO orders (user_id, amount, status) VALUES (1, 99.5, done); ) # 执行迁移脚本SQLite 版本 with open(up_sqlite.sql, r) as f: cursor.executescript(f.read()) # 验证 cursor.execute(SELECT COUNT(*) FROM orders WHERE currency IS NULL) print(缺失 currency 的行数:, cursor.fetchone()[0]) conn.close()注意 SQLite 不支持ALTER COLUMN TYPE和枚举类型所以 Claude Code 在生成 SQLite 版本时会采用「新建表 → 复制数据 → 删旧表 → 重命名」的方式。这个差异你要提前告诉它否则它可能生成 SQLite 不认的语法。4.2 PostgreSQL 真实环境验证PostgreSQL 验证更接近生产。如果你本地没有装 PostgreSQL可以用 Docker 起一个docker run --name pg-migration-test \ -e POSTGRES_PASSWORDtest123 \ -e POSTGRES_DBmigration_demo \ -p 5432:5432 \ -d postgres:15然后用psql连接进去依次执行建表、迁移、验证脚本psql -h localhost -U postgres -d migration_demo -f init.sql psql -h localhost -U postgres -d migration_demo -f up.sql psql -h localhost -U postgres -d migration_demo -f verify.sql如果verify.sql里的检查查询都返回预期结果再执行一次down.sql然后重新跑up.sql确认迁移和回滚可以反复执行。这个「up → verify → down → up」的循环是验证迁移脚本健壮性的最小闭环。4.3 成功结果长什么样一次成功的迁移验证输出应该类似这样-- verify.sql 执行结果 column_name | data_type | is_nullable | column_default -------------------------------------------------------- currency | character varying | NO | CNY::character varying status | order_status | YES | enumlabel ---------- pending paid shipped cancelled indexname | indexdef --------------------------------------------------------------------- idx_orders_user_created | CREATE INDEX ... ON orders (user_id, created_at) missing_currency ---------------- 0 status 不在枚举范围内的行数 ---------------------------- 0看到missing_currency为 0、枚举值完整、索引存在基本可以确认迁移脚本在结构层面和数据层面都通过了。5. 本篇常见错排查即使有 Claude Code 辅助实际跑的时候还是会遇到一些典型问题。下面这几个是我在本地验证阶段踩过的坑按出现频率排序。5.1 枚举类型重复创建报错PostgreSQL 里CREATE TYPE没有IF NOT EXISTS语法直接执行会报type order_status already exists。Claude Code 通常会生成DO $$ ... END$$块来做幂等处理但如果你手动改了脚本可能把这个块删掉了。排查方法在up.sql里搜索CREATE TYPE确认它被包在条件判断里。5.2 字段类型转换缺少 USING 子句从VARCHAR改成枚举类型时PostgreSQL 要求显式指定转换方式-- 错误写法 ALTER TABLE orders ALTER COLUMN status TYPE order_status; -- 正确写法 ALTER TABLE orders ALTER COLUMN status TYPE order_status USING status::order_status;如果报column status cannot be cast automatically to type order_status就是这个原因。让 Claude Code 重新生成时在提示词里加一句「PostgreSQL 类型转换需要 USING 子句」。5.3 默认值未覆盖存量行ADD COLUMN currency VARCHAR(3) NOT NULL DEFAULT CNY在 PostgreSQL 11 里会快速填充默认值但在更早版本或者某些数据库里存量行可能还是 NULL。验证脚本里的missing_currency查询就是用来抓这个问题的。如果返回非零手动补一条UPDATE orders SET currency CNY WHERE currency IS NULL。5.4 回滚脚本执行顺序错误回滚时如果先删枚举类型再改字段类型会报依赖错误。正确顺序是先改字段类型回VARCHAR再删枚举。Claude Code 一般会按正确顺序生成但如果你手动调整过脚本记得检查down.sql里DROP TYPE是不是在最后。5.5 TaoToken 通道返回 401 或超时如果 Claude Code 突然报认证失败先检查ANTHROPIC_API_KEY是否过期或被撤销。可以到 TaoToken 控制台重新生成一个 Key。如果是超时检查ANTHROPIC_BASE_URL是否被其他工具的配置覆盖了——有些工具会写自己的环境变量导致 Claude Code 读到了错误的端点。用echo $ANTHROPIC_BASE_URL确认当前值。6. 把迁移脚本纳入日常开发流程跑通一次迁移脚本之后更有价值的做法是把它变成可重复的流程。我自己的习惯是每次表结构变更先在 Claude Code 里用提示词模板生成三段式脚本存到项目的migrations/目录下命名带上时间戳比如20250115_add_currency_to_orders_up.sql。然后在 CI 里加一步用 Docker 起一个临时 PostgreSQL跑一遍up → verify → down通过才允许合并。这样做的成本很低但能挡住大部分「本地能跑、线上报错」的问题。Claude Code 负责生成TaoToken 负责通道Docker 负责验证环境三者串起来就是一个轻量但完整的迁移工作流。如果你还没配 TaoToken可以从模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite先试一下通道是否可用如果打算长期用 Claude Code 做编码和 Agent 任务可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入细节和参数说明在接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里。先把通道跑通再让 Claude Code 帮你写迁移脚本整个流程会顺很多。