Безпечний search-replace у WordPress через WP-CLI

Чому прямий SQL або sed можуть пошкодити WordPress

WordPress часто зберігає налаштування у форматі PHP serialization. У такій структурі разом із текстом записується його довжина. Наприклад, рядок може мати вигляд a:1:{s:3:"url";s:18:"https://old.example";}. Якщо замінити адресу на довшу або коротшу без перерахунку довжини, PHP не зможе правильно прочитати значення.

Такі дані трапляються в wp_options, wp_postmeta, wp_usermeta, таблицях плагінів і полях конструкторів сторінок. Наслідками можуть бути зникнення налаштувань, помилки плагіна, порожні віджети або повідомлення про пошкоджені serialized data.

Звичайний SQL UPDATE або масова заміна через sed не розуміють структуру серіалізованих масивів. Вони змінюють символи, але не знають, які довжини потрібно оновити. WP-CLI search-replace створений саме для такого сценарію.

• Не редагуйте дамп бази звичайним пошуком і заміною, якщо не перевіряєте всі формати даних.
• Не замінюйте лише значення в wp_options: адреси можуть бути в контенті, мета-полях і таблицях плагінів.
• Враховуйте точний варіант адреси: http або https, www або без www, а також наявність кінцевого слеша.

Підготовка до заміни домену

Перед запуском команди визначте кореневу директорію потрібного WordPress. У ній зазвичай знаходиться wp-config.php. Це важливо на сервері з кількома сайтами: помилка в шляху може призвести до роботи з іншою базою даних.

Зробіть резервну копію бази даних і переконайтеся, що її можна відновити. Backup має бути доступним до початку операції, а не створюватися після невдалого search-replace. Якщо сайт критичний, спочатку протестуйте міграцію на staging-копії.

Також перевірте, чи доступний WP-CLI від імені користувача, який має доступ до файлів WordPress і бази даних. Команду краще запускати з кореня сайту, а не з випадкової директорії.

• Підготуйте дамп бази та, за потреби, резервну копію файлів.
• Перевірте, що старий і новий URL записані без помилок.
• З’ясуйте, чи є у базі таблиці плагінів із тим самим префіксом, що й таблиці WordPress.
• Не виконуйте операцію на production без перевіреного backup.
• Якщо доступно кілька сайтів, явно вкажіть правильний шлях до WordPress.

cd /var/www/example.com
wp core is-installed
wp option get home
wp option get siteurl

Які варіанти URL потрібно врахувати

Одна міграція не завжди охоплює всі варіанти адреси. Наприклад, у базі можуть залишитися http://old.example, https://old.example, http://www.old.example або URL із кінцевим слешем. Спочатку визначте, які значення реально використовуються, а потім виконуйте окремі, контрольовані заміни.

Не слід бездумно замінювати лише назву домену в будь-якому тексті. Домен може зустрічатися в email-адресах, webhook-налаштуваннях, ключах API або зовнішніх інтеграціях. Перед операцією оцініть контекст знайдених збігів.

Базова команда WP-CLI search-replace

Для типової міграції домену можна почати з dry-run і пропустити поле guid. Параметр --all-tables-with-prefix охоплює всі таблиці, назви яких починаються з префікса WordPress, а не лише стандартні wp_posts або wp_options.

Значення в лапках потрібно передавати точно. Якщо в URL є спеціальні символи, використовуйте одинарні лапки в shell або інший безпечний спосіб екранування.

• --dry-run показує очікувані зміни, але не записує їх у базу.
• --all-tables-with-prefix дає змогу перевірити таблиці багатьох плагінів із відповідним префіксом.
• --skip-columns=guid виключає колонку guid із заміни.
• Після аналізу dry-run ту саму команду можна виконати без --dry-run.

wp search-replace \
'https://old.example' 'https://new.example' \
--all-tables-with-prefix \
--skip-columns=guid \
--dry-run

Виконання після перевірки

Якщо звіт відповідає очікуванням, backup створений, а сайт працює з правильною базою, повторіть команду без прапорця --dry-run. Не змінюйте пошуковий рядок або параметри між перевіркою та фактичним запуском без нової перевірки.

wp search-replace \
'https://old.example' 'https://new.example' \
--all-tables-with-prefix \
--skip-columns=guid

Як перевірити результат dry-run

Звіт WP-CLI показує таблиці, колонки та кількість знайдених збігів. Не оцінюйте результат лише за загальною кількістю: важливо побачити, у яких саме таблицях і полях буде виконана заміна.

Нуль збігів не завжди означає проблему. Можливо, сайт уже використовує новий домен, пошуковий рядок відрізняється протоколом або команда запущена не з тієї інсталяції. Велика кількість збігів у контенті, навпаки, може бути нормальною під час міграції, але її потрібно зіставити зі структурою сайту.

