Розробка модуля міграцій бази даних для 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 місяців — виправлення помилок і оновлення під нові версії Бітрікс.

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

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

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

Міграція сайтів на 1С-Бітрікс

Переїзд на нову CMS — завжди стрес для сайту. Якщо проігнорувати URL-структуру, через два тижні трафік падає на 50–80 %. WordPress генерує /product/item-name/, OpenCart — /index.php?route=product/product&product_id=123, а Бітрікс за замовчуванням хоче /catalog/section/element/. Без карти 301-редиректів пошуковики фіксують масові 404. Ми починаємо будь-яку міграцію зі сканування старого сайту через Screaming Frog і складаємо повну карту редиректів ще до першого рядка коду. Як сказано в документації 1С-Бітрікс: коректна міграція вимагає повного маппінгу URL.

За 7 років ми перенесли понад 50 проєктів — від лендінгів до каталогів на 300 000 товарів. Середній термін — 2–8 тижнів. Оцінку проєкту робимо безкоштовно за 1 день — зв'яжіться для попереднього розрахунку.

Які CMS ми переносимо на Бітрікс?

За роки роботи дані мігрували з десятків систем.

Блоги та корпоративні сайти: WordPress / WooCommerce → 1С-Бітрікс. Таблиці wp_posts, wp_postmeta, wp_wc_product_meta_lookup маппяться в інфоблоки та highload-блоки. Варіації товарів (WooCommerce Variable Product) стають торговими пропозиціями (b_catalog_product).

Інтернет-магазини: OpenCart / ocStore → 1С-Бітрікс. Структура oc_product, oc_product_description, oc_product_to_category переїжджає в ієрархію інфоблоків. Мультимовність OpenCart перетворюється на мовні версії властивостей. Joomla / VirtueMart, MODX Revolution (TV-змінні → властивості інфоблоків), Drupal, PrestaShop — аналогічно.

SaaS-платформи: Tilda, InSales, Shopify, Wix, Squarespace. Бізнес переріс конструктор — потрібні 1С-інтеграції та управління залишками.

Самописні двигуни: реверсимо БД і відновлюємо бізнес-логіку за вихідним кодом.

Що переноситься?

Контент: сторінки, статті, новини → інформаційні інфоблоки. Каталог: категорії → розділи, товари → елементи з прив'язкою до b_catalog_product, властивості → властивості інфоблоку або highload-довідники. Зображення, відгуки, FAQ.

E-commerce: товари з варіаціями (торгові пропозиції), ціни в b_catalog_price (мультивалютні через b_catalog_currency), залишки по складах b_catalog_store_product, знижки (b_sale_discount), історія замовлень (b_sale_order + b_sale_basket).

Користувачі: клієнтська база — b_user + UF-поля. Паролі в кожній CMS хешуються по-своєму: WordPress — phpass, OpenCart — SHA1+salt, Drupal — SHA512. Ми пишемо кастомний CUser::LoginByHash з fallback на старий алгоритм — клієнт вводить пароль один раз, система перехешує в bcrypt Бітрікса.

SEO-дані: мета-теги, alt-теги, URL-структура. Головне завдання — зберегти всі URL або проставити 301-редиректи.

Медіа: зображення, документи, відео — зі збереженням шляхів та оптимізацією через CFile::MakeFileArray().

Як відбувається міграція?

Як зберегти SEO-позиції?

Втрата органічного трафіку — головний страх, і він обґрунтований. Ось як ми його уникаємо.

Маппінг URL 1:1 — де можливо, через CUrlRewriter та ЧПУ-налаштування інфоблоку зберігаємо точну структуру. Де не можна — 301. Автогенерація карти редиректів: парсимо експорт Screaming Frog, зіставляємо з slugs нових елементів, генеруємо конфіг nginx. Кожен редирект перевіряється curl -I після перемикання.

Перенесення мета-тегів: title, description, h1 переносяться як є у властивості ELEMENT_META_TITLE, ELEMENT_META_DESCRIPTION. Canonical: rel="canonical" через SEO-компонент Бітрікс. Дуби відсікаємо: www/без www, http/https, параметри сортування. Sitemap: нова sitemap.xml через модуль seo Бітрікса, подача в Search Console та Вебмастер одразу після перемикання.

Порівняння швидкості: Бітрікс у 3 рази швидше обробляє каталог із 100 000 товарів, ніж OpenCart, завдяки тегованому кешуванню та оптимізації запитів до b_catalog_product.

Що входить у роботу (deliverables)

Міграція інтеграцій

Зовнішні інтеграції — окремий пласт. Ми перепідключаємо:

• Платіжні системи — sale.paysystem зі збереженням історії транзакцій.
• Доставка — налаштування sale.delivery.handler (СДЕК, Укрпошта).
• CRM — прив'язка до Бітрікс24 або збереження поточної через REST API.
• 1С — налаштування обміну через CommerceML. Часто це головна причина міграції на Бітрікс.
• Email-маркетинг — перенесення підписників, шаблонів, вебхуків.
• Аналітика — e-commerce tracking під нову структуру dataLayer.

Типові помилки при міграції

Кожна з цих помилок призводила до втрати позицій і клієнтів.

Втрата URL без редиректів — найруйнівніший промах. /product/123 замість /catalog/item-name.html — без 301 це масові 404 та обвал трафіку. Ми генеруємо карту автоматично і перевіряємо кожен редирект після перемикання.

Дублювання контенту: один товар доступний з www і без, по HTTP і HTTPS, з GET-параметрами фільтрації — п'ять URL замість одного. SEO-вага розмивається. Налаштовуємо canonical, 301 для варіацій, robots.txt з Disallow для параметрів.

Биті зображення: абсолютні URL в контенті (src="https://old-site.ru/img/photo.jpg"), втрата якості при перетисканні. Замінюємо на відносні шляхи, переносимо зі збереженням структури, перевіряємо HTTP 200 для кожного файлу.

Втрата мета-тегів і мікророзмітки: title, description, Schema.org можуть не перенестися або перенестися криво. Робимо повний маппінг і перевірку на staging.

Відвалені форми та інтеграції: змінилися ID, API-ключі, вебхуки. Складаємо реєстр усіх інтеграцій до початку і перевіряємо кожну після.

Мобільна версія: старий m.site.ru → адаптивний Бітрікс. Без редиректу мобільних URL — 404 для мобільних користувачів. Враховуємо в карті редиректів.

Перед міграцією обов'язково: 1) повне сканування Screaming Frog / Sitebulb; 2) експорт SEO (title, description, h1, canonical, hreflang); 3) фіксація позицій за ключовими запитами; 4) бекап файлів і БД з перевіркою відновлення; 5) реєстр усіх інтеграцій; 6) карта редиректів для кожної проіндексованої сторінки; 7) тестова міграція на staging з повною перевіркою; 8) коректна мобільна версія та редиректи з m.site.ru; 9) нова sitemap.xml готова до подачі; 10) план відкату: DNS збережені, конфіг задокументовано, доступ до старого хостингу є.

Терміни та економія

Економія: після міграції ви перестаєте платити за ліцензію старої CMS та підтримку застарілого коду. Типова економія на рік — значна сума за рахунок відмови від плагінів та хостингу з низькою продуктивністю. Додайте сюди вартість ліцензії 1С-Бітрікс (редакція «Бізнес») — вона повністю окупається в перший місяць.

Отримайте консультацію з міграції: заповніть форму на сайті, і ми підготуємо пропозицію за 1 день. Оцінимо ваш проєкт безкоштовно — напишіть нам для розрахунку.