WordPress CLIの wp search-replace コマンドについて、基本的な使い方や安全に置換するための主要オプション、SQLでの置換との違い、AI エージェントが実行した場合の危険性と自動実行許可の判断基準を紹介しています。

wp search-replaceとは

wp search-replace は、WordPressのデータベース内の特定の文字列を検索し、別の文字列へ一括置換するためのWP-CLIコマンドです。
このコマンドの最大の特徴は、WordPressのデータベースに多く含まれる「シリアライズされたデータ（配列やオブジェクトが文字列化されたもの）」を壊すことなく、安全に置換できる点にあります。

主要なオプションの意味

オプション	意味
--dry-run	データベースに変更を加えずに、置換対象となる箇所とプレビュー結果のみを表示します（事前確認に必須）。
[table]	特定のテーブルのみを置換対象として指定します（例: wp_posts）。
--all-tables	マルチサイト環境などを含め、データベース内のすべてのテーブルを検索・置換対象にします。
--export=[file.sql]	直接データベースを書き換えずに、置換後のデータをSQLファイルとして書き出します。

本番適用する前に、必ず --dry-run オプションを付与して影響範囲や件数を確認することが、このコマンドを使う上での鉄則です。

よく使う組み合わせ

置換予定の件数を確認する（Dry Run）

wp search-replace 'http://old-domain.com' 'https://new-domain.com' --dry-run

実際にデータベースを書き換えることなく、指定した古いドメインから新しいドメインへの変更が、どのテーブルで何件発生するかをシミュレーションして表示します。

特定のテーブルのみ置換を実行する

wp search-replace '旧テキスト' '新テキスト' wp_posts

投稿本文やタイトルが格納されている wp_posts テーブルのみを対象に一括置換を実行します。
対象を絞ることで、設定値（options）などを巻き込んで意図しない不具合が発生するリスクを抑えられます。

ドメイン移行に伴う本番データベースの置換実行

wp search-replace 'http://localhost/wp' 'https://repop.jp'

ローカル開発環境のURL設定を本番環境のドメインへ一括書き換えします。
シリアライズデータ内の文字列長のカウントも自動で修正されるため、テーマ設定やウィジェットが壊れるのを防ぎます。

wp search-replace vs SQL (REPLACE関数) の違い

データベース内の置換はSQLのクエリ（UPDATE文）でも実行可能ですが、以下のような決定的な違いがあります。

項目	wp search-replace	SQL UPDATE ... REPLACE()
シリアライズデータの維持	完璧に対応（文字列の文字数情報も自動で再計算・更新）	非対応（文字数がずれるため、PHP側でデータが破損・消失と判定される）
事前テスト（Dry-Run）	コマンドのオプションで簡単に実行可能	事前にSELECTクエリなどで複雑な集計が必要
手軽さ	コマンド1行で全テーブルを走査可能	テーブルやカラムごとにクエリを個別作成する必要がある

PHPオブジェクトのシリアライズ形式（s:19:"http://old..." のように文字数が記録される形式）でデータが保存されているWordPressにおいては、SQLで直接置換するとデータが破損します。
安全な移行と設定保持のためには、必ず wp search-replace を使用すべきです。

ユースケース

サイトのSSL化（HTTPS移行）に伴う内部リンク修正

Webサイトを常時SSL化した際、投稿内の画像パスや内部リンクが http:// のまま残っていると混在コンテンツ警告が出ます。
これを一括で https:// に書き換えてリンクエラーを解消します。

開発環境と本番環境のドメイン同期

ローカルで構築したWordPressサイトのデータベースを本番サーバーへインポートした際、サイトの稼働ドメインを一瞬で本番URLへ同期・変換させます。

AIエージェントが実行しようとした場合

AIエージェントの目的

AIエージェントは主に次のような目的で wp search-replace を実行しようとすることがあります。

• 開発用のローカルURLと本番用のドメイン環境を自動で同期するため
• 複数の過去投稿に共通して含まれる誤字脱字や不要なタグを一括で修正・クリーンアップするため

危険性

wp search-replace コマンドは、データベース全体を書き換える極めて影響範囲の大きいコマンドです。
もし検索文字列や置換文字列の指定を誤った場合、サイトの設定情報が破壊されたり、意図しない場所のテキストが巻き添えで書き換えられたりし、サイト全体が真っ白になる（動作停止する）危険性があります。

自動実行の許可設定

このコマンドは、誤設定によるデータベース破損という不可逆的な大事故を引き起こす可能性が高いため、AIエージェントの自動実行（許可）設定はオフ（要承認）にすることを強く推奨します。
実行前に人間が置換のクエリ、および --dry-run による置換予定件数の結果を確認した上で、承認の手続きを取るべきです。