AppCotton は、バージョンアップ時やテーブル構造の変更時に、
WordPress の dbDelta() を使用してデータベースのマイグレーション（更新）を自動的に行います。
しかし、サーバ環境・キャッシュ・途中状態の更新などが原因で、
DBマイグレーションが正常に完了せず、テーブル定義や構造が不整合になることがあります。
この章では、その発生要因と 安全に復旧するための基本手順をまとめます。
1. マイグレーション失敗の典型症状
| 症状 | 備考 |
|---|---|
| プランを追加しても反映されない | product_plans テーブルのカラム不整合 |
| ライセンスが発行できない | licenses テーブルが未更新／壊れている |
| Stripe 決済後にライセンスが生成されない | orders テーブルのキー欠損 |
| 管理画面に「SQL構文エラー」ログが出る | ALTER文の途中失敗が原因 |
2. 原因の代表例
| 原因 | 説明 |
|---|---|
| サーバの MySQL バージョン差 | 5.5 / 5.6 の場合 ALTER が不安定になる |
| カラム定義が途中状態で中断 | プラグイン更新中にタイムアウトが起こった |
| 古いバージョンの AppCotton がキャッシュされている | OPcache / キャッシュプラグイン / CDN |
| マルチサイトで site_id の切り替えが正しく処理されていない | switch_to_blog() 前後のdbDelta不一致 |
3. 最初に試すべき標準復旧手順（安全）
- WordPress 管理画面へログイン
- 左メニュー → AppCotton → 設定
- 画面下部 → 「データベース修復（Repair Database）」 をクリック
- メッセージが出たら 画面を再読み込み
- プラグインを一度無効化 → 再有効化
→ これによりdbDelta()が再実行される
ポイント：「無効化→再有効化」だけで直るケースは非常に多いです。
4. それでも改善しない場合
原因は「ALTER TABLE の途中失敗」
→ 現行テーブルをバックアップして再生成するのが最短かつ安全
手順：
- phpMyAdmin / Adminer でDBにアクセス
- 次の対象テーブルを エクスポート
| テーブル名 | 用途 | 最重要度 |
|---|---|---|
appcotton_products | 製品定義 | ★★★ |
appcotton_product_plans | プラン / 価格情報 | ★★★★★ |
appcotton_licenses | 既存ユーザーのライセンス資産 | ★★★★★ |
appcotton_license_activations | 利用環境ログ | ★★★★ |
appcotton_orders | 決済記録 | ★★★ |
- これらのテーブルを 一旦削除しないこと（データが消えるため）
- AppCotton → 設定 → DB修復を再度実行
- 「構造だけ修復」されたあとで、必要に応じて手動で差分カラムを調整する
5. 手動確認すべきカラム例（チェックリスト）
| テーブル | 欠けやすいカラム | 正しい型 |
|---|---|---|
appcotton_licenses | activation_limit | INT NOT NULL DEFAULT -1 |
appcotton_product_plans | price, stripe_price_id, activation_limit | 設計に合わせる |
appcotton_license_activations | ip | VARBINARY(16)（packed形式） |
ALTER TABLE wp_appcotton_license_activations
MODIFY ip VARBINARY(16) NULL;
など 型の再定義 が必要な場合あり。
6. キャッシュによる「修復完了に見える不具合」への対処
・WP Object Cache
・OPcache (PHP)
・Cloudflare / LiteSpeed Cache / WP Rocket
これらが 古いクラスファイルを読み続け、
「修復されたように見えるけど、実際は昔のSQLが動いている」状態が起きることがあります。
解決策
- サーバの OPcache をクリア
- WordPress のページキャッシュを 全削除
- CDN キャッシュを パージ
7. それでも直らない場合に確認するべきログ
| ログ | 目的 |
|---|---|
PHP error_log | SQL構文エラーの直接原因が出る |
Stripe Webhook Log | ライセンス未生成時の根本原因の切り分け |
wp_appcotton_license_activations の内容 | ドメイン判定不整合を検出 |
8. 相談テンプレート（開発者向け）
問題が再現したとき、次の情報を揃えて問い合わせると最短で解決できます：
AppCotton バージョン:
WordPress / PHP / MySQL バージョン:
発生した動作:
期待していた動作:
該当テーブル dump（構造のみ）:
error_log 抜粋:
まとめ
| 状況 | 解決策 | 優先度 |
|---|---|---|
| マイグレーション失敗直後 | AppCotton → 設定 → DB修復 | ★★★★★ |
| 修復後も不整合が見える | プラグイン再有効化 + OPcacheクリア | ★★★★ |
| カラム欠損が確定している | 手動で ALTER / 再生成 | ★★★★ |
| 状況が複雑 | テーブル構造だけ export → 検証 | ★★★ |
「データを消さずに構造だけ直す」
これが DBマイグレーション対応の基本方針です。