Repository navigation
Commit cee4b16
fix(metadata-protocol): land the NULL-safe sys_setting / sys_notification_preference identity on PostgreSQL, and never report a no-op as created (#26782)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XUEEEpJPSpQ64pHamCtDAD3)_
Fixes #26630
Clause-②: no
Metadata-protocol: none
## 维护者速读
- **改了什么**:PostgreSQL 上 `sys_setting` 与 `sys_notification_preference`
的空值安全行身份(`COALESCE(user_id, '')`)现在真正落库;落不了时启动日志如实报出,不再假报成功。
- **为什么改**:18.2.0 在 PG 上声明的唯一键是约束而非索引,迁移的 `DROP INDEX` 被拒(2BP01),随后
`CREATE … IF NOT EXISTS` 空转却报 `created`,同一组织同一设置键可存两行,读设置时没有确定的胜者。
- **风险与回滚**:只动启动迁移在 PG 上的删除与判定;SQLite/MySQL
的建删语句与结果不变。有重复数据时照旧不删不并、保留旧键,只多报计数。回滚即回退本 PR。
-
**先看**:`packages/metadata-protocol/src/migrations/partial-index-probe.ts`(`probeThenReplaceIndexPostgres`
与
`freePostgresIndexName`)、`identity-index.live-postgres.test.ts`、`sys-setting-identity-index.ts`
冲突分支。
- **两分钟验证**:`OS_TEST_POSTGRES_URL=postgres://… pnpm --filter
@objectstack/metadata-protocol exec vitest run
identity-index.live-postgres`,预期 7 个测试全过;在 `origin/main` 上同一命令 5 个红。
- **需要你做的**:无,席位落地。
## What changes
`probeThenReplaceIndex` (the shared seam both identity migrations use)
gets a PostgreSQL arm, selected when the caller passes the table and the
seam's knex client:
1. **The drop frees what actually holds the name.** On PostgreSQL the
declared unique is a UNIQUE CONSTRAINT (`SqlDriver.syncDeclaredIndexes`
→ knex `table.unique()` → `ALTER TABLE … ADD CONSTRAINT … UNIQUE`). The
replace step now runs `ALTER TABLE t DROP CONSTRAINT IF EXISTS name`
then `DROP INDEX IF EXISTS name`, which is the spelling the driver's own
`dropIndexIfExists` already uses (dialect-chosen, constraint first). No
`CASCADE`.
2. **`created` means the definition is in place.** The probe's
definition is read with `pg_get_indexdef(to_regclass(…))` before the
probe is dropped; after the real create, the real name's definition is
read the same way and must be equal (compared from ` ON ` onward).
Anything else is `status: 'failed'`, `failedAt: 'verify'`, with the
drop's refusal in `detail`, so each caller prints its existing ADR-0120
D4 `could not rebuild …` line naming what is not enforced, and the boot
keeps running.
3. **Existing duplicates are reported with a count.** The `conflict`
lines of both migrations now carry `(N duplicated key(s), held by M
row(s))`, counted by wrapping each migration's own duplicate probe in
`SELECT COUNT(*), SUM(duplicate_rows) FROM (…)`. Counts only, no row
values. No row is deleted or merged; the previous key stays (unchanged
behaviour).
Both callers (`sys-setting-identity-index.ts`,
`notification-preference-identity-index.ts`) pass `table` and `client`;
`overlay-index.ts` passes neither and keeps the dialect-blind order.
`read-probe.ts` exports its existing `catalogFamilyOf` so the two
modules share one reading of which client is PostgreSQL. `driver-sql` is
not touched.
SQLite stays byte-for-byte on the probe, the drop, the create and the
outcome: a unit test pins the identical statement stream for `sqlite3`,
`better-sqlite3`, `mysql2`, an unnamed client, and a `pg` caller that
names no table. The one addition on every dialect is the count query,
run only after a `conflict` outcome.
## Tests
- `identity-index.live-postgres.test.ts` (new, live PostgreSQL, same
harness and isolation as `seed-tenancy-backfill.live-postgres.test.ts`;
fixture constraints are the exact knex-compiled statements). Both
tables: the constraint is replaced by the COALESCE index and the
duplicate insert is refused (23505); a second run is quiet and
identical; with duplicates present the result is `conflict`, the
constraint stays, no row is deleted, and the line carries the count and
no value; a name the drop cannot free (a foreign key depends on the
constraint, so 2BP01 without `CASCADE`) is `failed`, never `created`.
- `partial-index-probe.test.ts`: the PostgreSQL arm's exact statement
order and no `CASCADE`; the verify failure naming the refusal; a probe
whose definition cannot be read fails at `probe` before the real name is
touched; the legacy order for every other client; `countDuplicateKeys` /
`describeDuplicateKeys`.
- `sys-setting-identity-index.test.ts`,
`notification-preference-identity-index.test.ts` (SQLite): the conflict
line carries the count.
## Acceptance notes
- **CI lane.** The new live file is selected by name by the existing
`Run the metadata-protocol migration statements against live MySQL and
PostgreSQL` step (`vitest run live-mysql live-postgres`). That step
lives in the `Temporal Conformance (live PG + MySQL)` job, whose `if:`
excludes `pull_request` and `merge_group`, so its first CI run is
`main`'s push battery after the merge. No new job or gate was added; the
local live runs below are the pre-merge evidence.
- The verify read-back runs only on PostgreSQL; MySQL never reaches the
replace step (its dialect refuses the probe, `unsupported`).
## Verification
Local PostgreSQL 16.15. Base = `origin/main` `5cc31c788`.
<details><summary>Red on base: os dev boot on an empty
PostgreSQL</summary>
Boot log (`objectstack dev --seed-admin --no-watch -d
postgres://…/os26630_red`, app-showcase, base build):
```text
[sql-driver] DATABASE_ERROR — the backend refused a raw statement (2BP01). … cannot drop index uniq_sys_setting_organization_id_namespace_key_scope_user_id because constraint uniq_sys_setting_organization_id_namespace_key_scope_user_id on table sys_setting requires it
[sql-driver] DATABASE_ERROR — the backend refused a raw statement (2BP01). … cannot drop index uniq_sys_notification_preference_a22d7d27 because constraint uniq_sys_notification_preference_a22d7d27 on table sys_notification_preference requires it
✓ Server is ready
```
`pg_indexes` / `pg_constraint` after the boot:
```text
uniq_sys_setting_… ON public.sys_setting USING btree (organization_id, namespace, key, scope, user_id)
uniq_sys_notification_preference_a22d7d27 ON public.sys_notification_preference USING btree (organization_id, user_id, topic, channel)
pg_constraint: both names present, contype u
```
Copy of the tenant-scope `localization/timezone` row under a new id, in
a transaction: `INSERT 0 1`, count 2, rolled back.
The new live suite on the base source: 5 failed, 2 passed (7).
</details>
<details><summary>Green: same boot after the fix</summary>
Three boots, no `2BP01` and no `[metadata-protocol]` line on any: (1)
over the red database above (the upgrade path), (2) on an empty
database, (3) a second boot over (2).
Both databases afterwards:
```text
uniq_sys_setting_… ON public.sys_setting USING btree (organization_id, namespace, key, scope, COALESCE(user_id, ''::character varying))
uniq_sys_notification_preference_a22d7d27 ON public.sys_notification_preference USING btree (organization_id, COALESCE(user_id, ''::character varying), topic, channel)
constraints holding either name: 0
duplicate tenant-row insert: ERROR: duplicate key value violates unique constraint "uniq_sys_setting_organization_id_namespace_key_scope_user_id"
```
Conflict boot (constraint restored and one duplicate tenant row
inserted, then booted on the fix): one `ERROR [metadata-protocol] cannot
tighten 'uniq_sys_setting_…' on "sys_setting" — existing rows violate
(organization_id, namespace, key, scope, COALESCE(user_id, '')) (1
duplicated key, held by 2 rows). The previous index is left in place …`,
`Server is ready`, the duplicate row still present, the constraint still
present, and neither the organization id nor the key value appears
anywhere in the log.
The new live suite on the fix: 7 passed (7).
</details>
<details><summary>Package suite, typecheck, lint, gates</summary>
All at head `1d5f19a2b`; every `packages/*/vitest.repo-tests.json`
project's `test:repo` also passes.
- `pnpm --filter @objectstack/metadata-protocol test` with
`OS_TEST_POSTGRES_URL` set (under the verify lock): `VERDICT
command-exit 0`, Test Files 271 passed / 2 skipped (the two live-MySQL
files, no MySQL here), Tests 21599 passed / 12 skipped.
- `pnpm --filter @objectstack/metadata-protocol typecheck`: `VERDICT
command-exit 0` (its `tsc` program lists the migration test files, 16 of
them).
- `eslint --no-inline-config
packages/metadata-protocol/src/migrations/`: exit 0.
- `node scripts/pm/dispatch-gates.mjs --commands` on this diff: 58
commands, each run with its exit code captured before any pipe. 57
exited 0 on the first pass. `check-plugin-teardown-shape.mjs
--self-test` exited 3 on the shallow clone (its pinned fixture commit
was missing); after `git fetch origin 621a487…` it exited 0 (48 cases).
`--ran` reconciliation: `58 derived, 58 run, 0 NOT-MEASURED, 0 UNRUN`.
- Not measured locally, by design: the CI type-check lanes and the
path-scheduled CI jobs the derivation lists outside its total; the
`Temporal Conformance` job (it does not run on PRs, see Acceptance
notes).
</details>
## 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. (not touched)
- [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_01FEkQ5kZqq2RmtHXdiXnRqX
---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5kZqq2RmtHXdiXnRqX)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent c8583f8 commit cee4b16
11 files changed
Lines changed: 834 additions & 13 deletions
File tree
- .changeset
- packages
- metadata-protocol/src/migrations
- types/src
| 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 | + | |
| 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 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
| 246 | + | |
| 247 | + | |
| 248 | + | |
| 249 | + | |
| 250 | + | |
| 251 | + | |
| 252 | + | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
| 256 | + | |
| 257 | + | |
| 258 | + | |
| 259 | + | |
| 260 | + | |
| 261 | + | |
| 262 | + | |
| 263 | + | |
| 264 | + | |
| 265 | + | |
| 266 | + | |
| 267 | + | |
| 268 | + | |
| 269 | + | |
| 270 | + | |
| 271 | + | |
| 272 | + | |
| 273 | + | |
| 274 | + | |
| 275 | + | |
| 276 | + | |
| 277 | + | |
| 278 | + | |
| 279 | + | |
| 280 | + | |
| 281 | + | |
| 282 | + | |
| 283 | + | |
| 284 | + | |
| 285 | + | |
| 286 | + | |
| 287 | + | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
| 292 | + | |
| 293 | + | |
| 294 | + | |
| 295 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
163 | 163 | | |
164 | 164 | | |
165 | 165 | | |
166 | | - | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
167 | 170 | | |
168 | 171 | | |
169 | 172 | | |
170 | 173 | | |
171 | 174 | | |
| 175 | + | |
172 | 176 | | |
173 | 177 | | |
174 | 178 | | |
| |||
0 commit comments