/** * 部署前的迁移体检:`drizzle/*.sql` 声明过的东西,生产库里是不是真的有。 * * bun scripts/check-migrations.ts # 只读;有缺失时退出码 1 * * ## 为什么需要它 * * 这个仓库没有迁移执行器:`deploy.sh` 从不碰 schema,迁移靠人手工跑 * `apply-migration.ts`。于是存在一个谁都没注意的耦合 —— **谁部署,谁替所有人的 * 未落库迁移买单**。你合并的分支不需要迁移,但 `git pull` 会把别人**已经合进 main、 * 迁移却还没跑**的提交一起带上生产,重启之后所有相关查询直接 500。 * * 2026-08-22 就这么炸过一次:一次知识库改动的部署顺带把 `tasks.method_coverage` * 的代码拉了上去,那一列的迁移从没执行过,`/api/tasks` 全线 500,面板打不开四分钟。 * 部署脚本的验证步骤拦住了(这是它做对的地方),但那时服务已经重启完了 —— 拦得太晚。 * * 所以这一步放在 **pull 之后、restart 之前**:此时新代码已经在盘上,老进程还在跑, * 缺列还只是一个可以从容处理的告警,而不是一次线上事故。 * * ## 为什么连列也要查 * * `apply-migration.ts` 原来只复核表和索引。而生产上真正炸掉的是 **ADD COLUMN** —— * 加一列不建表也不建索引,原来的复核完全看不见它。这里三种都查。 * * ## 它不做什么 * * 不自动执行迁移。DDL 是对生产的写操作,按 CLAUDE.md 归操作者决定;这个脚本只负责 * 让人在**正确的时刻**知道该跑哪一条。 */ import { readFileSync, readdirSync } from "node:fs"; import path from "node:path"; import pg from "pg"; const DIR = path.resolve(import.meta.dir, "../drizzle"); const raw = process.env.DATABASE_URL; if (!raw) { console.error("[migrate-check] DATABASE_URL 未设置(见 .env)"); process.exit(2); } /** * 明知故犯的清单:声明过、但**故意没有**落到生产的对象。 * * 一个会因为历史包袱天天变红的检查,等于没有检查 —— 人会学会忽略它,然后连真的 * 那次也一起忽略。所以豁免必须存在,但每一条都要写清楚为什么,并且这个文件在 * code review 里是显眼的。 * * 加一条之前先问:这是"当年设计废弃了"还是"该跑没跑"?后者请去跑迁移。 */ const ACKNOWLEDGED: Record = { // 0002 设计的 SpecDelta 事件表。这条路后来被 run_conditions 取代(执行器直接写 // 结构化条件,不再另存一份 delta 事件),全仓库没有任何代码引用它 —— 建出来只会 // 是一张永远空着的表。 spec_delta_events: "设计已被 run_conditions 取代,全仓库无引用(0002)", // 「验证」曾是 features.deliverable='report' 的 feature,0036 把它搬进 verifications, // 0037 删掉这三列和 audit_notes(已并入 verification_notes)。0037 跑之前它们都还在, // 跑之后不在 —— 两种状态都是对的,所以豁免。 audit_notes: "已并入 verification_notes,0037 删除(0034)", "features.deliverable": "验证线已拆成 verifications 表,0037 删除(0032)", "features.audit_report": "移到 verifications.audit_report,0037 删除(0033)", "features.verify_spec": "移到 verifications.verify_spec,0037 删除(0035)", }; interface Want { file: string; kind: "表" | "索引" | "列"; /** 表名/索引名,或 "表.列"。 */ name: string; table?: string; column?: string; } const wants: Want[] = []; for (const file of readdirSync(DIR).filter((f) => f.endsWith(".sql")).sort()) { // 注释里出现的 SQL 片段不算数 —— 这个仓库的迁移写了大量解释性注释,里面常有 // 示例语句,把它们当成"声明过的对象"会造出永远修不好的假缺失。 const sql = readFileSync(path.join(DIR, file), "utf8").replace(/^\s*--.*$/gm, ""); for (const m of sql.matchAll(/CREATE TABLE\s+(?:IF NOT EXISTS\s+)?"?([\w.]+)"?/gi)) wants.push({ file, kind: "表", name: m[1] }); for (const m of sql.matchAll(/CREATE (?:UNIQUE )?INDEX\s+(?:IF NOT EXISTS\s+)?"?([\w.]+)"?/gi)) wants.push({ file, kind: "索引", name: m[1] }); for (const m of sql.matchAll( /ALTER TABLE\s+"?([\w.]+)"?\s+ADD COLUMN\s+(?:IF NOT EXISTS\s+)?"?([\w.]+)"?/gi, )) wants.push({ file, kind: "列", name: `${m[1]}.${m[2]}`, table: m[1], column: m[2] }); } // URL 解析与 db_client.ts 一致:IPv6 字面量必须以裸 host 传给 pg。 const u = new URL(raw); const pool = new pg.Pool({ host: u.hostname.replace(/^\[|\]$/g, ""), port: u.port ? Number(u.port) : 5432, user: decodeURIComponent(u.username), password: decodeURIComponent(u.password), database: u.pathname.replace(/^\//, ""), connectionTimeoutMillis: 30_000, }); // 永远不要把 URL 本身打出来 —— 它带着生产口令。 console.log(`[migrate-check] 目标库 ${u.pathname.replace(/^\//, "")} @ ${u.hostname}`); console.log(`[migrate-check] ${wants.length} 个对象,来自 ${new Set(wants.map((w) => w.file)).size} 份迁移`); try { const cols = new Set(); for (const r of (await pool.query<{ t: string; c: string }>( `select table_name as t, column_name as c from information_schema.columns where table_schema = 'public'`, )).rows) cols.add(`${r.t}.${r.c}`); const missing: Want[] = []; for (const w of wants) { if (w.kind === "列") { if (!cols.has(w.name)) missing.push(w); continue; } const r = await pool.query<{ oid: string | null }>("SELECT to_regclass($1) AS oid", [w.name]); if (!r.rows[0]?.oid) missing.push(w); } const excused = missing.filter((m) => ACKNOWLEDGED[m.name]); const blocking = missing.filter((m) => !ACKNOWLEDGED[m.name]); for (const e of excused) console.log(`[migrate-check] 豁免 ${e.kind} ${e.name} —— ${ACKNOWLEDGED[e.name]}`); if (!blocking.length) { console.log(`[migrate-check] \x1b[32m全部已落库\x1b[0m`); process.exit(0); } console.error(`\n[migrate-check] \x1b[31m${blocking.length} 个对象在生产库里不存在:\x1b[0m`); const byFile = new Map(); for (const m of blocking) byFile.set(m.file, [...(byFile.get(m.file) ?? []), m]); for (const [file, items] of byFile) { console.error(`\n drizzle/${file}`); for (const i of items) console.error(` ${i.kind} ${i.name}`); console.error(` → bun scripts/apply-migration.ts drizzle/${file} # 预演`); console.error(` → bun scripts/apply-migration.ts drizzle/${file} --commit # 执行`); } console.error(`\n[migrate-check] 迁移是对生产的写操作,由人决定要不要跑;跑完再继续部署。`); process.exit(1); } catch (err) { console.error(`[migrate-check] 检查失败: ${(err as Error).message}`); process.exit(2); } finally { await pool.end(); }