Как настроить миграции БД в 1С-Битрикс через sprint.migration?

На практике часто так: на локалке вы создали инфоблок «Акции», запушили шаблоны в git — а на тесте каталог пустой, потому что тип инфоблока есть только в вашей базе. Коллеги вручную кликают админку и ломают прод. Это не перенос сайта — это рассинхрон структуры БД между dev, staging и production. Модуль sprint.migration превращает правки в файлы в git. К концу гайда вы установите модуль, создадите миграцию инфоблока и прогоните её на стендах через консоль.

Миграции sprint.migration - это версионирование изменений базы данных CMS: инфоблоки, highload-блоки, пользовательские поля, агенты. Файлы лежат в /local/php_interface/migrations/, накатываются командой up и откатываются через down. Перед production всегда делайте свежий дамп БД и прогоняйте те же миграции на staging. Это другой процесс, чем перенос всего сайта с SEO и 301-редиректами.

Речь про коробочную CMS 1С-Битрикс: Управление сайтом на вашем сервере, не про облачный портал Bitrix24. Если вы только переносите проект с другого хостинга - смотрите гайд по переносу сайта на Битрикс. Здесь - ежедневный dev-workflow: структура БД едет в git вместе с кодом, как composer.lock.

Разберите, когда нужны миграции БД, а когда хватит админки

База данных CMS хранит не только товары и статьи, но и "скелет" сайта: типы инфоблоков, свойства, highload-блоки, почтовые шаблоны, агенты. Код шаблонов лежит в git, а структура БД - нет, пока вы не завели миграции.

Делайте: любое изменение схемы, которое должно повториться на staging и prod, оформляйте миграцией. Не делайте: не путайте sprint.migration с облачной CRM — у неё другой API и нет общего git-workflow.

Установите sprint.migration через Маркетплейс или Composer

Модуль бесплатный (MIT), автор Andrey Ryabin. Официальное имя в админке - "Миграции для разработчиков". Перед установкой создайте каталог /local/php_interface/ - иначе модуль может положить migrations в /bitrix/php_interface/, и путь не совпадет с best practice /local/.

1. Создайте папки /local/php_interface/ и при необходимости /local/modules/ на dev.
2. Установите модуль: Маркетплейс sprint.migration или Composer: composer require andreyryabin/sprint.migration с путем в local/modules/.
3. Проверьте версию: на Packagist актуальна 5.13.0 (июль 2026), в карточке Маркета может быть старее - в команде лучше зафиксировать одну версию в composer.json.
4. Откройте настройки: Настройки - Настройки продукта - Миграции для разработчиков или /bitrix/admin/settings.php?mid=sprint.migration.
5. Убедитесь, что каталог миграций - /local/php_interface/migrations (архив - migrations.archive).
6. Создайте алиас консоли /local/bin/migrate.php, который подключает bitrix/modules/sprint.migration/tools/migrate.php.

На Symfony 3.20+ есть bundle и php bin/console sprint:migration. Без Symfony - migrate.php из tools модуля.

Делайте: один способ установки на всю команду (Composer или Маркет). Не делайте: не смешивайте версии модуля на dev и prod - билдеры ведут себя по-разному.

Создайте первую миграцию через админку и консоль

Миграция — PHP-файл с классом Version: метод up() накатывает изменения, down() откатывает. Состояния: New (файл есть, в БД записи нет), Installed (накатана), Unknown (запись в БД без файла). В реальном проекте Unknown — типичная ошибка после git revert, когда файл удалили, а запись в таблице модуля осталась.

Через админку: Настройки - Миграции для разработчиков - Миграции (cfg) - кнопки "Создать миграцию для инфоблока", HL-блока, UF и др. Файл появится в /local/php_interface/migrations/. Допишите down(), если билдер оставил заглушку.

<?php

namespace Sprint\Migration;

class Version20260720120000 extends Version
{
    protected $description = "Инфоблок Акции";

