Skip to content

Commit e0deec4

Browse files
committed
no-mistakes(document): Document #258 PK-refuse fix in CHANGELOG and bug doc
1 parent 737d324 commit e0deec4

2 files changed

Lines changed: 52 additions & 5 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
77

88
## [Unreleased]
99

10-
Shared-enum cross-package hardening (**#246** + its sibling **#259**). When cut this releases
11-
as a coordinated PATCH — the loader change (#246) lands in all five ports, the Kotlin codegen
12-
changes (#246 Bug 1, #259) land on Maven Central; no metadata vocabulary changes, byte-identical
13-
output for any model that doesn't hit the specific cross-package/two-hop enum shapes below.
10+
Shared-enum cross-package hardening (**#246** + its sibling **#259**), plus an **npm-only**
11+
migrate-ts fix (**#258**). When cut this releases as a coordinated PATCH — the loader change
12+
(#246) lands in all five ports, the Kotlin codegen changes (#246 Bug 1, #259) land on Maven
13+
Central, and #258 lands on npm only (`migrate-ts` + `cli`; schema/migrate is TS-owned, ADR-0015);
14+
no metadata vocabulary changes, byte-identical output for any model that doesn't hit the specific
15+
cross-package/two-hop enum shapes below (and, for #258, any migration that isn't a primary-key
16+
move).
1417

1518
- **#246 — a `field.enum` may now be shared across packages, and a conflicting redeclaration is
1619
rejected instead of silently dropped.** Two independent fixes:
@@ -48,6 +51,35 @@ documented as out-of-scope in the design spec
4851
Kotlin `enumTypeName` collapse gaining the `isAbstract` leg the other ports already carry (so a
4952
root-level *concrete* enum extended with own `@values` gets a per-field enum on every port).
5053

54+
### Fixed — migrate refuses a primary-key move instead of silently dropping the PK (#258)
55+
56+
**npm-only** (`migrate-ts` + `cli`; PyPI / NuGet / Maven Central unchanged — schema migrations are
57+
TS-owned, ADR-0015). The diff/emit has no primary-key change kind, so adopting an existing database
58+
(`--from-db`) whose `PRIMARY KEY` differs from the metadata identity degraded **silently** into an
59+
add-column + drop-column: the old PK column and its constraint were dropped, the new column was
60+
never made PK, leaving the table with **no primary key**, so every foreign key referencing it
61+
failed at apply (`there is no unique constraint matching given keys for referenced table`). Only
62+
observable when adopting an existing DB whose PK disagrees with the metadata — a greenfield
63+
`create-table` carries its PK inline. Follow-on from #255, which is what let the apply clear the
64+
column drops and reach the FK stage where this surfaced.
65+
66+
Migration generation now detects the move and throws a new `PrimaryKeyChangeError` (naming the
67+
table and both PKs) instead of emitting the un-appliable SQL — detect-and-refuse, the #226→#241 arc
68+
for D1 FK cascades being the precedent (auto-migrating the PK remains a follow-up). The check runs
69+
**after** rename detection, mapping live PK column names through any detected `rename-column` for
70+
the table, so a PK column that was merely renamed (the engine preserves the PK through `RENAME
71+
COLUMN`) is not mistaken for a move. It is gated by a `DiffArgs.refusePrimaryKeyChange` flag set
72+
only by the migration-generation paths (the online `meta migrate --db` diff call and the offline
73+
`planOffline`); the read-only `meta verify`/drift path does **not** set it, so `verify` keeps
74+
reporting PK drift rather than throwing. The CLI catches `PrimaryKeyChangeError` at both throw
75+
sites (online + offline, including the D1 path) and emits a structured error + exit 1.
76+
77+
Byte-identical for any migration that is not a primary-key move (the full `migrate-ts` suite passes
78+
unchanged). Gated by 5 unit tests (refuse on a move; no-refuse on an unchanged PK; no-refuse on a
79+
resolved PK-column rename; no-throw without the flag) plus a real-Postgres integration round-trip
80+
(gated on `MIGRATE_TS_PG_URL`) that reproduces the original failure — a live
81+
`user_profiles PK(user_id)` with a referencing FK — and asserts the refusal fires.
82+
5183
## [0.20.10] — 2026-08-02
5284

5385
**Coordinated PATCH** — npm `0.20.10` · PyPI `0.19.9` · NuGet `0.19.7` · Maven Central `7.11.7`.

‎docs/bugs/2026-08-02-no-primary-key-change-kind.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,22 @@ title: "migrate: no primary-key change kind, so moving a table's PK leaves it wi
55
labels: bug
66
---
77

8-
> **Filed as** https://github.com/metaobjectsdev/metaobjects/issues/258 (2026-08-02). Open. Follow-on from #255.
8+
> **Filed as** https://github.com/metaobjectsdev/metaobjects/issues/258 (2026-08-02). **RESOLVED
9+
> (detect-and-refuse).** Follow-on from #255.
10+
>
11+
> Migration generation now refuses a primary-key move instead of emitting un-appliable SQL — the
12+
> second of the two approaches proposed below, chosen deliberately over auto-migrating. It landed
13+
> in `272ee9d5` ("fix(#258): migrate refuses a primary-key move instead of silently dropping the
14+
> PK") and was extended to the D1 path in `737d3244`. The diff throws a new `PrimaryKeyChangeError`
15+
> (naming the table and both PKs) when an existing table's live `PRIMARY KEY` differs from the
16+
> metadata identity; the check runs after rename detection, so a PK column that was merely renamed
17+
> (the engine preserves the PK through `RENAME COLUMN`) is not mistaken for a move. It is gated by
18+
> a `DiffArgs.refusePrimaryKeyChange` flag that only the migration-generation paths set (the online
19+
> `meta migrate --db` diff call and the offline `planOffline`); the read-only `meta verify`/drift
20+
> path does **not** set it, so `verify` keeps reporting PK drift rather than throwing. Gated by 5
21+
> unit tests plus a real-Postgres round-trip on the genuine reproduction. Auto-migrating the PK —
22+
> the `add-primary-key`/`drop-primary-key` change kinds and staging proposed in "Suggested fix"
23+
> below — remains a follow-up. Kept as a written record of the failure mode.
924
1025
**Affected port(s):** TypeScript (diff + emit; shared migration engine, so all ports)
1126
**Package + version:** `@metaobjectsdev/cli` + `@metaobjectsdev/migrate-ts` 0.20.10

0 commit comments

Comments
 (0)