cli/runtime: explicit driver(`--database-driver` / `OS_DATABASE_DRIVER`)在 CLI 与 standalone stack 之间仍有三处分叉(#6265 后续)

[qq9340100]

发现于 #6265 的实施(PR #6344)。#6344 的裁决面是「mysql:// 识别」+「env 值过 zod enum 真校验」,这三处都不在其中,顺手改等于在未裁的情况下扩/收契约,故另记、未认领。

⚠️ 开 issue 前的查重只跑通了两条(storage-driver 别名、"OS_DATABASE_DRIVER" alias 词表,均 0 命中),其余查询撞上 GitHub search 速率限制。若与既有 issue 重复,请直接关掉。

背景

#6344 之后,OS_DATABASE_DRIVER 的未知值在 standalone stack(os migrate / createStandaloneStack / 嵌入方)会响亮拒绝并列出合法值,不再静默落 SQLite。这消灭了「静默连错库」,但没有让两侧的 explicit-driver 口径一致 —— 下面三条都是「不再静默,但仍不一致」。

(1) 别名词表两侧不同

• CLI(packages/cli/src/utils/storage-driver.ts resolveStorageDefinition)接受:mongodb|mongo、sqlite|sql、sqlite-wasm|wasm-sqlite|wasm、postgres|postgresql|pg、mysql|mysql2、turso|libsql、memory|mingo|in-memory;
• standalone stack(packages/runtime/src/standalone-stack.ts StandaloneDatabaseDriverSchema,feat(runtime): standalone stack 认 mysql://,并对 OS_DATABASE_DRIVER 做真校验 (#6265) #6344 后)只收规范拼写:sqlite、sqlite-wasm、memory、postgres、mysql、mongodb、turso;
• 而 content/docs/data-modeling/drivers.mdx 的 "Supported Drivers" 表把别名列为 OS_DATABASE_DRIVER 的合法值(postgres | postgresql | pg、mysql | mysql2、sqlite | sql、…)。

后果:OS_DATABASE_DRIVER=pg(或 mysql2 / mongo / libsql / wasm-sqlite / mingo / …)在 os start 下正常,在 os migrate 下被拒。改前这条路是静默 SQLite,所以 #6344 是净改善;但同一个环境变量仍有两种答案。

复现:

OS_DATABASE_DRIVER=pg OS_DATABASE_URL=postgres://u:p@localhost:5432/db os start   # 认
OS_DATABASE_DRIVER=pg OS_DATABASE_URL=postgres://u:p@localhost:5432/db os migrate plan   # 拒(改前:静默 SQLite)

值得注意:仓内已经有一份唯一别名表 —— packages/spec/src/data/driver/config-registry.zod.ts 的 DRIVER_ID_ALIASES / resolveDriverId(共享工厂已经在用它,注释里明确写着「两张表意味着选 driver 的 id 与选 config 契约的 id 可能不一致」)。但它的规范 id 是 mongo(不是 standalone 的 mongodb),且不含 turso/libsql(那不是 builtin driver),所以直接复用不是机械替换,需要裁决。

未裁选项:

• A standalone enum 收下同一批别名(与 CLI 对齐,词表集中一处);
• B 反过来把 CLI 收窄到规范拼写,拒绝时给 rename hint(contract-first 口味,但会打断现有 --database-driver pg 用法);
• C 两侧都改读 spec 的 resolveDriverId,并先把 mongodb/turso 的口径补进那张表。

倾向 C(唯一词表,选 driver 与选 config 契约同一个集合)或 A;但这是公开配置面的取舍,应由维护者裁。

(2) 显式选了「非文件」driver 却没给 URL —— 两侧都不好,方式不同

• CLI:resolveStorageDefinition('postgres', { databaseUrl: undefined }) 产出 config: { url: undefined },pg 于是用它自己的默认值连 localhost:5432 —— 连到一个操作者从没点名的地方;
• standalone stack:resolveDatabaseUrl() 兜底成 file:…/standalone.db,于是 mysql/postgres/mongodb 拿到一个 file: 开头的 DSN,失败在 driver 里,消息与成因隔了两层。

对照:turso 在 CLI 侧已经有 typed UnsupportedDriverError,话说得很到位 ——「选了 turso 却没给 URL,libSQL 没有可猜的默认;退回 SQLite 会静默忽略你要的 driver」。同一句话对 mysql / postgres / mongodb 一字不改都成立。

建议:把那条 typed 拒绝推广到所有「无本地默认」的 kind(两侧),而不是各自兜一个错误的默认。

(3) --database-driver 的 help 文案漏项

packages/cli/src/commands/start.ts:109 与 packages/cli/src/commands/dev.ts:102 的描述都是
Force driver kind: sqlite | turso | postgres | mongodb | memory,漏了 mysql 与 sqlite-wasm —— 两者都能用;content/docs/deployment/cli.mdx:134 / :323 的表同样漏。而 content/docs/deployment/environment-variables.mdx:52 列的是全集(含 mysql)。三份清单,三种答案。

若 (1) 收敛到唯一词表,这条应当顺带由那份词表推导出来,而不是再手写一遍。

---

未认领。

[claude]

Triage: needs-user-decision + domain:cli.

Why the decision box and not the queue. Item (1) is a public configuration surface: whether OS_DATABASE_DRIVER=pg | mysql2 | mongo | libsql | wasm-sqlite | mingo stays legal (A), gets narrowed to canonical spellings with a rename hint (B), or both sides move onto packages/spec's DRIVER_ID_ALIASES / resolveDriverId (C). The reporter says so explicitly, and the routing label is on the card so it drops into the cli lane the moment the call is made — no re-triage needed. Item (2) (typed UnsupportedDriverError generalized from turso to every no-local-default kind) is a rejection-behaviour change on the same surface and rides the same ruling.

Item (3) is deliberately NOT carved out into its own queued card. The --database-driver help text and the two docs tables are mechanical, but the issue itself states the honest reason to keep them together: if (1) converges on a single alias table, (3) should be derived from that table rather than hand-written a fourth time. Splitting it now would either duplicate the work or pre-commit the decision.

Maintainer, the question in one line: should the CLI's driver aliases (pg, mysql2, mongo, libsql, wasm-sqlite, mingo, …) remain accepted for OS_DATABASE_DRIVER everywhere (A), be narrowed to canonical spellings with a rename hint (B), or should both sides adopt packages/spec's existing resolveDriverId table after reconciling mongo vs mongodb and adding turso (C)? The docs currently promise A; os migrate after #6344 delivers B.

Baseline note (matters for whoever picks this up). PR #6344 is still open — the "after #6344" facts in the body (zod enum on StandaloneDatabaseDriverSchema, loud rejection instead of silent SQLite) are not on origin/main yet. Last touches on packages/cli/src/utils/storage-driver.ts / packages/runtime/src/standalone-stack.ts are #6272 and #6202. Re-verify the divergence after #6344 merges; the (3) help-text drift is independent of it and true on main today.

Dedupe (three repos, issues + PRs): no duplicate. #6265 (open, pm:queue, domain:cli) is the parent defect this follows up on, and #6344 is its PR — both cross-linked from the body already. The reporter flagged that their own dedupe hit search rate limits; the searches that were rate-limited have now been re-run from this seat and come back clean.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling — 2026-08-07. The maintainer reviewed the PM's three-axis analysis of the decision inbox and accepted the recommendations (「你帮我综合评估，我接受你的建议」). Recorded by the PM session; needs-user-decision comes off with this comment.

Decision: Option C — converge both sides on spec's single vocabulary (DRIVER_ID_ALIASES / resolveDriverId).

Ruled items:

1. Sequence contract-first: first extend the spec table with canonical entries for mongodb and turso/libsql (spec half — shared contract surface, spec seat owns it); then CLI (resolveStorageDefinition) and standalone stack (StandaloneDatabaseDriverSchema) both consume resolveDriverId. Triage may split into spec + cli sub-issues with a Blocked-by line.
2. Generalize the typed no-URL rejection (the existing turso UnsupportedDriverError wording) to every kind without a local default — mysql / postgres / mongodb, on both sides. No side invents a wrong default (localhost:5432, file: DSN into mysql).
3. Help text and docs derive from the table: --database-driver descriptions in start.ts / dev.ts and the three docs tables stop being hand-written lists — one vocabulary, one derivation.

Rationale: two hand-maintained vocabularies have already drifted into three different documented answers; narrowing the CLI (Option B) breaks working --database-driver pg usage for no gain; Option A duplicates the vocabulary in a second place and the drift returns.

---

Generated by Claude Code

[os-project-manager]

维护者裁定存档(2026-08-08,cli 席)

• 岔口 (1) 裁定 C:两侧(CLI resolveStorageDefinition 与 standalone StandaloneDatabaseDriverSchema)都改读 packages/spec 的 resolveDriverId 唯一词表;作为裁定的一部分,先把 mongodb / turso 的规范口径补进 DRIVER_ID_ALIASES(现表规范 id 是 mongo、且缺 turso)。
• 岔口 (2) 批准:把 turso 式 typed UnsupportedDriverError 推广到所有「无本地默认」的 kind(mysql / postgres / mongodb),两侧一致,不再各自兜一个错误的默认。
• 岔口 (3):--database-driver help 文案与文档表由统一词表推导,不再手写第三份清单。

排程:本卡与 #6469 是同一条解析缝(resolveDatabaseUrl / storage-driver.ts),顺序落 —— #6469 落地后派发本卡,避免同文件撞车。

---

Generated by Claude Code