☰
WORDPRESS / PRACTICE

Надійні міграції бази даних плагіна WordPress без падіння production

Надійні міграції бази даних плагіна WordPress без падіння production

Зміна структури таблиць плагіна — це не просто додавання кількох SQL-запитів до оновлення коду. У production міграція може виконуватися на великій базі, конкурувати із запитами користувачів, перевищити ліміт часу або завершитися посередині.

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

Чому register_activation_hook() не підходить для звичайних оновлень

register_activation_hook() запускається під час активації плагіна, а не під час кожного оновлення його файлів. Якщо користувач оновив плагін із версії 1.4 до 1.6, код активації зазвичай не буде виконано повторно. Через це нова колонка або індекс можуть не з’явитися, хоча код уже очікує їх наявності.

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

Не варто також виконувати довгу міграцію безпосередньо під час першого запиту адміністратора. Вона може спричинити PHP timeout, блокування таблиці або помилку через обмеження хостингу. Для великих обсягів краще розділяти зміну структури та перенесення даних.

  • Активація — для початкового налаштування, а не єдиний механізм оновлення схеми.
  • Міграції мають запускатися незалежно від того, чи було плагін деактивовано та активовано повторно.
  • Довгі операції потрібно виносити у WP-Cron, WP-CLI або інший контрольований процес.

Зберігайте версію схеми окремо від версії плагіна

Версія плагіна описує реліз коду, а версія схеми — стан бази даних. Це різні поняття. Один реліз може містити кілька послідовних змін таблиць, а користувач може оновитися через кілька версій одразу.

Для простої установки можна зберігати номер у WordPress option, наприклад my_plugin_db_version. Для multisite важливо заздалегідь визначити область зберігання: окремо для кожного сайту чи на рівні всієї мережі. Якщо таблиці створюються з префіксом конкретного сайту, версію зазвичай також потрібно обробляти окремо для кожного блогу.

Міграції слід виконувати послідовно. Наприклад, схема 1 створює таблицю, схема 2 додає колонку status, а схема 3 переносить дані у цю колонку. Не варто одразу перевіряти лише версію 3 і пропускати попередні кроки: між ними можуть бути необхідні перетворення даних.

  • Використовуйте цілі числа або інший однозначний формат, який легко порівнювати.
  • Після успішного завершення конкретного кроку записуйте нову версію.
  • Не підвищуйте версію наперед: якщо SQL або обробка даних завершилися помилкою, крок має бути доступним для повторного запуску.
  • Розділяйте міграції структури та важкі міграції даних, якщо вони можуть тривати довго.
$current_version = (int) get_option('my_plugin_db_version', 0);\n$target_version  = 3;\n\nfor ($version = $current_version + 1; $version <= $target_version; $version++) {\n    my_plugin_run_migration($version);\n    update_option('my_plugin_db_version', $version, false);\n}

Проєктуйте кожну міграцію ідемпотентною

Ідемпотентна міграція безпечно переносить повторний запуск. Це особливо важливо, коли процес перервано після виконання частини SQL, але до запису нової версії. Повторний запуск не повинен ламати таблицю або дублювати дані.

Перед ALTER TABLE перевіряйте, чи існує таблиця, колонка або індекс. Назви таблиць та колонок у SQL потрібно формувати лише з контрольованих значень, а не з даних користувача. Для значень використовуйте підготовлені запити.

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

  • Перевіряйте існування таблиці перед її створенням.
  • Перевіряйте колонку перед ADD COLUMN, якщо SQL-діалект і версія MySQL не гарантують безпечний IF NOT EXISTS для конкретної операції.
  • Для перейменування колонок передбачайте сценарій частково виконаного кроку.
  • Не покладайтеся лише на номер версії: фактичний стан таблиці також потрібно перевіряти.
  • Логічно відокремлюйте DDL-зміни, конвертацію даних і створення індексів.
