@agentaily/db
平台的持久化层:拥有平台固定表的 schema(Drizzle 真相源)、生成的迁移(./migrations,由 wrangler 应用),以及 @agentaily/backend 各 storage seam 的 D1 实现。@agentaily/backend 保持纯逻辑(逻辑 + 抽象 seam + in-memory 替身);apps/web 的 Pages Functions 把这里的工厂接到 D1 binding 上。
🔁 重构中(REFACTOR.md): 本包将 rework + rename →
@agentaily/runtime—— 职责从「JSON-Schema 派生表」转向「吃@agentaily/aml的EmitResult做 provision + scoped 数据引擎」。下面的 AML 引擎(轨道 B)就是这个方向的已落地地基;旧的 JSON-Schema 路线(轨道 A)仍承载当前生产,待新引擎接管后逐步退役。设计真相源见DESIGN.md(轨道 A)与../REFACTOR.md(终态)。
双轨并存(当前现实)
本包同时装着两套数据表引擎。轨道 A 承载当前生产,轨道 B 是收敛后的目标地基,二者都已 ship。
轨道 A —— 旧 JSON-Schema 派生路线(承载当前生产)
从内容文档派生 recordSchema(JSON Schema)→ 编译成每项目一张真表 data_<projectId>(每字段一列)。vertical-agnostic(吃 JSON Schema,不 import 任何 vertical)。
| 文件 | 是什么 |
|---|---|
schema.ts | 平台固定表的 Drizzle 真相源:projects · submissions · users · authTokens · customHostnames |
client.ts | drizzleClient(env.DB) → DB(D1 上的 Drizzle 客户端) |
dataStores.ts · authStores.ts | @agentaily/backend seam 的 D1 实现(d1Stores、d1UserStore / d1TokenStore、getProjectBySlug / getProjectByHostname) |
compiler.ts | 纯函数:JSON Schema → 列定义 + diff 迁移(类型映射、软删归档、归档+新列绕开「改列类型」) |
dataTable.ts | 上面编译器的 D1 运行时:ensureDataTable / createDataTableIfNotExists / insertRecord / listRecords / queryRecords(派生数据 API /api/data/:id 的底座) |
详尽设计(类型映射、迁移 op、决策台账)见 DESIGN.md。
轨道 B —— 新 AML 引擎(M1 + M2,additive)
吃 @agentaily/aml 的 emit() 产物({ tables, sql, api(ApiDescriptor) })→ provision D1 表 + 从 ApiDescriptor 派生 scoped/authed 数据接口。这是 REFACTOR 的 @agentaily/runtime 雏形。
| 文件 | M | 是什么 |
|---|---|---|
amlCompiler.ts | M1 | 纯函数:provisioningStatements / indexStatements / diffTable / migrationSql + 值 codec(encodeValue / decodeValue / isJsonColumn)。从 aml tables 算建表 / 迁移 SQL |
amlTable.ts | M1 | M1 编译器的 D1 运行时:provisionTables / migrateTable / provisionAndMigrate / provisionFromAml / liveColumns |
amlDataCompiler.ts | M2 | 纯 SQL 编译器:compileInsert / compileQuery / applyDefaults / decodeRow + Scope —— 从 ApiDescriptor 派生类型化 insert/query |
amlDataEngine.ts | M2 | M2 编译器的 D1 运行时:createDataEngine → DataEngine。每个 op 强制把行级 scope(如 { projectId })注入 SQL —— 调用方无法跑无 scope 的查询,请求体里传的 id 被忽略(REFACTOR §5 的安全模型) |
导出加了前缀避免与轨道 A 撞名:
amlMigrationSql/isAmlJsonColumn/encodeAmlValue/AmlMigrationOp/AmlQueryOpts等。
装哪 / 怎么用
// consumer package.json
"dependencies": { "@agentaily/db": "workspace:*" }消费为 TypeScript 源码(无构建步)。固定表迁移由 wrangler d1 migrations apply(本地 --local / 生产 --remote)应用,运维见 ../OPERATIONS.md 第六节。
测试
pnpm --filter @agentaily/db test(根 pnpm test 一并跑)—— 纯逻辑单测(编译器 / 迁移 diff / scoped SQL 等),node 环境。