    public function up()
    {
        $helper = $this->getHelperManager();
        $iblockId = $helper->Iblock()->saveIblock([
            'CODE' => 'promo',
            'NAME' => 'Акции',
            'IBLOCK_TYPE_ID' => 'catalog',
        ]);
        $this->outSuccess('Iblock ID: ' . $iblockId);
    }

    public function down()
    {
        $helper = $this->getHelperManager();
        $helper->Iblock()->deleteIblockIfExists('promo');
    }
}

Консоль (из корня сайта): php local/bin/migrate.php add my_first - пустой шаблон; php local/bin/migrate.php ls --new - список новых; php local/bin/migrate.php up - накатить все новые по порядку от старых к новым. При ошибке одной миграции цепочка останавливается.

Миграция не в списке - проверьте путь cfg, кэш и каталог migrations/. Справочник CLI - commands.txt.

Делайте: коммитьте файл миграции сразу после проверки up на dev. Не делайте: не правьте уже установленную миграцию на проде - создайте новую с исправлением.

Настройте типовые сценарии: инфоблок, HL, UF и агенты

Готовые билдеры в cfg покрывают большую часть рутины. Связка с другими гайдами:

• Инфоблок - после создания инфоблока вручную снимите миграцию билдером, чтобы структура уехала в git.
• Highload-блок - то же для HL-справочников: поля, индексы, права.
• Пользовательские поля (UF) - для сущностей USER, HL, разделов ИБ.
• Агенты и почтовые события - чтобы cron и письма не расходились между стендами.
• Настройки модулей — когда модуль хранит опции в b_option.
• Права доступа — роли и группы, если их настраивали вручную на dev.

Компоненты и шаблоны в git не заменяют миграции: если свой компонент читает инфоблок по CODE, а типа нет на prod - получите пустую выдачу или 404.

Делайте: одна миграция - одна логическая задача (один ИБ или один HL). Не делайте: не смешивайте в одном файле и инфоблок, и тысячи элементов каталога - для данных используйте импорт, для схемы - миграции.

Прогоните чек-лист dev → git → staging → production

Схема релиза:
dev (создали миграцию, up локально) → git commit + push → staging (git pull, бэкап БД, up, smoke-тест) → production (бэкап, up в окно релиза, мониторинг)

1. На dev: создайте миграцию, выполните php local/bin/migrate.php up, убедитесь, что сайт работает.
2. В git: добавьте файлы из /local/php_interface/migrations/, не коммитьте .env и дампы БД.
3. На staging: git pull, php local/bin/migrate.php ls --new, сделайте бэкап базы, затем php local/bin/migrate.php up.
4. Smoke-тест: откройте разделы, затронутые миграцией (каталог, формы, админка).
5. На production: повторите pull, свежий дамп БД, up в согласованное окно; держите план отката down.
6. После релиза: пометьте набор тегом php local/bin/migrate.php up --add-tag=release20260720 для отката группы.

В cfg задайте console_user - под кем CLI выполняет миграции (по умолчанию admin). Тяжелые SQL при обновлении ядра - отдельный продвинутый кейс, не ежедневные миграции структуры.

Нужна помощь с настройкой pipeline на вашем проекте - обсудим задачу. Похожие внедрения - в портфолио.

Делайте: одинаковый порядок миграций на всех стендах. Не делайте: не накатывайте на prod без прогона на staging с копией данных близкой к бою.

Откатите миграцию через down и теги релиза

Откат одной версии: php local/bin/migrate.php down 20260720120000. Повторный накат после правки файла: redo. Удаление файла без down оставит запись Installed - появится Unknown при следующем ls.

Теги группируют миграции релиза: down --tag=release20260720 откатывает все с этим тегом. Для PostgreSQL: поддержка есть с версии модуля 5.0.0 - убедитесь, что проект не на устаревшем форке.

Делайте: пишите осмысленный down() для каждой up(). Не делайте: не удаляйте файлы миграций с прода, пока не согласовали с командой - сломаете историю.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: GitHub sprint.migration, Маркетплейс 1С-Битрикс, блог автора модуля.

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