Reylo的Freshness机制:Schema变更后如何检测过期类型并防止陈旧错误
Reylo的Freshness机制:Schema变更后如何检测过期类型并防止陈旧错误
Reylo 是一个将 .sql 文件直接导入 TypeScript 并获得完整类型推断的开源工具,全程零代码生成。但数据库的 Schema 会随迁移不断变化——Reylo 的 Freshness 机制正是为此而生:它让每条查询自带"构建时的 Schema 快照",在运行前自动检测 Schema 漂移,一旦过期就拒绝执行并给出清晰报错,从根源上防止陈旧类型导致的运行时错误。
🎯 为什么需要一次"新鲜度检查"
Reylo 的类型直接来自数据库:查询被解析后,引擎会读取每一列的类型、可空性与返回行数,全程不需要手写行类型,也没有生成文件需要同步(见 README.md)。
但问题也随之而来:
- 类型在构建时确定,而数据库不会停止演化;
- 一个长期运行的服务可能跨越多轮迁移——今天上午部署的代码,下午看到的 Schema 已经变了;
- 手写的行类型或代码生成的类型文件同样会过期,且过期后毫无提示。
Reylo 的答案是:把"这条查询依赖了哪些 Schema 事实"一起打包进编译产物,运行时重新核对。任何变化都会让调用失败,并点名是哪张表、哪一列变了。
⚙️ Freshness 机制如何工作:三步拆解
第 1 步:构建时为 Schema 拍一张"照片"
分析查询时,Rust 引擎会提取该语句实际引用的列的事实,存成一条无参数 catalog 查询的文本结果行(实现于 engine/core/src/fresh.rs):
| 事实 | 含义 |
|---|---|
| 表名 + 列名 | 语句引用到的每一列(* 展开为全部列) |
| 类型 | catalog 中记录的原始类型文本 |
| 是否 NOT NULL | 可空性 |
| 是否有默认值 | 默认值有无 |
| 默认值文本(仅 Postgres / SQLite) | 结构化 insert 复制进来的默认值原文 |
关键点:语句没引用的列不算事实。所以一次迁移只是给表新增了一列,只要你的查询从不碰它,检查就不会被触发——不会误伤无关变更。
这些事实连同那条 catalog 查询一起,被写入每个 .sql 编译产物中(见 src/loader.ts 中 defineQuery 的 fresh 字段)。
第 2 步:运行前重查 catalog 并逐行比对
每次 .run() 之前,运行时通过你正在用的同一个客户端重新执行那条 catalog 查询,把当前结果与构建时的快照逐列比对(核心比对逻辑在 src/fresh.ts 的 differences 函数中)。同步路径 runSync 与异步路径 run 都会执行这次检查(见 src/execute.ts)。
第 3 步:发现差异 → 拒绝执行,点名报错
只要有任何差异,查询不会跑,而是抛出带细节的错误(由 src/fresh.ts 的 staleError 生成):
The database changed after get_user.sql was built: users.email was text not null and no longer exists. Build it again (the type check, or reylo generate) and deploy the new build.
错误信息直接给出文件名 + 表 + 列 + 变更前后状态,定位问题不再需要猜。
🚨 哪些 Schema 变更会触发"陈旧"报错
| Schema 变更 | 结果 |
|---|---|
| 查询引用的列被删除或重命名 | ❌ 调用失败 |
引用列的类型被修改(如 text → varchar(100)) |
❌ 调用失败 |
| 引用列的 NOT NULL / 有无默认值变化 | ❌ 调用失败 |
| INSERT 目标表新增了"无默认值的 NOT NULL 列" | ❌ 调用失败 |
| 结构化 insert 复制过的默认值文本被修改 | ❌ 调用失败 |
| 表新增了查询从不引用的列 | ✅ 照常运行 |
比对细节还考虑了各数据库的差异:SQLite 的类型按 ASCII 忽略大小写比较(pragma_table_xinfo 会把已知类型名大写,而 Turso 引擎按声明拼写),默认值文本会归一化为同一拼写再比;Postgres 与 MySQL 则严格比较(归一化逻辑见 src/fresh.ts)。
💡 机制背后的贴心设计
- 60 秒新鲜度窗口:每个查询模块在进程内首次运行必检,之后每隔一分钟再检一次(
FRESH_FOR = 60_000)。长时间运行的服务因此能"看见"运行期间上线的迁移,又不为每次调用增加一次 catalog 往返。 - 单调时钟:计时使用
performance.now()而非Date.now(),避免在 Next.js 预渲染等环境中出错(见 src/fresh.ts)。 - 优雅降级,绝不卡死:如果 catalog 查询失败(例如角色无权读 catalog),或返回的行根本不是 catalog 的形状(如 mock / stub 客户端),检查静默跳过、查询照常运行——检查是保护,不是枷锁。
- 零额外依赖:检查复用调用方自己的连接与驱动,不需要额外的数据库连接。
以上行为的回归覆盖在 tests/fresh.test.ts 中,涵盖了列被重命名、改类型、默认值变更、新增必填列等全部场景。
🛠️ 收到"陈旧类型"错误后怎么办
报错信息已经说明了答案,动作很简单:
- 重新构建:重跑类型检查(
tsc --noEmit --runExternalCode),或执行reylo generate重新生成编译产物; - 部署新构建:让运行时的快照与当前 Schema 对齐;
- 由于 Reylo 的类型与 SQL 一一对应,重建后所有过期的调用点会同时被类型检查找出——每个事实只存于一处,就不会有遗漏的陈旧类型残留。
📚 核心文件路径速查
| 文件 | 作用 |
|---|---|
| engine/core/src/fresh.rs | 引擎侧:提取 Schema 事实、生成 catalog 查询 |
| src/fresh.ts | 运行时侧:新鲜度判定、差异比对、陈旧错误 |
| src/execute.ts | .run() / runSync() 执行前触发检查 |
| src/loader.ts | 将 fresh 事实嵌入 .sql 编译产物 |
| tests/fresh.test.ts | Freshness 机制的完整测试用例 |
| AGENTS.md | 项目结构与贡献指南 |
Freshness 机制让 Reylo 的"零代码生成"不只是省掉了同步成本,更把"Schema 已经变了"这件事从隐性的坑变成了显式的、可定位的错误——类型永远不会悄悄说谎。

