ShopMagicで重複カラムエラーが出る原因とデータベース接頭辞の修正

ShopMagicで重複カラムエラーが出る原因とデータベース接頭辞の修正

ShopMagic 4.8.6以前のバージョンで、データベースアップグレード中に「カラムが重複しています（Duplicate column name ‘note_context’）」というエラーが発生する場合、原因はプラグイン内部のマイグレーションファイルでテーブル接頭辞が wp_ に固定されていることだ。バージョン4.8.7へのアップデートで修正されるが、すぐにアップデートできない場合は、データベースのオプション値を直接編集する緊急回避策でエラーを止められる。

なぜShopMagicで重複カラムエラーが発生するのか

ShopMagicには、プラグインが更新されるたびにデータベースのテーブル構造を自動調整する「マイグレーション」機能が備わっている。今回の問題は、マイグレーションファイル Version_42.php の17行目付近で発生する。このファイルは、note_context というカラムが既に存在するかどうかを確認するために SHOW COLUMNS クエリを実行するが、その際に対象テーブルを wp_shopmagic_automation_outcome_logs と決め打ちしてしまっている。

サイトのデータベース接頭辞（wp-config.php の $table_prefix）がデフォルトの wp_ であれば問題は出ない。しかし、セキュリティや複数サイト運用の都合で接頭辞を abc123_ などに変更している場合、wp_shopmagic_automation_outcome_logs というテーブルは存在しないため、SHOW COLUMNS が失敗する。その結果、プラグインは「カラムが存在しない」と誤認し、note_context を追加しようとする。しかし実際には正しい接頭辞のテーブルに既に存在するため、ALTER TABLE が「カラムが重複しています」というエラーで失敗する。

さらに深刻なのは、このエラーによってマイグレーションチェーン全体が止まってしまう点だ。Version 42が失敗として記録されないため、後続のVersion 43から48のマイグレーションがいっさい実行されない。これにより、マーケティングリストやトラッキングメール関連のテーブルが不足し、気付かないうちに一部機能が不完全になる可能性がある。また、エラーはページが読み込まれるたびに繰り返し発生し、デバッグログを大量に汚染する。

データベースエラーを解消するアップデート手順

根本的な解決策は、ShopMagicをバージョン4.8.7以降にアップデートすることだ。このバージョンでは、マイグレーションファイル内のハードコードされた wp_ が削除され、動的に正しいテーブル接頭辞を参照するように修正されている。

管理画面から自動アップデートする

WordPress管理画面の「プラグイン」→「インストール済みプラグイン」で、ShopMagicに利用可能なアップデートが表示されていれば、「今すぐ更新」をクリックする。アップデート後、データベースのアップグレードが正常に走り、エラー通知が消えていることを確認する。

手動でアップデートする

自動アップデートが利用できない場合は、公式リポジトリまたは有料版の提供元から最新のZIPファイルをダウンロードし、管理画面の「プラグイン」→「新規追加」→「プラグインのアップロード」から上書きインストールする。既存の設定やデータが失われることはないが、不安な場合は事前にサイト全体のバックアップを取得しておく。

アップデートできない場合の緊急回避策

何らかの理由ですぐにプラグインをアップデートできない場合、データベースのオプション値を直接書き換えることでエラーの無限ループを止められる。この方法は、マイグレーションVersion 42が「未完了」として記録されているために毎回実行される状態を、「完了」とマークするものだ。Version 42が実際に行うべきテーブル変更（カラム追加）はエラーを起こしながらも既に成功しているため、安全性は高い。

変更を保存して管理画面を再度読み込むと、ShopMagicはVersion 42のマイグレーションが完了したと認識し、続けてVersion 43から48の未実行マイグレーションを順次処理する。これにより、不足していたテーブルが自動的に作成され、エラー通知も消える。なお、マイグレーション44では既存のオプトインメールデータを作成済みのマーケティングリストテーブルにコピーする処理が含まれるため、データ量によってはページの読み込みに時間がかかることがある。

よくある質問

エラーが解消された後、不足していたテーブルは自動的に作られるのか

アップデートまたはオプション値の書き換え後、ページを読み込んだタイミングで自動的に不足テーブルが作成される。Version 43から48のマイグレーションが順次実行され、マーケティングリストテーブルやトラッキングメールテーブルなどが生成される。特別な操作は不要だ。

データベース接頭辞をデフォルトのwp_に変更すれば直るのか

接頭辞の変更はサイト全体に影響を与える大掛かりな作業であり、推奨しない。テーブル名の一括置換やwp-config.phpの編集、シリアライズ化データの再計算などが必要になる。このエラーはプラグイン側の問題であり、ShopMagicをアップデートするだけで解決するため、そちらを優先する。

この問題はShopMagic以外のプラグインでも起きるのか

プラグインが内部でデータベース接頭辞をwp_に決め打ちしている場合、全く同じメカニズムでエラーが発生する。ただし、多くのプラグインはWordPressの$wpdb->prefixを用いて動的に接頭辞を取得するため、一般的な問題ではない。カスタム接頭辞を使用しているサイトで特定のプラグインだけがエラーを起こす場合、同様のハードコードが原因である可能性を疑うとよい。

phpMyAdminから直接オプション値を変更するのが不安だ

WP-CLIが利用できる環境であれば、wp option update shopmagic_db 'WPDesk\ShopMagic\migrations\Version_42' --format=plain というコマンドで安全に同じ変更が行える。phpMyAdminを使う場合でも、該当行の編集後すぐに管理画面を開き、エラー通知が消えたことを確認すれば問題ない。

この記事のポイント

• エラーの直接原因は、マイグレーションファイル内でテーブル接頭辞が wp_ に固定されていること
• カスタム接頭辞を使うサイトでは、毎回のページ読み込みでエラーが繰り返される
• ShopMagicをバージョン4.8.7以降にアップデートすれば根本解決する
• アップデートできない場合、shopmagic_db オプションを手動で進める緊急回避策がある
• 回避策を取ったあと、後続のマイグレーションが自動実行され不足テーブルも作成される

佐々木 太陽

・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている