Импорт структуры таблиц и данных из MySQL

Введение

Перенос схемы и данных из MySQL в YDB — в том числе больших таблиц, объём которых превышает доступную оперативную память, — выполняется утилитой mysql2ydb.

Цель утилиты — получить копию исходной базы данных один к одному. Имена таблиц и колонок сохраняются как в MySQL; типы данных сопоставляются с ближайшими эквивалентами YDB (INT → Int32, VARCHAR → Text, AUTO_INCREMENT → BigSerial и т. д.). Поскольку имена переносятся без изменений, они должны быть допустимыми идентификаторами в YDB (символы, длина, зарезервированные слова). В результате должна получиться база YDB, повторяющая исходную структуру и позволяющая выполнять запросы с минимальным «переводом» с MySQL.

Каждый фрагмент данных читается из MySQL одним ограниченным запросом SELECT, записывается в YDB порцией (BulkUpsert или транзакционный UPSERT), после чего освобождается из памяти. Процесс повторяется, пока не будет обработана вся таблица — в памяти одновременно хранится не больше одной порции (при конвейерном чтении — не больше двух).

Импорт выполняется в следующем порядке:

1. Утилита подключается к MySQL и по метаданным information_schema определяет состав таблиц и их структуру.
2. В YDB создаются целевые таблицы с сопоставленными типами данных.
3. Данные переносятся порциями: чтение из MySQL и запись в YDB.
4. После успешной записи каждой порции в служебную таблицу состояния сохраняется позиция курсора — при сбое миграцию можно продолжить с последнего успешного фрагмента.

Соответствие схемы MySQL

При переносе схемы mysql2ydb стремится к структурному соответствию: те же имена таблиц и колонок, индексы там, где YDB их поддерживает, типы, при которых значения сохраняются без потерь (беззнаковые целые остаются беззнаковыми, логические типы — логическими и т. д.).

Утилита читает метаданные MySQL из information_schema и формирует DDL YDB напрямую. Основные сопоставления типов:

Структурные решения

Вторичные индексы

Неуникальные ключи MySQL становятся INDEX … GLOBAL ASYNC, уникальные (кроме первичного) — INDEX … GLOBAL UNIQUE SYNC. Таблицы с синхронными уникальными индексами при загрузке данных автоматически переключаются на транзакционный UPSERT, поскольку BulkUpsert поддерживает только асинхронные индексы.

Примеры

AUTO_INCREMENT — колонка MySQL id BIGINT AUTO_INCREMENT превращается в:

`id` BigSerial NOT NULL,
PRIMARY KEY (`id`)

После CREATE TABLE, если известно значение information_schema.TABLES.AUTO_INCREMENT:

ALTER SEQUENCE `<db>/<table>/_serial_column_id` START WITH <next_value> RESTART

Таблицы без первичного ключа

В YDB у каждой таблицы должен быть PRIMARY KEY. mysql2ydb берёт ключ только из колонок MySQL с COLUMN_KEY = 'PRI'; индексы UNIQUE KEY становятся вторичными GLOBAL UNIQUE SYNC, но не подставляются вместо первичного ключа. Если у таблицы нет PRIMARY KEY, создание схемы завершается ошибкой (PRIMARY KEY () — недопустимый DDL), и перенос данных не начинается.

Перед миграцией для таких таблиц нужно задать ключ в MySQL, например:

ALTER TABLE my_table ADD COLUMN id BIGINT AUTO_INCREMENT PRIMARY KEY FIRST;

или назначить PRIMARY KEY на существующую колонку (или набор колонок), если он действительно уникален.

Если добавить PRIMARY KEY в MySQL нельзя, но схему в YDB можно подготовить вручную, создайте таблицу с нужным ключом сами и запустите утилиту с флагом -data-only. Чтение из MySQL при отсутствии PRIMARY KEY в метаданных пойдёт через LIMIT/OFFSET: на каждой странице MySQL заново сканирует все предыдущие строки, поэтому время миграции растёт квадратично от размера таблицы — для больших таблиц лучше предварительно добавить ключ в MySQL. Ключевые колонки в YDB должны присутствовать среди колонок MySQL.

Если нужен автоматический импорт без ключа в MySQL, рассмотрите YDB Importer — он добавляет синтетическую колонку ydb_synth_key (SHA-256 по строке). mysql2ydb синтетические ключи не создаёт.

Эффективный доступ к MySQL

Утилита минимизирует обращения к MySQL и ограничивает объём каждого запроса:

1. Постраничное чтение по первичному ключу — WHERE (pk…) > (?) ORDER BY pk LIMIT n. Без полного сканирования таблицы в память.
2. Конвейер чтение → запись — одна горутина читает следующую порцию из MySQL, пока другая записывает предыдущую в YDB. На таблицу одновременно в полёте не более двух порций.
3. Адаптивный размер порции — число строк ограничивается доступной RAM и средним размером строки из information_schema.
4. Контрольная точка прогресса — после каждой успешно записанной порции позиция курсора и счётчик строк сохраняются в служебной таблице YDB; перезапуск продолжает с последней порции.

MySQL: SELECT порция N   →  BulkUpsert(порция N)   →  YDB
MySQL: SELECT порция N+1 →  BulkUpsert(порция N+1) →  YDB
...

Возможности

• Копия схемы один к одному — исходные имена таблиц и колонок; сопоставление типов MySQL с ближайшими типами YDB (AUTO_INCREMENT → BigSerial, UNSIGNED → Uint32/Uint64, вторичные индексы, TINYINT(1) → Bool; см. раздел Соответствие схемы MySQL).
• Создание схемы — таблицы в YDB создаются по метаданным MySQL (information_schema).
• Пофрагментная миграция данных — таблица обрабатывается порциями фиксированного размера; объём данных может превышать доступную RAM.
• Перезапись по ключу — данные записываются через BulkUpsert или транзакционный UPSERT; повторный запуск не создаёт дубликаты строк.
• Возобновление — прогресс по каждой таблице хранится в YDB; прерванную миграцию можно продолжить с последней порции.

Установка

Исходный код и инструкции по сборке — в репозитории mysql-ydb-importer на GitHub.

Для сборки требуется Go версии не ниже указанной в go.mod репозитория:

git clone https://github.com/ydb-platform/mysql-ydb-importer.git
cd mysql-ydb-importer
go build -o mysql2ydb ./cmd/mysql2ydb

Порядок использования

Параметры подключения к MySQL по умолчанию читаются из файла ~/.my.cnf (как у клиента mysql), секция [client]. Флаг -mysql переопределяет конфигурационный файл.

Пример ~/.my.cnf:

[client]
user = myuser
password = mypass
host = localhost
port = 3306
database = mydb

Если сервер требует защищённое соединение (require_secure_transport=ON), добавьте в [client]:

ssl-mode = REQUIRED

Для самоподписанного сертификата (без проверки):

ssl-mode = REQUIRED
ssl-verify = 0

Альтернативный вариант — ssl=1 и ssl-verify=0.

Минимальный запуск при наличии ~/.my.cnf (обязателен только -ydb):

./mysql2ydb -ydb "grpc://localhost:2136"

С явным DSN MySQL (игнорирует ~/.my.cnf):

./mysql2ydb -mysql "user:$MYSQL_PASSWORD@tcp(localhost:3306)/mydb" -ydb "grpc://localhost:2136" -batch-size 10000

Флаги командной строки

Примеры

Только схема:

./mysql2ydb -mysql "..." -ydb "grpc://localhost:2136" -schema-only

Только данные (после создания схемы):

./mysql2ydb -mysql "..." -ydb "grpc://localhost:2136" -data-only -batch-size 5000

Выбранные таблицы:

./mysql2ydb -mysql "..." -ydb "grpc://localhost:2136" -tables "users,orders"

Пофрагментное чтение

• Для таблиц с первичным ключом в MySQL используется постраничное чтение по курсору: WHERE (pk > ?) ORDER BY pk LIMIT batch_size. В памяти одновременно находится не больше одной порции.
• Если в MySQL нет PRIMARY KEY, но схема в YDB уже создана вручную (режим -data-only), применяется LIMIT batch_size OFFSET offset — см. раздел Таблицы без первичного ключа.

Запись в YDB

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

Запросы к YDB помечены как идемпотентные, поэтому SDK автоматически повторяет их при сетевых сбоях. Отсутствие дубликатов при перезапуске миграции обеспечивается перезаписью строк по ключу и сохранением прогресса в служебной таблице (см. раздел Возможности, пункт «Возобновление»).

Сравнение с YDB Importer

Для загрузки данных в YDB есть и другие инструменты. YDB Importer — универсальный JDBC-импортёр для PostgreSQL, Oracle, SQL Server и других источников: XML-конфигурация, параллельный импорт, настройка партиционирования.

mysql2ydb решает более узкую задачу — перенос базы MySQL «один к одному» одним бинарным файлом, без JVM. Для миграции только из MySQL с большими таблицами достаточно ~/.my.cnf и флага -ydb; прогресс сохраняется в служебной таблице YDB.

YDB Importer рассчитан на импорт из многих JDBC-источников в настраиваемую структуру YDB (table-name-format, blob-name-format, режимы преобразования дат, опциональные синтетические ключи). Ниже — практические отличия при импорте одной и той же базы MySQL двумя инструментами:

Работа с BLOB

Таблица MySQL attachments (id INT, data MEDIUMBLOB):

С mysql2ydb можно выполнить SELECT data FROM attachments WHERE id = 1 так же, как в MySQL. С ydb-importer потребуется соединение основной таблицы с дополнительной blob-таблицей.