Repository navigation
Commit 8c75f83
feat(driver-sql): SQL Server as a federation-only dialect (#31381)
<!-- claude-projects-attribution: {"github_login":"marchtian"} -->
_Requested by **田騏** · [project
thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSi7ghxnTm51PSygb4ygX2wUJ)_
Fixes #31327
Clause-②: yes (widening)
Metadata-protocol: added
Skills-docs: generated only —
`skills/objectstack-data/references/_index.md` gains the
`driver/mssql.zod.ts` row (`gen:skill-refs`); no hand-written skill text
changes.
## 维护者速读
- **改了什么**:外部数据源新增 SQL Server(`driver: 'mssql'`,别名 `sqlserver` /
`tedious`),只做联邦:能读写已有的 SQL Server 表,Studio 能列出 `dbo.Orders`
这类表并导入为对象;平台永不在 SQL Server 上建表或改表,managed 数据源声明它会在解析时被拒。
- **为什么改**:企业客户的业务数据大量在 SQL Server(ERP、财务库)。没有这个方言之前,driver-sql 把它当
`unknown`,文本匹配在 SQL Server 默认不区分大小写的排序规则下答错,分页语法也不合法。
- **风险与回滚**:新增驱动行与新方言分支,其余驱动行为不变。已与先落地的
Oracle(#31351)对齐成一套名字和机制:联邦专用判断、选择面类型、managed 拒绝消息、DDL 拒绝渲染都用 Oracle
的;两边的 lossy 规则合成一张表 `DIALECT_LOSSY_RULES`,Oracle
的结果不变。另改了一个检查脚本:`check-driver-conformance` 把联邦套件(SQL Server 和
Oracle)单列报告,不计入托管矩阵覆盖。回滚即整体 revert。
- **先看**:①
`packages/spec/src/data/driver/config-registry.zod.ts`(federationOnly
列与选择面类型)②
`packages/drivers/driver-sql/src/sql-driver-predicate-emitters.ts` 的
mssql 文本匹配分支(BIN2 + TRANSLATE)③ `scripts/check-driver-conformance.mjs` 的
federation 立场(新语义)。
- **两分钟验证**:`pnpm --filter @objectstack/driver-sql exec vitest run
src/sql-driver-mssql-dialect.test.ts`,预期 15 条全过;有 SQL Server 时设
`OS_TEST_MSSQL_URL` 跑联邦一致性套件,预期 227/227。
- **需要你做的**:ADR-0015 §4.6 改动属受管面(Tier H),需要你批准;contract review
owed(Fable 不可用,按默认档)。
## What changes
- **`@objectstack/spec`**: the driver vocabulary gains `mssql` (aliases
`sqlserver`, `tedious`), a second `federationOnly` row after Oracle's
(#31351), with `hasLocalDefault: false`. #31351's
`FEDERATION_ONLY_DRIVER_IDS`, `isFederationOnlyDriver()`,
`FederationOnlyDriverId` and `DatabaseSelectionDriverId` now answer both
drivers, and a `managed` datasource declaring `mssql` meets the same
parse-time refusal as `oracle` (`federationOnlyDriverOnManagedRefusal`,
which names the drivers that can be managed from
`DATABASE_DRIVER_SELECTION_IDS`). `MssqlConfigSchema` is the closed
config (`host`, `port` 1433, `instanceName`, `database`, `username`,
`ssl`); an inline password, a URL and `autoMigrate` are refused with the
reason. The boot-host selection tables are built without federation-only
rows, so the withdrawal holds by the column, not by the row's empty
`aliases`. `type-compat` gains `SqlDialect` `'mssql'` and
`DIALECT_ALIASES.mssql`. Oracle's exact-to-lossy demotion
(`DIALECT_DEMOTED_TO_LOSSY`) and this PR's added lossy pairing are now
ONE table, `DIALECT_LOSSY_RULES`, one rule per (dialect, canonical type)
with `demoteExact` and `addLossy`, both only ever toward `'lossy'`:
`oracle` / `uuid` keeps its demotion unchanged, and on `mssql` a text
column backs a `json`, `tags` or `multiselect` field as `'lossy'`,
because SQL Server keeps JSON in `nvarchar(max)` and the driver stores
those fields there. A self-signed server is documented as the
datasource-level `ssl: { enabled: true, rejectUnauthorized: false }`:
the block's `enabled` defaults to false, and a block without it turns
encryption off. ADR-0015 §4.6 lists the dialect and the one lossy table,
and §5.1's federation-only arm (from #31351) names both drivers and that
no boot host selects either.
- **`@objectstack/driver-sql`**: `dialectName` reads `'mssql'`. Paging
is `OFFSET … FETCH` with an ORDER BY (the caller's keys, else the
table's single-column primary key read from the catalog, else `(SELECT
NULL)`), and `limit: 0` is `TOP (0)`. Identifiers are `[]`-quoted. Text
predicates keep the #6518 contract on case-insensitive collations:
case-exact through `Latin1_General_100_BIN2`, folded with `TRANSLATE`,
`%` `_` `[` escaped with a bound ESCAPE. A `bit` aggregand is cast for
SUM/AVG/MIN/MAX. Writes use `OUTPUT inserted.*` through a temp table, so
a table with triggers accepts them. A `uniqueidentifier` reads back in
the canonical lower-case form (tedious `lowerCaseGuids`, unless the host
sets it), so the `uniqueidentifier` to `uuid` type-compat row holds: a
GUID written as a string reads back as that string and filters by it in
either case. Dates bind as ISO text against `nvarchar` columns. JSON
text columns read back. Introspection lists user tables as
`schema.table` with primary keys, foreign keys, single-column uniques
and indexes. Managed DDL is refused (`SQL_DIALECT_EMISSION_UNSUPPORTED`)
through #31351's `'federation-only'` reason and its renderer, which
names the client it refuses; this PR's own vendor-named renderer is
gone. `coreSqlDialectOf` maps `mssql` to `'unknown'` as it does
`oracle`. Paging falls back from the caller's keys to the column the
binding's `columnMap` maps to `id` (#31378), then to the catalog key.
And `$contains` / `$empty` on a multi-value field is refused instead of
approximated.
- **`@objectstack/service-datasource`**: the factory builds `SqlDriver`
with the `tedious` connection (server, port, database, user, the bound
secret as password, encrypt / trustServerCertificate / instanceName / CA
from config and the datasource `ssl` block) and reports `@@VERSION`.
`resolveSslOption` moves unchanged to the leaf module
`datasource-ssl-option.ts`, so the connection pins load no driver; the
liveness ledger's five citations of it are repointed. The Studio
connection form does not offer `mssql`; it is declared in code (optional
`tedious` peer, federation-only).
- **Docs**: `content/docs/data-modeling/external-datasources.mdx` gains
"8. SQL Server (federation only)", after Oracle's §7; `drivers.mdx`
lists it next to Oracle; the reference page
`references/data/driver-mssql.mdx` is generated.
- **`scripts/check-driver-conformance.mjs`**: a suite that names
`MSSQL_FEDERATION_CELL` or `ORACLE_CELL` is a federation suite. It is
listed on its own line under the dialect axis and is never counted as
managed-matrix coverage, so it cannot discharge a managed DEBT entry
(driver-sql's `UNIQUE_NULL_DISTINCT` debt stays) or trip MATRIXED.
`FEDERATION_CELL_SYMBOLS` is the list a further federation-only dialect
appends to. Self-test gains three assertions.
## Tests
- `sql-driver-mssql-dialect.test.ts`: 15 offline pins, one per emitter
arm (OUTPUT, emission refusal, the lower-case GUID connection option,
each text operator, JSON-array refusals, paging, aggregands,
qualified-name split). Runs everywhere, no server.
- `sql-driver-mssql-federation-conformance.test.ts`: the shared
case-sets FILTER_LOGIC, FILTER_TEXT, FILTER_COMPARAND_TYPE, TEMPORAL,
TEMPORAL_TIME, PAGINATION (incl. unordered and zero-limit), AGGREGATION,
VALUE_ROUNDTRIP, UNIQUE_NULL_DISTINCT (filtered unique indexes),
READABLE_IDS, plus a write block on a table with a trigger and a
default, and a `uniqueidentifier` block (create answers the GUIDs as
written; equality and `$in` match in either case; update by a GUID id
lands); CROSS_FIELD is asserted as the federated-object refusal. Built
with raw DDL plus `registerExternalObject` in a per-file schema.
- The live cell is opt-in: `OS_TEST_MSSQL_URL` provisions it,
`OS_EXPECT_MSSQL_FEDERATION=1` makes an unprovisioned run fail. No CI
job hosts SQL Server, so in CI it is a declared skip, and the
live-dialect coverage report prints `live sql server (federation) NOT
RUN`.
- `mssql-connection.test.ts` (service-datasource, 6 tests, two of them
the datasource `ssl` block through the spec parse, `resolveSslOption`
and `buildMssqlConnection`: `enabled: true` keeps `encrypt` on with
`trustServerCertificate`, and a block without it is `encrypt: false`), a
table-wide pin that no spelling of a federation-only row resolves on the
selection face, the CLI driver-vocabulary parity pin (a federation-only
driver resolves its contract, and `os start` refuses it in dev and prod
even with a URL), the credential-slot pin and the analytics echo-bucket
roster gain `mssql`.
- Tests that used `mssql` as the stand-in for an unmodelled dialect now
use `UnmodelledKnexClient` (`unmodelled-knex-client.testkit.ts`).
## Acceptance notes
Known gaps, stated so nobody reads them as covered:
- Column-map handling on `update()` / `delete()` / `bulkDelete()` /
`aggregate()` / `distinct()` landed on main with #31349 and is merged in
here; this PR does not touch those paths.
- A table whose key is an IDENTITY column cannot be written through the
platform (the insert names the key); keep such a datasource read-only.
- JSON-array membership (`$contains` on a multi-value field) and
`$empty` on one are refused on mssql.
- Date buckets run in memory: the dialect advertises no native date
granularity.
- service-analytics' native-SQL face still uses plain LIKE for mssql:
#31394.
- A table with no single-column primary key pages in an order SQL Server
does not guarantee; the driver warns.
- Cross-field `$field` comparisons are refused on federated objects on
every dialect (existing behaviour).
- SQL Server 2017 is the floor (`TRANSLATE`).
- Substring operators on a `uniqueidentifier` column compare against SQL
Server's own upper-case text form of the GUID; filter a GUID by equality
(documented in the SQL Server section): #31395.
- The Studio connection form does not offer `mssql` yet: #31389 tracks
offering it there as federation-only.
- The spec API surface widens by 4 exports, all `MssqlConfig*` (listed
in `api-surface/data.json`); the federation-only names are #31351's.
## Verification
Head `b22da50f83`, merged with `origin/main` at `b91dc73d33` (after
#31351). The contract review of `dfc8a224c5` was answered on
`194571ae2f` (delta PASS); this head carries the reconcile, should-fix
5.
<details><summary>Live SQL Server (local container, SQL Server 2022
image, TZ=America/New_York)</summary>
`OS_TEST_MSSQL_URL=... OS_EXPECT_MSSQL_FEDERATION=1 vitest run
sql-driver-mssql-federation-conformance.test.ts
sql-driver-mssql-dialect.test.ts`: 2 files, 227 passed on this head.
Coverage reporter: `live sql server (federation) RAN`.
</details>
<details><summary>Package suites and typechecks</summary>
- `@objectstack/driver-sql` full suite: 241 files passed, 13 skipped;
3899 tests passed, 219 skipped (no live server env). `tsc --noEmit`
clean.
- `@objectstack/spec` full suite: 821 files, 25977 passed, 1 todo
(before the refusal-message change; the config-registry and datasource
files re-run after it, 556 passed). `check:test-typecheck` OK.
`check:generated` OK after a spec build.
- `@objectstack/service-datasource` full suite on this head: 74 files,
1291 passed. `tsc --noEmit` clean.
- `@objectstack/spec` `src/data` on this head: 163 files, 6064 passed.
`check:generated` 14 of 14 current, `check:llms-txt` OK.
- `@objectstack/driver-sql` full suite on this head: 244 files passed,
13 skipped; 4085 tests passed, 220 skipped (the Oracle dialect pins
included). `tsc --noEmit` clean.
- `@objectstack/service-analytics` echo-bucket enumeration: 236 passed.
- `@objectstack/cli` driver-vocabulary parity: 131 passed;
database-driver flag derivation: 11 passed. `tsc --noEmit` clean.
- `@objectstack/runtime` dev-auto-migrate: 7 passed. `tsc --noEmit`
clean.
- ESLint (`--no-inline-config`) over every changed `.ts`/`.mjs` file:
clean.
</details>
<details><summary>dispatch-gates</summary>
On `f8388ce29e`: `node scripts/pm/dispatch-gates.mjs --ran` 146 derived
families, 146 run, 0 NOT-MEASURED, every exit code 0; the 60
artifact-roster and wide-population families also run, all 0 except the
four that need the workflow's PR context (closing-target, Part-of,
single-claim paths, governed queue guard), which CI ran green. CI then
found `check:facade-delegation-only` (a roster family) and the
dropped-refinements header count; both fixed here. The sweep on each new
head is posted as a separate comment.
</details>
Not run here: SQL Server in CI (no job provisions it; the cell is a
declared skip there). Full dogfood is not owed (Clause-② is a widening
and the title carries no `!`).
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_017ihL2g4TsRRELWgXKEF8H3
<!-- signed: epic:#27261#1 · marchtian ·
session_017ihL2g4TsRRELWgXKEF8H3 -->
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent e3ab0aa commit 8c75f83
60 files changed
Lines changed: 2603 additions & 170 deletions
File tree
- .changeset
- content/docs
- data-modeling
- references
- data
- docs
- adr
- audits
- 2026-07-unknown-key-strictness-ledger.counts
- packages
- cli/src/utils
- drivers/driver-sql/src
- services
- service-analytics/src/__tests__
- service-datasource/src
- __tests__
- spec
- api-surface
- authorable-defaults
- authorable-surface
- declaration-map
- export-origins
- json-schema.manifest
- liveness
- src/data
- driver
- scripts
- skills/objectstack-data/references
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
81 | 81 | | |
82 | 82 | | |
83 | 83 | | |
| 84 | + | |
84 | 85 | | |
85 | 86 | | |
86 | 87 | | |
| |||
104 | 105 | | |
105 | 106 | | |
106 | 107 | | |
| 108 | + | |
107 | 109 | | |
108 | 110 | | |
109 | 111 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
583 | 583 | | |
584 | 584 | | |
585 | 585 | | |
| 586 | + | |
| 587 | + | |
| 588 | + | |
| 589 | + | |
| 590 | + | |
| 591 | + | |
| 592 | + | |
| 593 | + | |
| 594 | + | |
| 595 | + | |
| 596 | + | |
| 597 | + | |
| 598 | + | |
| 599 | + | |
| 600 | + | |
| 601 | + | |
| 602 | + | |
| 603 | + | |
| 604 | + | |
| 605 | + | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
| 618 | + | |
| 619 | + | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
| 630 | + | |
| 631 | + | |
| 632 | + | |
| 633 | + | |
| 634 | + | |
| 635 | + | |
| 636 | + | |
| 637 | + | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
| 641 | + | |
| 642 | + | |
| 643 | + | |
| 644 | + | |
| 645 | + | |
| 646 | + | |
| 647 | + | |
| 648 | + | |
| 649 | + | |
| 650 | + | |
| 651 | + | |
| 652 | + | |
| 653 | + | |
| 654 | + | |
| 655 | + | |
| 656 | + | |
| 657 | + | |
| 658 | + | |
| 659 | + | |
| 660 | + | |
| 661 | + | |
| 662 | + | |
| 663 | + | |
| 664 | + | |
| 665 | + | |
| 666 | + | |
| 667 | + | |
| 668 | + | |
| 669 | + | |
| 670 | + | |
| 671 | + | |
586 | 672 | | |
587 | 673 | | |
588 | 674 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
| 22 | + | |
22 | 23 | | |
23 | 24 | | |
24 | 25 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
30 | 30 | | |
31 | 31 | | |
32 | 32 | | |
| 33 | + | |
33 | 34 | | |
34 | 35 | | |
35 | 36 | | |
| |||
0 commit comments