+7 495 981-01-85 + Стать клиентом
Услуги Кейсы Контент-хаб

Обновление Битрикса через миграции: как не словить инсульт, нажимая «Обновить»

26
#Разработка 19 мая 2026
Данная статья про битрикс, а конкретно про его обновление. Казалось бы, что может быть проще, чем нажать на проде кнопку «Обновить» и дождаться полного обновления системы? Но чем проект больше и старше, тем сильнее хочется прочитать какую-нибудь молитву перед тем как это сделать. Если повезло — выдыхаем и радуемся обновлению. Если всё пошло «как всегда», то распаковываем бэкапы и пробуем снова.
В некоторых случаях такой подход граничит с безумством. В какой-то момент мы устали от ритуалов и сюрпризов при обновление Битрикса на проде и придумали новый способ — обновление через миграции. Ниже я расскажу, как это вообще работает и почему обновляться с кнопки может быть затруднительным.

Из чего состоит обновление Битрикса

Первое и самое очевидное — обновляется код самого ядра. Обновляются модули, компоненты и т. п. Так же, как и в других фрейвормках. И в этом нет большой проблемы, так как ядро можно запушить в репозиторий, подключить как vendor-пакет. В общем, вариантов немало и проблемой это не является.
Второе и самое неприятное — обновление БД. Битрикс в своих обновлениях постоянно затрагивает базу. Обновляет схему данных, добавляет новые таблицы и поля, добавляет индексы и т. п. Вот здесь как раз и кроется проблема.

Почему кнопка — это не всегда хорошая идея

Начнем с того, что обновление чего-либо на проде — это всегда риск. Может возникнуть непредвиденная ошибка БД или сервера, могут перестать быть доступными ресурсы Битрикса (откуда и выкачиваются обновления), коллеги из ИБ могут применить важные политики безопасности, которые могут заафектить обновление.
В итоге либо получаем ошибку сразу (что не так плохо), либо система обновляется частично и процесс обновления прерывается. Повезет, если админка продолжит функционировать и можно будет вручную еще раз запустить обновление и продолжить работы. А вот если админка умирает, то тут уже расчехляем бэкапы БД и файлов. Не очень радужный расклад, не так ли?

Откуда вообще взялись миграции

Идея довольно банальная: не обновляем прод напрямую. Алгоритм действий примерно такой:
  • берем выделенную дев-площадку с отдельной БД;
  • приводим схему БД к состоянию прода (можно взять с прода дамп или просто поднять все имеющиеся миграции);
  • включаем логировать SQL-запросов в настройках Битрикса;
  • запускаем процесс обновления;
  • коммитим правки ядра; создаем миграцию на основе записанных запросов к БД.
По итогу мы не трогаем прод напрямую и не подвергаем его риску. Контролируем процесс обновления. Процесс обновления становится предсказуемым и более спокойным.

Но конечно, не всё так просто

Если кажется, что это серебряная пуля — нет.
Во-первых, это всё надо подготовить. Где-то обновиться, собрать SQL, почистить, оформить миграцию, закоммитить, не забыть ничего по дороге.
Во-вторых, миграции имеют неприятное свойство «протухать». Если ты сделал ее сегодня, а выкатываешь через неделю — будь добр, перепроверь, что она всё еще актуальна.
Поэтому для мелких обновлений этим обычно никто не заморачивается. Нажал кнопку — и поехали. Но когда речь идет о серьезных апдейтах, выбора особо нет.

Когда без миграций лучше даже не начинать

У нас был кейс, где нужно было обновить Битрикс с 17 версии до 23. Шесть мажорных версий. Это не «обновление», это уже почти переезд. Делать такое через кнопку — это буквально сидеть и молиться, чтобы процесс дошел до конца. Потому что, если он падает где-то на середине — всё, привет.
Плюс там еще ИБ могла в любой момент перекрыть доступ к внешним ресурсам. А обновление весит прилично, его надо скачать. В итоге мы пошли через миграции — просто чтобы не играть в русскую рулетку.

Как это выглядит на практике

Сначала поднимаем отдельную площадку с копией базы. Дальше включаем логирование SQL:
                    // /bitrix/php_interface/dbconn.php
$DBDebugToFile = true;
                
После этого идем и жмем ту самую кнопку «Обновить Битрикс». Только уже не страшно — это не прод.
На выходе получаем файл mysql_debug.sql. Обычно он весит как небольшой сериал — мегабайт 50–100. Внутри всё подряд: запросы, тайминги, стектрейсы, лишний мусор. Мы прогоняем его через скрипт, который вычищает всё лишнее и оставляет только SQL. Размер резко худеет до пары сотен килобайт.
Но тут важно не расслабляться: скрипт не самый умный. Иногда в файле остаются вещи вроде отправки почты или других побочных действий. Они нам не нужны, так как могут вызвать нежелательные действия, поэтому глазками пробегаемся и удаляем лишнее.

Логика работы скрипта подготовки файла с запросами