global $wpdb;\n$table = $wpdb->prefix . 'my_plugin_items';\n\n$table_exists = $wpdb->get_var(\n    $wpdb->prepare('SHOW TABLES LIKE %s', $table)\n);\n\nif ($table_exists === $table) {\n    $column_exists = $wpdb->get_var(\n        $wpdb->prepare('SHOW COLUMNS FROM `' . esc_sql($table) . '` LIKE %s', 'status')\n    );\n\n    if (!$column_exists) {\n        $wpdb->query('ALTER TABLE `' . esc_sql($table) . '` ADD COLUMN `status` varchar(20) NOT NULL DEFAULT \'new\'');\n    }\n}

Коли використовувати dbDelta(), а коли — окремі міграції

dbDelta() з пакета WordPress добре підходить для базової синхронізації опису таблиці: створення таблиці або додавання простих змін у її структурі. Його часто використовують під час первинного встановлення та для нескладних схем.

Однак dbDelta() не є повноцінною системою міграцій. Він не переносить дані між колонками, не знає бізнес-логіки перетворення значень і не замінює контрольоване перейменування колонок. Також складні індекси, зміна типів і видалення старих полів потребують окремого тестування.

Опис таблиці для dbDelta() має бути сумісним із його правилами розбору: кожне поле та індекс краще подавати в очікуваному форматі, а результат виконання перевіряти. Навіть якщо dbDelta() не повернув явну помилку, після операції варто перевірити фактичну структуру таблиці.

  • Використовуйте dbDelta() для початкової або простої синхронізації таблиці.
  • Для перенесення даних пишіть окрему міграцію з пакетною обробкою.
  • Не видаляйте стару колонку в тому самому релізі, де ще може працювати код, який її читає.
  • Складні індекси та зміни типів спочатку перевіряйте на копії production-даних.
require_once ABSPATH . 'wp-admin/includes/upgrade.php';\n\n$sql = "CREATE TABLE {$wpdb->prefix}my_plugin_items (\n    id bigint(20) unsigned NOT NULL AUTO_INCREMENT,\n    status varchar(20) NOT NULL,\n    created_at datetime NOT NULL,\n    PRIMARY KEY  (id),\n    KEY status (status)\n) {$wpdb->get_charset_collate()};";\n\ndbDelta($sql);

Обробляйте великі обсяги даних пакетами

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

Пакетна міграція бере обмежену кількість рядків, обробляє їх і зберігає прогрес. Для навігації краще використовувати keyset-підхід: запам’ятовувати останній оброблений id і вибирати записи з більшим id. OFFSET на великих таблицях може ставати повільнішим у міру просування.

Після кожного пакета зберігайте курсор або кількість оброблених записів. Якщо cron-запуск перервався, наступний процес продовжить роботу, а не почне все спочатку. Розмір пакета потрібно підбирати за навантаженням конкретного сайту, а не вважати універсальним.

  • Вибирайте записи за стабільним індексованим ключем.
  • Оновлюйте лише необхідні поля.
  • Не завантажуйте всю таблицю в пам’ять PHP.
  • Після пакета перевіряйте помилки та фіксуйте прогрес.
  • Для критичних таблиць плануйте міграцію на період низького навантаження.
$last_id = (int) get_option('my_plugin_migration_3_last_id', 0);\n$batch_size = 200;\n\n$rows = $wpdb->get_results(\n    $wpdb->prepare(\n        "SELECT id, legacy_value FROM {$table}\n         WHERE id > %d AND new_value IS NULL\n         ORDER BY id ASC LIMIT %d",\n        $last_id,\n        $batch_size\n    )\n);\n\nforeach ($rows as $row) {\n    $new_value = my_plugin_convert_value($row->legacy_value);\n    $wpdb->update($table, ['new_value' => $new_value], ['id' => $row->id]);\n    $last_id = (int) $row->id;\n}\n\nupdate_option('my_plugin_migration_3_last_id', $last_id, false);

Запускайте міграції через WP-Cron або WP-CLI

