FT17: schema-diff — ADR-0009 を実装する (cli/schemaDiff.php)

[hideyukiMORI]

Trial

NeNe Field Trial 17 — schema-diff CLI 実装 (ADR-0009 採用 Option C)。

Clone: `/home/xi/github/NeNe-FT/ft17-schema-diff` (port 8097/3324, baseline post-#416).

Why this trial

ADR-0009 (`docs/adr/0009-schema-migration-story.md`) で「operator-applied `cli/schemaDiff.php`」を Option C 採用、実装は別 trial に deferred と明記した。本 trial で実装する。

評価レポート `REPORT_commercial_feasibility.md` (PR #401) が指摘した commercial NeNe deployments の最大懸念 (migration 機構の欠如) に対する明示的な resolution の最終ピース。

Goal

`cli/schemaDiff.php` を新規作成:

• DB introspection (MySQL: INFORMATION_SCHEMA / SQLite: PRAGMA table_info)
• live schema vs `SchemaDefinition::buildTables()` を diff
• 以下を ALTER TABLE / CREATE TABLE / CREATE INDEX として emit:
  • Add column (ADR-0009 initial scope)
  • Add table
  • Add index
• 以下は warning のみ (operator hand-write):
  • Drop column / Drop table / Drop index
  • Column type change
  • Column rename
  • Constraint changes (UNIQUE / FOREIGN KEY / CHECK)
  • Default-value-only changes

CLI は apply しない (operator が SQL を redirect / 確認 / 実行する flow)。

Acceptance criteria

• `php cli/schemaDiff.php --dsn=mysql:host=127.0.0.1;port=...;dbname=nene --user=nene --pass=nene` が現状一致なら "schema is in sync" を出力し exit 0
• `SchemaDefinition` に new column を追加 → diff CLI が `ALTER TABLE ... ADD COLUMN ...` を 1 行出力 (default値も含む)
• `SchemaDefinition` に new table を追加 → diff CLI が `CREATE TABLE ...` を出力
• live schema に extra column がある (= definition から drop された) → warning が stderr に出る、SQL は emit しない
• SQLite mode (`--dsn=sqlite:...`) でも MySQL と同じ shape の出力
• Unit test: 5+ cases (sync / add-column / add-table / drop warning / unknown change warning)
• composer test 全部 green、format/Phan も green

Out of scope (per ADR-0009)

• Drop / type-change / rename / constraint-change の SQL 自動生成
• Auto-apply (operator が常に実行する flow を維持)
• Multi-version migration history

Aftermath

• Trial report at `docs/field-trials/2026-05-field-trial-17.md`
• ADR-0009 の "implementation tracking" section に PR # を cross-link
• `docs/development/schema-migrations.md` を新規作成 (workflow + out-of-scope list)
• Follow-up Issues (発見 friction)

[hideyukiMORI]

FT17 完了。Report PR #418、follow-up Issues:

• FT17 feat: SchemaDiffer + cli/schemaDiff.php + SchemaCompiler promote + composer schema:diff (#417) #419 (feat) — SchemaDiffer + cli/schemaDiff.php + SchemaCompiler promote + composer schema:diff + tests
• FT17 docs: schema-migrations.md + ADR cross-links + AGENTS + --help expand (#417) #420 (docs) — schema-migrations.md + ADR cross-links + AGENTS + --help expand
• FT17 follow-up (F-5): SchemaDiffer に add-index path を追加する #421 (follow-up F-5) — add-index path

ADR-0002 cadence: 全 close 後に FT18 へ。