☰
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, например my_plugin_db_version. В multisite важно заранее определить область хранения: отдельно для каждого сайта или на уровне всей сети. Если таблицы создаются с префиксом конкретного сайта, версию обычно также нужно обрабатывать отдельно для каждого блога.

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

  • Используйте целые числа или другой однозначный формат, который легко сравнивать.
  • После успешного завершения конкретного шага записывайте новую версию.
  • Не повышайте версию заранее: если SQL-запрос или обработка данных завершились ошибкой, шаг должен быть доступен для повторного запуска.
  • Разделяйте миграции структуры и тяжёлые миграции данных, если они могут выполняться долго.
$current_version = (int) get_option('my_plugin_db_version', 0);
$target_version  = 3;

for ($version = $current_version + 1; $version <= $target_version; $version++) {
    my_plugin_run_migration($version);
    update_option('my_plugin_db_version', $version, false);
}

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

Идемпотентная миграция безопасно переносит повторный запуск. Это особенно важно, если процесс был прерван после выполнения части SQL, но до записи новой версии. Повторный запуск не должен повреждать таблицу или дублировать данные.

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

Операции переноса данных также должны быть повторяемыми. Например, обрабатывайте записи, в которых новое поле ещё не заполнено, или используйте стабильный идентификатор в качестве курсора. Если повторный запрос снова встретит уже обработанную запись, он не должен создавать дубликат.

  • Проверяйте существование таблицы перед её созданием.
  • Проверяйте столбец перед ADD COLUMN, если диалект SQL и версия MySQL не гарантируют безопасное использование IF NOT EXISTS для конкретной операции.
  • Для переименования столбцов предусматривайте сценарий частично выполненного шага.
  • Не полагайтесь только на номер версии: фактическое состояние таблицы также нужно проверять.
  • Логически разделяйте изменения DDL, конвертацию данных и создание индексов.
global $wpdb;
$table = $wpdb->prefix . 'my_plugin_items';

$table_exists = $wpdb->get_var(
    $wpdb->prepare('SHOW TABLES LIKE %s', $table)
);

if ($table_exists === $table) {
    $column_exists = $wpdb->get_var(
        $wpdb->prepare('SHOW COLUMNS FROM `' . esc_sql($table) . '` LIKE %s', 'status')
    );

    if (!$column_exists) {
        $wpdb->query('ALTER TABLE `' . esc_sql($table) . '` ADD COLUMN `status` varchar(20) NOT NULL DEFAULT \'new\'');
    }
}

Когда использовать dbDelta(), а когда — отдельные миграции

dbDelta() из пакета WordPress хорошо подходит для базовой синхронизации описания таблицы: создания таблицы или добавления простых изменений в её структуру. Его часто используют при первоначальной установке и для несложных схем.

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

Описание таблицы для dbDelta() должно соответствовать его правилам разбора: каждое поле и индекс лучше указывать в ожидаемом формате, а результат выполнения проверять. Даже если dbDelta() не вернул явную ошибку, после операции стоит проверить фактическую структуру таблицы.

  • Используйте dbDelta() для первоначального или простого синхронизирования таблицы.
  • Для переноса данных пишите отдельную миграцию с пакетной обработкой.
  • Не удаляйте старый столбец в том же релизе, где код ещё может его читать.
  • Сложные индексы и изменения типов сначала проверяйте на копии production-данных.
require_once ABSPATH . 'wp-admin/includes/upgrade.php';

$sql = "CREATE TABLE {$wpdb->prefix}my_plugin_items (
    id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
    status varchar(20) NOT NULL,
    created_at datetime NOT NULL,
    PRIMARY KEY  (id),
    KEY status (status)
) {$wpdb->get_charset_collate()};";

dbDelta($sql);

Обрабатывайте большие объёмы данных пакетами

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

Пакетная миграция выбирает ограниченное количество строк, обрабатывает их и сохраняет прогресс. Для навигации лучше использовать подход keyset: запоминать последний обработанный id и выбирать записи с большим id. На больших таблицах OFFSET может становиться медленнее по мере продвижения.

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

  • Выбирайте записи по стабильному индексированному ключу.
  • Обновляйте только необходимые поля.
  • Не загружайте всю таблицу в память PHP.
  • После каждого пакета проверяйте ошибки и фиксируйте прогресс.
  • Для критически важных таблиц планируйте миграцию на период низкой нагрузки.
$last_id = (int) get_option('my_plugin_migration_3_last_id', 0);
$batch_size = 200;

$rows = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT id, legacy_value FROM {$table}
         WHERE id > %d AND new_value IS NULL
         ORDER BY id ASC LIMIT %d",
        $last_id,
        $batch_size
    )
);

foreach ($rows as $row) {
    $new_value = my_plugin_convert_value($row->legacy_value);
    $wpdb->update($table, ['new_value' => $new_value], ['id' => $row->id]);
    $last_id = (int) $row->id;
}

update_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-события и служебные опции.
if (!get_transient('my_plugin_migration_lock')) {
    set_transient('my_plugin_migration_lock', 1, 5 * MINUTE_IN_SECONDS);

    try {
        my_plugin_process_next_batch();
    } finally {
        delete_transient('my_plugin_migration_lock');
    }
}

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

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

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

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

  • Создайте резервную копию перед DDL-операциями и массовым обновлением.
  • Проверьте миграцию на staging с данными, близкими к production по объёму и структуре.
  • Подготовьте план отката: восстановление backup, отключение нового кода или обратное преобразование данных.
  • Убедитесь, что пользователь базы данных имеет права на необходимые операции.
  • После релиза отслеживайте логи, время выполнения запросов и ошибки плагина.

Типичные ошибки в миграциях WordPress-плагинов

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

Другая проблема — использование одного большого UPDATE для всех данных или выполнение миграции при каждом запросе без проверки. Это создаёт непредсказуемую нагрузку и может ухудшить работу сайта. Также опасно безусловно добавлять столбец: повторный запуск завершится ошибкой «column already exists».

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

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

Частые вопросы

Где лучше всего запускать проверку миграций?

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

Достаточно ли dbDelta() для обновления таблицы?

Для простого создания таблицы или базовой синхронизации структуры — часто да. Но dbDelta() не заменяет перенос данных, сложное переименование, контроль прогресса и сценарии восстановления после частичного выполнения.

Что делать, если миграция завершилась с ошибкой после нескольких пакетов?

Не отмечайте её как завершённую. Сохранённый курсор должен позволить продолжить работу с последнего успешного пакета. Повторный запуск должен проверить уже обработанные записи и не создать дубликаты.

Нужна ли резервная копия перед добавлением одного столбца?

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

Вывод

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

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

← Все материалы WordPress