docs(#226): document the D1 referenced-table rebuild refusal

Author: dmealing

CHANGELOG.md

@@ -5,6 +5,21 @@ here. The format follows [Keep a Changelog](https://keepachangelog.com/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 (pre-1.0; MINOR bumps may introduce breaking changes with notice).
 
+## [Unreleased]
+
+### Fixed — `meta migrate --dialect d1` no longer emits an un-appliable rebuild of a foreign-key-referenced table (#226)
+
+npm-only (`migrate-ts` — D1 is a TS-only dialect). On remote Cloudflare D1 a migration
+runs inside D1's implicit transaction, where `PRAGMA foreign_keys = OFF` is a no-op — so
+the SQLite table-rebuild recipe failed to drop a foreign-key-referenced table, aborting
+the migration with `FOREIGN KEY constraint failed`. The failure was silent until a table
+held rows, so it first surfaced against populated production databases. `meta migrate
+--dialect d1` now **refuses at generation time** with a clear, actionable error when a
+change would rebuild a table that another table's foreign key references (self-references
+included), instead of emitting SQL that fails at apply time. Migrations that do not
+rebuild a referenced table are byte-identical. Auto-generating the rebuild cascade is
+tracked as a follow-up (#241).
+
 ## [0.20.6] — 2026-07-26
 
 **Coordinated PATCH** — npm `0.20.6` · PyPI `0.19.8` · Maven Central `7.11.6` · NuGet

docs/features/migrations-and-drift.md

@@ -55,6 +55,22 @@ meta migrate --dialect d1     # Cloudflare D1 dialect (TS-only)
 Dialects: `postgres` (default), `sqlite`, `d1`. Output lands under the path
 configured in `metaobjects.config.ts` (typically `./migrations/<timestamp>__<slug>.sql`).
 
+#### D1 limitation: rebuilding a foreign-key-referenced table
+
+Cloudflare D1 applies each migration inside its own implicit transaction, and SQLite
+ignores `PRAGMA foreign_keys` while a transaction is open. The SQLite table-rebuild
+recipe (used for a `CHECK`, column type/nullability/default, foreign-key, or
+`field.enum` values change) relies on `PRAGMA foreign_keys = OFF` taking effect before
+it drops and recreates the table — which does not happen on remote D1.
+
+To avoid emitting a migration that would fail against a populated production database
+with `FOREIGN KEY constraint failed`, `meta migrate --dialect d1` **refuses at
+generation time** when a change would rebuild a table that another table's foreign key
+references. Apply such a change by hand-writing the migration: rebuild the referencing
+table to temporarily drop its foreign key, rebuild the referenced table, then restore
+the foreign key — or make the change on an unreferenced table. (Auto-generating this
+cascade is tracked as a follow-up.)
+
 ### Java
 
 Schema migrations for Java projects are owned by the **TypeScript toolchain**