dbDelta() の使い方｜説明・引数・注意点

説明

基本構文

dbDelta( string|string[] $queries = '', bool $execute = true ): array

引数

• $queries：テーブル作成のSQL文
• $execute：実行するか

戻り値

実行した処理の結果の配列。

使い方（サンプル）

require_once ABSPATH . 'wp-admin/includes/upgrade.php';
$sql = "CREATE TABLE {$wpdb->prefix}my_table (
  id bigint(20) NOT NULL AUTO_INCREMENT,
  name varchar(255) NOT NULL,
  PRIMARY KEY  (id)
) {$charset_collate};";
dbDelta( $sql );

注意点

• wp-admin/includes/upgrade.php の読み込みが必要です。
• SQLの書式に厳しい制約があります（PRIMARY KEY の後に半角スペース2つなど）。
• 有効化フックの中で1度だけ呼びます。

実務での使いどころ

• プラグインの有効化時に、独自のテーブルを、作る・更新するとき。
• バージョンアップで、テーブルの構造を、変更するとき。

よくあるミスと対処

• wp-admin/includes/upgrade.php を、読み込んでいない。関数が未定義になる。
• SQLの書式を守らないと、2回目以降の更新（カラムやインデックスの差分の適用）が、正しく動かないことがある。公式の書式（1行1項目、PRIMARY KEY の後ろはスペース2つ、KEY を使うなど）に従う。
• 毎回のリクエストで、実行している。有効化時や、バージョンが変わったときだけにする。
• 文字コードを、指定していない。$wpdb->get_charset_collate() を使う。

NG例

dbDelta( "CREATE TABLE {$wpdb->prefix}logs (id INT PRIMARY KEY, message TEXT)" ); // 書式が違い、ファイルも読み込んでいない

OK例

require_once ABSPATH . 'wp-admin/includes/upgrade.php';
$charset = $wpdb->get_charset_collate();
$sql = "CREATE TABLE {$wpdb->prefix}logs (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  message text NOT NULL,
  PRIMARY KEY  (id)
) $charset;";
dbDelta( $sql );

使い分け早見表

関連項目

register_activation_hook()、$wpdb->query()、$wpdb->prepare()

公式リファレンス：dbDelta() | Function | WordPress Developer Resources