Якщо у звіті з’явилися таблиці плагіна або нестандартні колонки, перевірте документацію цього плагіна. Деякі продукти зберігають дані у форматі JSON, стислому або зашифрованому вигляді. WP-CLI коректно обробляє стандартні serialized PHP-структури, але не може безпечно розпакувати довільний формат, про який він не знає.

• Перевірте назви таблиць і колонок у звіті.
• Порівняйте кількість збігів із очікуваним обсягом контенту та налаштувань.
• З’ясуйте причину, якщо заміна не знаходить жодного значення.
• Не запускайте операцію повторно без потреби: повторна заміна може бути зайвою або змінити дані, якщо пошукові рядки перетинаються.

wp search-replace \
'https://old.example' 'https://new.example' \
--all-tables-with-prefix \
--skip-columns=guid \
--dry-run \
--report-changed-only

Що робити з GUID і кастомними таблицями

Колонка guid у wp_posts має спеціальне призначення. Це глобальний ідентифікатор запису, а не звичайне поле для відображення поточного URL сторінки. Тому під час типової міграції її часто пропускають через --skip-columns=guid.

Якщо є конкретна причина змінювати GUID, це потрібно робити свідомо після перевірки наслідків. Не варто включати поле лише тому, що в ньому залишилася стара адреса. Зміна GUID не є стандартним способом виправлення canonical URL, внутрішніх посилань або адреси сайту.

Параметр --all-tables-with-prefix охоплює таблиці з префіксом, вказаним у wp-config.php. Якщо плагін створив таблицю з іншим префіксом або без нього, вона може не потрапити до операції. Такі таблиці потрібно перевірити окремо та обробляти лише за документацією плагіна або після аналізу структури.

• За замовчуванням залишайте guid виключеним, якщо немає чіткої причини для його зміни.
• Перевіряйте нестандартні таблиці, особливо у складних плагінах і системах імпорту.
• Не додавайте всі таблиці бази навмання: сторонні таблиці можуть містити журнали, кеш або дані в несумісному форматі.

Перевірка сайту після search-replace

Після фактичної заміни перевірте значення home і siteurl, відкрийте головну сторінку, кілька записів, сторінки з медіа та форми. Окремо протестуйте авторизацію, адмін-панель, пошук, кошик або checkout, якщо сайт використовує електронну комерцію.

Перевірте, чи не залишилися посилання на старий домен у контенті, віджетах, меню та налаштуваннях плагінів. Для цього можна повторно запустити search-replace у dry-run зі старою адресою. Очікуваний результат — відсутність або зрозумілий залишок у полях, які навмисно не змінювалися.

Після міграції очистіть кеш WordPress, серверний кеш, CDN і кеш плагінів, якщо вони використовуються. Також перевірте robots.txt, XML-карту сайту, SSL-сертифікат, редиректи зі старого домену та налаштування зовнішніх інтеграцій.

• Перевірте home і siteurl через WP-CLI.
• Зробіть повторний dry-run для старого URL.
• Перегляньте сторінки з різними типами контенту та зображеннями.
• Перевірте email-відправлення, API, webhook і платіжні інтеграції.
• Зафіксуйте помилки PHP і HTTP 4xx/5xx після міграції.

wp option get home
wp option get siteurl
wp search-replace \
'https://old.example' 'https://new.example' \
--all-tables-with-prefix \
--skip-columns=guid \
--dry-run

Типові помилки та безпечна стратегія відновлення

Найчастіша помилка — запуск команди без backup або з неправильним шляхом до WordPress. Інші ризики: переплутаний протокол, заміна лише в стандартних таблицях, зміна GUID без потреби та спроба обробити за допомогою WP-CLI зашифровані або нестандартно стиснуті дані.

Якщо після операції зникли налаштування або сайт почав повертати помилки, не виконуйте хаотичні повторні заміни. Збережіть звіт команди й журнали помилок, тимчасово обмежте зміни на сайті та відновіть базу з перевіреної копії, якщо причина не очевидна.

Після відновлення повторіть процес на staging: спочатку перевірте точні URL, потім зробіть dry-run, перегляньте таблиці й лише після цього виконайте заміну. Такий підхід зазвичай швидший за ручне виправлення пошкоджених serialized data.

• Не редагуйте вручну пошкоджені серіалізовані рядки без розуміння їхньої структури.
• Зберігайте backup до та після міграції.
• Після великої міграції перевірте не лише фронтенд, а й адмін-панель та фонові завдання.
• Якщо дані плагіна зашифровані або мають власний формат, використовуйте штатний інструмент цього плагіна.