DB構造とマイグレーションの不一致を調べる

1. このページで伝える機能

DB項目不足・列型の不一致・マイグレーション履歴の問題を切り分け、データ保持が必要なDBと作り直せる開発DBで対応を分けます。

2. Wagby11で実現できること

2.1 最初のエラーとDBの実態を確認する

Javaの再生成だけでは、保存済みDDLやDBの構造が必ず置き換わるわけではありません。起動ログの最初の原因、対象のテーブル・列、接続しているDB、適用済みのマイグレーションを確認します。

たとえばJava側のcreatedByが文字列でも、DBにcreated_by BIGINTが残っていれば型が一致しません。生成ログの「自動生成対象の追加DDLなし」は、実DBとの整合性を確認済みという意味ではありません。

2.2 共通DDLとアプリのDDLを分けて確認する

共通基盤のDDLはcommon、AppSchemaから生成するDDLはappとして独立した履歴で管理し、common、appの順に適用してからJPAがテーブル・列を検証します。履歴テーブルはflyway_common_schema_historyとflyway_app_schema_historyです。システムモデルだから常にcommonという分類ではなく、DDLの管理元で分かれます。

適用済みSQLの書き換えや履歴の削除で、実DBを変更したことにはなりません。Flywayのrepairも履歴を修復する操作であり、DBの列型を変換する操作ではありません。

2.3 データを保持するDBでは追加マイグレーションを用意する

既存データを保持する場合は、適用済みSQLを変えず、型変換・制約・参照先への影響を確認した追加マイグレーションを用意します。バックアップを取得し、検証環境で変換とアプリの通常操作を確認します。AppSchemaの型を直すことと、保存済みデータを変換することを別の作業として計画します。

入力例や必要なデータ保持範囲をAIへ伝え、変換不能な値の扱いも相談します。項目変更の基本は既存項目の型変更、データの移送は異なる定義への移送を参照してください。

2.4 作り直せる開発用H2はDBとDDLを組で再構築する

データを引き継がずに作り直せる既定の開発用H2では、restapiのgenerateの再構築オプションを使えます。まず計画だけを表示し、対象DBとDDLの配置、退避先を確認します。本番やデータ保持が必要なDBへ適用しません。

./generate.sh --rebuild-dev-db
# 対象と計画を確認し、REST API・Web UI・更新ジョブを停止してから実行
./generate.sh --rebuild-dev-db --execute

Windowsはgenerate.batで同じオプションを使います。--executeはDBとapp用DDLを組で退避して再生成・クリーンビルドします。DBだけを空にして古いDDLを残すと、同じ不一致を再作成する場合があります。

この処理は旧データの移送、テスト、アプリの起動まで行うものではありません。失敗時も退避済みの旧DBと旧DDLを自動で元へ戻しません。ログと退避先を保存し、原因を確認してから次の作業へ進みます。

3. AIへの指示例

最小限の指示例

DBの型が合わず起動できません。データを残して直す方法を調べてください。

AIは起動ログ、生成Java、AppSchema、実DBと履歴を確認し、保持するデータに応じた修正案を補います。開発用か本番か、データを破棄できるかを明示します。最小限の指示だけで次の詳細例と同じ手順になるとは限りません。

より詳細な指示例

起動ログの最初の原因から、対象テーブル・列、foundとexpecting、接続先DB、common/appの履歴と適用済みDDLを照合してください。生成ログに追加DDLなしとあっても整合確認済みとは判断しないでください。
データを保持するDBでは適用済みSQLを変更せず、追加マイグレーションと型変換の検証計画を提示します。repairや履歴削除で列型が直るとは扱いません。
別案として、破棄できる既定の開発用H2に限り、generateの--rebuild-dev-dbで計画を表示し、DBとapp用DDLを組で退避する手順を示してください。まず調査結果と計画を提示し、データの削除・再構築は実行しないでください。

4. 編集されるAppSchemaの例

調査のためだけにAppSchemaを書き換える必要はありません。対象項目の定義、生成Java、実DBの列型を照合します。次は文字列として扱う監査項目の定義例です。これだけで既存DBのBIGINT列が文字列へ変換されるわけではありません。

# 対象モデルのattributesの抜粋
- name: 登録者
  name_en: createdBy
  type: string
  reserved: true

5. 参考資料

guide：トラブルシューティング

designer/docs/appschema/html/guide/appendix/04-troubleshooting.html

Java共通基盤：データベース構成とマイグレーション

designer/docs/java/html/29_database_migrations.html