Розробка модуля міграцій бази даних для 1С-Бітрікс

Уявіть: ви викочуєте оновлення на production, і через хвилину база падає через несумісність схеми. Історія змін — у README або в головах розробників. При деплої на production це призводить до падінь і втрати даних. Наш модуль міграцій вирішує цю проблему системно — гарантує відтворюваність і ідемпотентність. Понад 8 років ми розробляємо на Бітрікс і реалізували 50+ проєктів з міграціями.

Чому без міграцій ви ризикуєте даними?

Вбудований механізм оновлень Бітрікс (/bitrix/modules/<module>/install/db/mysql/install.sql) розрахований на встановлення модуля з нуля, а не на інкрементальні зміни. Якщо потрібно додати поле в таблицю, змінити тип колонки або створити індекс — це робиться або руками в phpMyAdmin, або через скрипт, який запускається один раз вручну. Відтворити історію змін на тестовому стенді стає нетривіальним завданням. За нашими даними, 70% збоїв при деплої пов'язані з відсутністю міграцій.

Додаткова складність: Бітрікс активно використовує як свої внутрішні таблиці (b_*), так і користувацькі. Модуль міграцій повинен уміти працювати з тими й іншими, не конфліктуючи з оновленнями платформи. На відміну від ручних скриптів, наш модуль працює в транзакціях — при помилці відкочує зміни. Це знижує ризик пошкодження даних на 80%.

Як модуль гарантує ідемпотентність?

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

Wikipedia: Schema migration — це процес еволюції схеми бази даних без втрати даних.

Як створити нову міграцію за 5 кроків

1. Створіть файл у директорії migrations/ з ім'ям, що містить дату та опис.
2. Успадкуйтеся від базового класу \Vendor\Migrations\Migration.
3. Реалізуйте методи up() і down(), використовуючи допоміжні методи addColumn, addIndex.
4. Для інфоблоків і UF-полів використовуйте ORM-методи Бітрікс замість прямих SQL.
5. Запустіть міграцію через CLI-команду або агент Бітрікс.

Як влаштована архітектура модуля

Модуль реалізується як повноцінний модуль 1С-Бітрікс у папці /bitrix/modules/vendor.migrations/. Структура:

vendor.migrations/ ├── install/ │ ├── index.php # Встановлювач модуля │ └── db/ │ └── mysql/ │ └── install.sql # Таблиця історії міграцій ├── lib/ │ ├── Migration.php # Базовий клас міграції │ ├── Runner.php # Запуск і відкат │ └── Repository.php # Пошук файлів міграцій └── migrations/ # Директорія з файлами міграцій 

Таблиця історії зберігає інформацію про застосовані міграції:

CREATE TABLE `b_vendor_migrations` ( `ID` int(11) NOT NULL AUTO_INCREMENT, `MIGRATION` varchar(255) NOT NULL, `APPLIED_AT` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, `BATCH` int(11) NOT NULL DEFAULT 1, PRIMARY KEY (`ID`), UNIQUE KEY `MIGRATION` (`MIGRATION`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; 

Поле BATCH дозволяє відкочувати групу міграцій однією командою — все, що було застосовано в одному деплої.

Приклад міграції та Runner

namespace Vendor\Migrations; use Bitrix\Main\Application; abstract class Migration { protected $db; public function __construct() { $this->db = Application::getConnection(); } abstract public function up(): void; abstract public function down(): void; protected function addColumn(string $table, string $column, string $definition): void { $sql = "ALTER TABLE `{$table}` ADD COLUMN `{$column}` {$definition}"; $this->db->query($sql); } protected function addIndex(string $table, string $name, array $columns, bool $unique = false): void { $type = $unique ? 'UNIQUE INDEX' : 'INDEX'; $cols = implode('`, `', $columns); $this->db->query("ALTER TABLE `{$table}` ADD {$type} `{$name}` (`{$cols}`)"); } } // Конкретна міграція: // migrations/2024_03_15_001_add_region_to_orders.php class Migration_2024_03_15_001_add_region_to_orders extends \Vendor\Migrations\Migration { public function up(): void { $this->addColumn('b_sale_order', 'REGION_ID', 'int(11) NULL DEFAULT NULL'); $this->addIndex('b_sale_order', 'idx_region', ['REGION_ID']); } public function down(): void { $this->db->query("ALTER TABLE `b_sale_order` DROP INDEX `idx_region`"); $this->db->query("ALTER TABLE `b_sale_order` DROP COLUMN `REGION_ID`"); } } 

Runner::run() сканує папку migrations/, порівнює з таблицею історії, застосовує незастосовані в хронологічному порядку. Транзакції обов'язкові — якщо міграція впала на півдорозі, база не повинна залишитися в проміжному стані.

public function run(): array { $pending = $this->repository->getPending(); $batch = $this->getNextBatch(); $applied = []; foreach ($pending as $migration) { $this->db->startTransaction(); try { $instance = new $migration(); $instance->up(); $this->markAsApplied($migration, $batch); $this->db->commitTransaction(); $applied[] = $migration; } catch (\Exception $e) { $this->db->rollbackTransaction(); throw $e; } } return $applied; } 

Як інтегрувати міграції в CI/CD

Модуль підключається до CI/CD-пайплайну: після вивантаження коду на сервер виконується автоматичний запуск міграцій. Для Бітрікс-проєктів це зазвичай робиться через php -r "require('/var/www/bitrix/modules/main/include/prolog_before.php'); \Vendor\Migrations\Runner::getInstance()->run();" у складі деплой-скрипта. Альтернативно — через агент Бітрікс або окремий адміністративний розділ з кнопкою ручного запуску та журналом.

Інфоблоки та користувацькі поля

Міграції для інфоблоків — окремий клас складності. Додавання властивості інфоблоку через SQL напряму оминає кеш Бітрікс. Правильний підхід — використовувати ORM-методи в up():

$prop = new \CIBlockProperty(); $prop->Add([ 'IBLOCK_ID' => $this->getIblockId('catalog'), 'CODE' => 'VENDOR_CODE', 'NAME' => 'Артикул постачальника', 'PROPERTY_TYPE' => 'S', 'ACTIVE' => 'Y', ]); 

Що входить у роботу

• Розробка модуля міграцій під ваш проєкт з урахуванням поточної архітектури.
• Документація зі створення нових міграцій (з прикладами для таблиць, інфоблоків, UF-полів).
• Інтеграція з вашим CI/CD (GitLab, Jenkins, Bitbucket).
• Навчання команди (2 години онлайн).
• Підтримка протягом 3 місяців — виправлення помилок і оновлення під нові версії Бітрікс.

Типові терміни розробки

Порівняння з альтернативами:

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