WP-Cron зручний для автоматичного виконання пакетів, але його запуск залежить від відвідувань сайту та налаштувань хостингу. Для великих сайтів або передбачуваного обслуговування краще використовувати системний cron, який викликає WP-CLI. У будь-якому разі міграція повинна мати можливість виконатися повторно без пошкодження даних.

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

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

  • Один cron-запуск має виконувати обмежений обсяг роботи.
  • Не покладайтеся на браузерний запит як на єдиний спосіб завершити міграцію.
  • Логуйте помилки без запису конфіденційних даних.
  • Додавайте режим dry-run або команду перевірки, якщо операція критична.
  • Після завершення видаляйте тимчасові cron-події та службові option.
if (!get_transient('my_plugin_migration_lock')) {\n    set_transient('my_plugin_migration_lock', 1, 5 * MINUTE_IN_SECONDS);\n\n    try {\n        my_plugin_process_next_batch();\n    } finally {\n        delete_transient('my_plugin_migration_lock');\n    }\n}

Перевірки перед запуском у production

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

Протестуйте всі переходи версій на staging-копії даних: зі старої схеми на нову, після часткового виконання, після помилки в середині пакета та при повторному запуску. Перевірте також оновлення через кілька версій одразу, де користувач не запускає кожен реліз окремо.

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

  • Зробіть резервну копію перед DDL-операціями та масовим оновленням.
  • Перевірте міграцію на staging із даними, близькими до production за обсягом і структурою.
  • Підготуйте план відкату: відновлення backup, вимкнення нового коду або зворотне перетворення даних.
  • Переконайтеся, що права користувача БД дозволяють потрібні операції.
  • Після релізу спостерігайте за логами, часом запитів і помилками плагіна.

Типові помилки в міграціях WordPress-плагінів

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

Інша проблема — використання одного великого UPDATE для всіх даних або виконання міграції на кожному запиті без перевірки. Це створює непередбачуване навантаження та може погіршити роботу сайту. Також небезпечно безумовно додавати колонку: повторний запуск завершиться помилкою «column already exists».

Не слід видаляти старі поля одразу після додавання нових, якщо різні веб-вузли, cron-процеси або кешовані PHP-файли можуть короткий час працювати з різними версіями коду. Спочатку додайте сумісну структуру, перенесіть дані, переключіть читання й запис, а видалення виконайте окремим кроком.

  • Не вважайте активацію плагіна гарантією запуску міграції після оновлення.
  • Не використовуйте dbDelta() як заміну міграціям даних.
  • Не запускайте довгі операції в адміністративному HTTP-запиті без обмеження часу.
  • Не зберігайте прогрес лише в пам’яті поточного процесу.
  • Не перевіряйте успіх тільки за відсутністю PHP-помилки — контролюйте фактичний стан БД.

Поширені запитання

Де найкраще запускати перевірку міграцій?

Можна виконувати легку перевірку під час завантаження плагіна або адміністративного запиту, але не саму довгу роботу. Перевірка має побачити, що версія схеми застаріла, і запланувати пакет через WP-Cron або передати виконання WP-CLI.

Чи достатньо dbDelta() для оновлення таблиці?

Для простого створення таблиці або базової синхронізації структури — часто так. Але dbDelta() не замінює перенесення даних, складні перейменування, контроль прогресу та сценарії відновлення після часткового виконання.

Що робити, якщо міграція впала після кількох пакетів?

Не позначайте її завершеною. Збережений курсор має дозволити продовжити роботу з останнього успішного пакета. Повторний запуск повинен перевірити вже оброблені записи та не створити дублікати.

Чи потрібен backup перед додаванням однієї колонки?

Так, якщо зміна виконується на production і таблиця важлива для роботи плагіна. Навіть проста DDL-операція може виявити проблеми з правами, місцем на диску, блокуваннями або несумісністю структури.

Висновок

Надійна міграція WordPress-плагіна — це керований процес, а не SQL-запит, захований у register_activation_hook(). Зберігайте окрему версію схеми, виконуйте зміни послідовно та робіть кожен крок ідемпотентним.

Для великих таблиць використовуйте пакетну обробку з постійним прогресом, блокуванням від паралельного запуску та виконанням через WP-Cron або WP-CLI. Перед production обов’язково створюйте й перевіряйте резервну копію, тестуйте сценарій на staging і контролюйте фактичний результат у базі даних.

← Усі матеріали WordPress