На вход скрипт принимает лог MySQL запросов. Для включения логирования запросов в Битриксе необходимо задать соответствующую настройку в файле dbconn.php: $DBDebugToFile = true;
Результатом работы скрипта будет файл ./result.sql, который можно использовать в качестве потенциальной миграции, чтобы не проводить классическое обновление из административной панели Битрикса в production-окружении.
Логика очистки файла:
  • очистка лога от debug-информации (пустые строки, временные метки, бэктрейс);
  • очистка от дублей строк;
  • удаление запросов SET, SELECT, ANALYZE, SHOW;
  • форматирование строк;
  • фиксация последних запросов к b_option параметрам update_system_update и update_autocheck_result (эти опции постоянно обновляются при обновлении).

Дальше — миграция

Берем получившийся SQL и превращаем его в миграцию. Мы использовали sprint.migration, он для этого подходит. Если запросов много (а их почти всегда много), лучше сразу разбить на чанки. Иначе потом сам себе спасибо не скажешь.
Оборачиваем всё в транзакции, добавляем логирование, обязательно рестартим миграцию после каждого обработанного чанка. Это всё кажется лишним, пока первый раз что-то не падает на середине.
И вот здесь лучше не торопиться. Мы всегда поднимаем чистую базу (до обновления) и прогоняем миграцию на ней. Если всё окей — отлично. Если нет — правим до победного. И только после этого идем дальше.
Пример миграции:
                    namespace SprintMigration;

class Example_BitrixUpdate extends Version
{
    protected $description = 'Накат SQL после обновления Битрикса (по частям)';
    protected $moduleVersion = '4.6.2';

    private function chunksDir(): string
    {
        return __DIR__ . '/' . $this->getClassName() . '_files/chunks';
    }

    /** Один раз: разбить result.sql на небольшие файлы (например по 50 строк). */
    private function ensureChunks(): void
    {
        $dir = $this->chunksDir();
        if (is_dir($dir) && count(glob($dir . '/*.sql')) > 0) {
            return;
        }
        // mkdir, читать result.sql построчно, каждые 50 строк — новый chunk_N.sql
    }

    public function up()
    {
        $this->ensureChunks();

        $files = glob($this->chunksDir() . '/*.sql') ?: [];
        $i = (int)($this->params['next'] ?? 0);

        if ($i >= count($files)) {
            $this->outSuccess('Готово');
            return;
        }

        $connection = BitrixMainApplication::getConnection();
        $connection->startTransaction();
        try {
            $connection->executeSqlBatch(file_get_contents($files[$i]));
            $connection->commitTransaction();
        } catch (Throwable $e) {
            $connection->rollbackTransaction();
            $this->outError($e->getMessage());
            return false;
        }

        $this->params['next'] = $i + 1;
        $this->restart(); // следующий запуск продолжит со следующего чанка
    }

    public function down() {}
}
                
После подготовительных работ мы получаем один большой result.sql. Его нельзя исполнять целиком в одном PHP-запросе из‑за лимита времени/памяти, поэтому SQL режем на чанки и в методе up() за один проход миграции выполняют один чанк, сохраняя индекс в $this->params и вызывая $this->restart(), чтобы следующий запуск скрипта миграций продолжил с того же места. Транзакция обычно на уровень одного чанка — чтобы при ошибке откат был ограничен последней порцией.
  • Если вы ищете сильных разработчиков, чтобы усилить свой проект на PHP, оставляйте заявку — обсудим ваши задачи.

Подготовка к обновлению прода (или как не облажаться)

Если коротко: нужно заранее продумать всё, что может пойти не так. Прямо буквально — сесть и написать план: какие команды, в каком порядке, кто что делает. Очень помогает репетиция на препроде. Заодно понимаешь, сколько это вообще занимает времени. Потому что чем больше версий обновляешь — тем дольше всё это едет.
И обязательно нужен план отката. Не в духе «ну откатим», а конкретный: что делаем, если сайт не поднялся, если данные поехали, если всё вроде прошло, но что-то не так. Если проект под SLA — обычно обновляют ночью, а утром другая команда подхватывает, потому что процесс может затянуться.
И еще маленький, но важный момент. При обновлении Битрикса обновляется папка /bitrix/. Ее нужно закоммитить. Или вынести в сабмодуль. Или завернуть в composer-пакет. Если этого не сделать — можно получить очень странные и неприятные эффекты, когда база уже новая, а код — нет.

Почему так не делают всегда?

Всё просто: потому что это дольше и сложнее.
Нужно больше думать, больше готовить, больше проверять. Плюс миграции нужно поддерживать в актуальном состоянии. Поэтому, если у тебя небольшой проект и простое обновление — скорее всего, никто не будет этим заниматься. Но если проект большой, есть ИБ, SLA и много версий апдейта — кнопка «Обновить» становится слишком рискованной.

Отправьте нам запрос, чтобы
начать общение по вашему
проекту

Контент-хаб

0 / 0