Skip to content

Commit cccbc61

Browse files
committed
no-mistakes(document): Document #258 PK-move refusal in migrate guide
1 parent e0deec4 commit cccbc61

1 file changed

Lines changed: 26 additions & 0 deletions

File tree

‎docs/features/migrations-and-drift.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,32 @@ cycle, rebuild the tables, then restore it) or break the cycle in your metadata.
9797
self-referencing table (a table whose own foreign key targets itself) is not a cycle
9898
in this sense and is handled by the cascade like any other rebuild.
9999

100+
#### A moved primary key (adoption-time refusal)
101+
102+
The diff/emit has no `add-primary-key` / `drop-primary-key` change kind, so an **existing**
103+
table whose live `PRIMARY KEY` differs from the metadata identity cannot be expressed as a
104+
migration. When adopting such a database (`--from-db`), `meta migrate` now **refuses at
105+
generation time** instead of emitting un-appliable SQL — detect-and-refuse, the same arc as
106+
[#226](https://github.com/metaobjectsdev/metaobjects/issues/226)→[#241](https://github.com/metaobjectsdev/metaobjects/issues/241)
107+
for the D1 foreign-key rebuilds above. It throws a `PrimaryKeyChangeError` (naming the table
108+
and both PKs), the CLI catches it and exits 1
109+
([#258](https://github.com/metaobjectsdev/metaobjects/issues/258)).
110+
111+
Previously the move degraded **silently** into an add-column + drop-column: the old PK
112+
column and its constraint were dropped while the new column was never made primary key,
113+
leaving the table with no primary key, so every foreign key referencing it failed at apply
114+
(`there is no unique constraint matching given keys`). This surfaces only when **adopting**
115+
an existing database whose PK disagrees with the metadata — a greenfield `create-table`
116+
carries its primary key inline.
117+
118+
The check is engine-wide (`postgres` / `sqlite` / `d1` — the diff is shared) and runs
119+
**after** rename detection, mapping live PK column names through any detected
120+
`rename-column` change, so a primary-key column that was merely **renamed** (the engine
121+
preserves the PK through `RENAME COLUMN`) is not mistaken for a move. The read-only
122+
`meta verify` / drift path does not set the refusal flag, so `verify` keeps **reporting**
123+
primary-key drift rather than throwing. Auto-migrating the move (adding the
124+
`add-primary-key` / `drop-primary-key` change kinds) is a documented future follow-up.
125+
100126
### Java
101127

102128
Schema migrations for Java projects are owned by the **TypeScript toolchain**

0 commit comments

Comments
 (0)