Uh oh!
There was an error while loading. Please reload this page.
feat(runtime): the standalone default datasource is a declaration, connected through the one datasource path (#3826) - #3869
Merged
os-zhuang merged 1 commit intoJul 28, 2026
Conversation
…nnected through the one datasource path (#3826) ADR-0062 D1 asked for exactly one "definition → live driver" path. Construction converged earlier; connect + failure verdict did not — the standalone `default` was pre-built and smuggled into the engine as a `driver.*` kernel service, so "what if it cannot connect" lived in `ObjectQLEngine.init()`, a second implementation of the policy `DatasourceConnectionService` owns for every other datasource. #3741 → #3758 showed what two copies cost. - `createStandaloneStack` emits a datasource DEFINITION; the new `DefaultDatasourcePlugin` connects it through the shared connection service. The connect happens in init() with a hard dependency on ObjectQLPlugin: the kernel resolves BOTH phases from the dependency graph, so list position proves nothing — the first cut connected in start() and a serve boot hoisted ObjectQL ahead of it, shipping a server with no tables (caught by the dev:crm smoke, fixed by phase separation: all inits precede all starts). - `bootCritical` on ConnectableDatasource: a third D5 fail-fast cause — the host declares the platform cannot run without it; shares OS_ALLOW_DRIVER_CONNECT_FAILURE and the DEGRADED BOOT banner. The default deliberately bypasses the connect policy (byte-for-byte with the old boot; that gate exists for optional datasources). - `connect(record, { asDefault: true })`: registers under the driver's natural name with isDefault, guarded by engine.getDefaultDriverName() idempotency. start() replays through the shared service so the primary DB shows a real status in Setup → Datasources (#3827). - `sqlite-wasm` joined the shared driver factory (last bespoke construction). - `default` is host-reserved: rejected in app bundles at load (AppPlugin) and in runtime-admin create. - The `driver.<name>` kernel service is still registered (os migrate's findSqlDriver and serve's storage detection read it); ObjectQL's discovery loop no-ops on it via the engine's skip-if-present guard. - serve's hasDriver detection counts DefaultDatasourcePlugin as a driver provider so the storage-driver fallback doesn't build a duplicate pool. The config-load fallback (createStorageDriver, mysql/turso, telemetry coupling) remains a tracked second site in #3826. - ObjectQLEngine.init() unchanged: it re-connects the already-connected default (all open-core drivers' connect() is idempotent) — the #3741 verification role D1 leaves it. Verified end to end: dev:crm --fresh creates the same 71 tables as unmodified main (the broken intermediate produced 10), zero "no such table", authenticated data reads serve seeded rows, and the artifact-serve path boots with `default` status 'ok' and no duplicate driver. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TQVM3A9Yd6N2eZS8ZcdnMk
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 4 package(s): 42 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 28, 2026 13:26
Uh oh!
There was an error while loading. Please reload this page.
os-zhuang
deleted the
claude/explicit-datasource-connection-fallback-5b83d0
branch
July 28, 2026 13:26
This was referenced Jul 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
按 #3826 讨论中的方案 B 落地(部分完成 —— 见末尾余项;issue 保持 open)。
改动
createStandaloneStack不再构建 driver,而是产出default的 datasource 定义(URL→config 翻译和mkdir仍归 host),由新的DefaultDatasourcePlugin在启动期通过共享的DatasourceConnectionService连接 —— 同一个 factory、同一份失败判决(bootCritical⇒ D5 fail-fast,新增的第三条判据)、同一个OS_ALLOW_DRIVER_CONNECT_FAILURE逃生阀、同一份留存状态(主库终于在 Setup → Datasources 显示真实status,#3827 补全)。配套:
sqlite-wasm进入共享 factory(sqlite-wasm/wasm-sqlite),消灭最后一处 bespoke 构造。default成为 host 保留名:app bundle 声明即在装载时被拒(AppPlugin),runtime-admin 创建同样拒绝 —— 此前是未定义行为(shadow + 静默改道)。connect(record, { asDefault: true }):driver 保留自然名(路由走引擎的 default fallback,从不经drivers.get('default')),以isDefault注册,幂等守卫走新增的engine.getDefaultDriverName()。default刻意不过 connect policy(与旧 boot 逐字节一致 —— 那道门为可选/外部 datasource 而设;测试钉死了「deny-all policy 不能挡住主库」)。ObjectQLEngine.init()不改:它对已连接的 default 再 connect 一次(五种开源 driver 的connect()均幂等,逐一核实过),恰好保留 ObjectQLEngine.init() 吞掉 driver 连接失败：连不上数据库的服务器照常启动，driver 的启动期致命错误被降级成运行时报错 #3741 要的启动校验角色。driver.<name>kernel service 仍然注册 ——os migrate的findSqlDriver和 serve 的 storage 探测靠它;ObjectQL 发现循环对同名 driver 是 skip-if-present,no-op。冒烟测试抓住并修掉的两个真实回归
诚实记录,这两个都是单元/集成测试没抓住、真机启动抓住的:
resolveDependencies),serve 全量 boot 里 ObjectQL 被更早注册的服务插件的依赖边提前,我的 plugin 的 start 排到了 schema sync 之后 —— 服务器起得干干净净,然后dev:crm --fresh只建出 10 张表(对照 main:71 张),所有业务对象查询报no such table。修法:connect 挪进 init()(Phase 1 全部完成才进 Phase 2,任何拓扑下都先于 sync),并声明对 ObjectQL 的硬依赖(保证'data'service 先注册)。start()再经共享服务 replay 一次(幂等命中already-registered),让判决落进 admin 列表读取的状态里。os migrate靠driver.*service 定位 SQL driver —— 新路径起初没注册它,CLI 集成测试红。补上注册,全部消费方(schema-migrate、serve storage 探测、发现循环)保持兼容。另:serve 的
hasDriver探测教会识别DefaultDatasourcePlugin,避免 config-load fallback 再建一份重复 pool(第一次冒烟抓到的双构造)。验证
dev:crm --fresh在本分支与未修改 main 上各跑一次 —— 两边同为 71 张表、零no such table;认证登录 +GET /api/v1/data/crm_account返回 seed 数据;artifact-serve 路径(quickstart/生产形态)boot 后default状态ok、无重复 driver。pnpm build全量、examples typecheck、ESLint、changeset 门禁全绿。degraded-boot-parity.test.ts继续全绿 —— 两条 connect 路径的运维契约(fail-fast 默认、旗标解析逐值一致、stderr banner)未漂移。ADR 与文档
bootCritical、自然名 +asDefault、分层反转为何未发生(runtime host 编排,ObjectQL 无感知)、以及余项。drivers.mdx补一段declareddefault的说明与保留名规则。余项(#3826 保持 open)
CLI serve 的 config-load fallback(
createStorageDriver+DriverPlugin):它还承载共享 factory 不支持的 mysql/turso,且 telemetry sibling-datasource 的供给耦合在它的解析结果上 —— 是剩下的第二构造点,连同 cloud-stack 的自组路径一起留在 issue 里。在它们收敛前,parity test 继续作为漂移守卫。Generated by Claude Code