Reylo的Freshness机制:Schema变更后如何检测过期类型并防止陈旧错误

原创2026-10-24 23:49:531,614 阅读

Reylo的Freshness机制:Schema变更后如何检测过期类型并防止陈旧错误

Reylo 是一个将 .sql 文件直接导入 TypeScript 并获得完整类型推断的开源工具,全程零代码生成。但数据库的 Schema 会随迁移不断变化——Reylo 的 Freshness 机制正是为此而生:它让每条查询自带"构建时的 Schema 快照",在运行前自动检测 Schema 漂移,一旦过期就拒绝执行并给出清晰报错,从根源上防止陈旧类型导致的运行时错误。

Reylo将.sql文件导入TypeScript获得完整类型推断的演示

🎯 为什么需要一次"新鲜度检查"

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)。

使用Reylo导入SQL文件到TypeScript项目的代码示意

第 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 中,涵盖了列被重命名、改类型、默认值变更、新增必填列等全部场景。

🛠️ 收到"陈旧类型"错误后怎么办

报错信息已经说明了答案,动作很简单:

  1. 重新构建:重跑类型检查(tsc --noEmit --runExternalCode),或执行 reylo generate 重新生成编译产物;
  2. 部署新构建:让运行时的快照与当前 Schema 对齐;
  3. 由于 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 已经变了"这件事从隐性的坑变成了显式的、可定位的错误——类型永远不会悄悄说谎。

登录后查看全文
reylo