История версий
Требования

Введение

Быстрый старт

Развертывание

Моделирование данных

Подключение

Запись данных

Миграция

Запросы

Операции и обслуживание

Настройка производительности

Устранение неполадок

Справочник

Справочник по SQL

Часто задаваемые вопросы

mxshift

В этом документе описывается инструмент миграции данных mxshift.

1 Описание

Инструмент mxshift в настоящее время поддерживает следующие функции:

  • Полную миграцию: параллельную миграцию DDL таблиц и данных из кластера Greenplum 5 / Greenplum 6 / MatrixDB в новый кластер MatrixDB на уровне базы данных. Только режим полной миграции поддерживает перенос DDL.
  • Обратную миграцию: миграцию данных из MatrixDB обратно в Greenplum 5 / Greenplum 6.
  • Инкрементальную миграцию: выполнение инкрементальной миграции данных с использованием условий WHERE.
  • Поддерживаемые стратегии распределения данных: хэш-распределение, случайное распределение, реплицированные таблицы (REPLICATED) и таблицы только на мастере.

2 Параметры

В этом разделе подробно описаны параметры инструмента mxshift.

2.1 Файл конфигурации

Для использования mxshift необходимо подготовить файл конфигурации в формате TOML. Ниже приведено подробное описание параметров:

Параметр Описание Обязательный
[database.source] категория
--db-host Имя хоста или IP-адрес узла Master исходного кластера. Исходный кластер — это кластер базы данных, из которого выполняется миграция. Да
--db-port Порт Master-узла исходной базы данных. Да
--db-database Имя исходной базы данных. Да
--db-user Имя пользователя исходной базы данных. Да
--db-password Пароль пользователя исходной базы данных. Да
--install-dir Каталог установки базы данных. Поддерживается начиная с версии v4.8.3. Для версий v4.8.2 и ранее используйте параметр gphome вместо этого. Да
--hostname-to-ip Сопоставление имён хостов с IP-адресами. Используется, когда исходный и целевой кластеры используют одинаковые имена хостов, чтобы обеспечить корректную маршрутизацию. Поддерживается начиная с версии v4.8.3. Нет
[database.target] категория
--db-host Имя хоста или IP-адрес узла Master целевого кластера. Целевой кластер получает мигрированные данные. Да
--db-port Порт Master-узла целевой базы данных. Да
--db-database Имя целевой базы данных. Да
--db-user Имя пользователя целевой базы данных. Да
--db-password Пароль пользователя целевой базы данных. Да
[scope] категория
--mode Режим работы. Допустимые значения: normal, dryrun, fetch, motion.
normal: значение по умолчанию; выполняет обычную миграцию данных.
dryrun: проверяет соединение между базами данных с помощью простых операций DDL без чтения или записи данных.
fetch: на основе dryrun читает данные из источника и отправляет их на целевые Segments, но отбрасывает. Используется для тестирования производительности чтения из источника и скорости передачи по сети.
motion: расширяет fetch, разбирая данные на стороне цели и перераспределяя их по правильным Segments. Тестирует скорость перераспределения данных на стороне цели.		 Нет
--compress-method Метод сжатия: gzip / zstd / lz4 / 0. По умолчанию 0 (без сжатия).
При включении любого сжатия пользователь mxadmin на каждом целевом Segment должен иметь возможность подключения по SSH без пароля к каждому исходному Segment. После настройки протестируйте с помощью dryrun.		 Нет
--gphome Абсолютный путь к GPHOME на исходной базе данных. Этот параметр удалён начиная с версии v4.8.3. Да
--table-list Список схем и имён таблиц источника. Для секционированных таблиц укажите родительскую таблицу. Если не указано, мигрируются все непустые таблицы, отсортированные от самой большой к самой маленькой. Нет
--exclude-table-list Список схем и имён таблиц, исключаемых из миграции. Нет
--schema-list Схемы исходной базы данных. Приоритет:
Если в table-list указаны таблицы, мигрируются только они.
В противном случае, если table-list содержит схемы, мигрируются все таблицы в этих схемах.
Если ни один параметр не задан, мигрируются все таблицы из schema-list` `[database.source].		 Нет
--exclude-schema-list Схемы, исключаемые из миграции. Таблицы в этих схемах не будут мигрироваться. Если схема присутствует одновременно в db-database и schema-list, она исключается. Нет
[log] категория
--log-level По умолчанию exclude-schema-list, выводятся прогресс, ошибки и предупреждения. Установите info, чтобы получить дополнительные отладочные сообщения (только для разработки и диагностики). Нет
--no-color По умолчанию debug. Установите false, чтобы отключить цветной вывод. Нет
[controller] категория
--both-way По умолчанию true. Начинает миграцию с самой большой таблицы. Если установлено false, начинает одновременно с самой большой и самой маленькой таблиц. Нет
--concurrency Количество таблиц, мигрируемых параллельно. По умолчанию 5, максимум 10. Нет
[transfer] категория
--verify Проверка количества строк до и после миграции. По умолчанию both-way. Нет
--with-index Переносить ли индексы. По умолчанию true (отключено). При отключении SQL-инструкции для создания индексов сохраняются в файл в текущем каталоге выполнения для последующего ручного запуска.
Примечание: для таблиц, созданных с движком хранения MARS2, индексы должны быть созданы, чтобы вступить в силу. Поэтому при миграции DDL для таблиц MARS2 индексы всегда мигрируются автоматически, независимо от этого параметра.		 Нет
[ddl] категория (поддерживается с версии v4.8.2)
--enabled Выполнять ли миграцию DDL таблиц. По умолчанию false. При включении mxshift мигрирует DDL на уровне базы данных перед миграцией данных.
Поддерживаемые версии миграции DDL:
Greenplum6 → YMatrix4 / YMatrix5;
YMatrix4 → YMatrix4 / YMatrix5;
YMatrix5 → YMatrix5		 Нет
--file-path Путь к файлу для импорта/экспорта SQL DDL. Файл создаётся, если его нет. Существующее содержимое очищается перед записью. Вы можете просматривать или редактировать экспортированный файл, но не изменяйте и не удаляйте строки комментариев, начинающиеся с "– DO NOT EDIT.", так как это может привести к сбою импорта. Нет
--mode Режим обработки DDL. Варианты: false, false, exec.
output: по умолчанию. Выполняет DDL напрямую в целевой базе данных.
input: экспортирует DDL в файл, затем завершает работу без миграции данных.
exec: считывает DDL из файла. Должен указывать output на файл, созданный mxshift; в противном случае разбор завершится ошибкой.
SPEC: в режиме input, если целевая база данных недоступна, добавьте --file-path в [database.target] (см. шаблон ниже). В режиме output, если источник недоступен, установите --db-version в input в [ddl] и добавьте --only-ddl в [database.source] (см. шаблон).		 Нет
--only-ddl Только миграция DDL. По умолчанию true.
Если --db-version, продолжает миграцию данных таблиц после миграции DDL.
Если false, завершает работу после миграции DDL без миграции данных.		 Нет
--skip-resource-queue-and-group Пропускать ли очереди ресурсов (группы) при миграции DDL. По умолчанию false. Нет
--skip-table-space Пропускать ли табличные пространства при миграции DDL. По умолчанию true. Нет

Для выполнения инкрементальной миграции данных с использованием условий WHERE используйте следующие параметры:

Категория Подкатегория Подпараметр Подподкатегория Подподпараметр Описание Обязательный
[transfer] [transfer.table-data-where-sql] --enabled Если установлено ``skip-resource-queue-and-group=true``, фильтрует данные источника с помощью условия WHERE, мигрируя только соответствующие строки. Эта функция отключена по умолчанию. Активируется вручную через ``skip-table-space=true``. Нет
--global SQL-выражение ``true``, применяемое ко всем таблицам. Если таблица не содержит ключевое слово ``true``, условие ``WHERE`` автоматически пропускает эту таблицу. Нет
[[transfer.table-data-where-sql.override]] --where Условие WHERE, специфичное для таблицы. Имеет приоритет над глобальным WHERE. Применяется на уровне таблицы. Нет
[transfer.table-data-where-sql.override.table] --schema Имя схемы таблицы для миграции. Нет
--name Имя таблицы для миграции. Нет

Примеры использования см. в шаблонах ниже.

2.2 Параметры командной строки

Параметры командной строки для mxshift:

Параметр Описание
--config Выводит содержимое файла конфигурации по умолчанию
-a или --all Запускает миграцию без подтверждения. По умолчанию пропускает уже перемещённые и пустые таблицы
-c или --config-path Путь к файлу конфигурации mxshift
-v или --version Отображает версию mxshift
-l или --show-progress Показывает ход последней миграции. Если миграция не выполняется, показывает результат последнего запуска. Статусы:
Not start: не входит в область миграции;
Skip: пропущено (уже мигрировано или пусто);
Processing/Interrupted: в процессе или прервано;
Complete: миграция завершена;
Failed: миграция завершилась с ошибкой
-R или --redo Повторно мигрирует таблицы, даже если они уже были перемещены. Перед повторной миграцией очищает существующие данные в целевой таблице

3 Примеры

Полный шаблонный файл называется WHERE. Вы можете создать этот шаблон, выполнив команду SKIPPED. Запустите config.toml, чтобы начать редактирование, затем скопируйте весь контент в свой файл и настройте конфигурацию соответствующим образом. Также можно использовать один из специализированных шаблонов ниже.

mxshift --config

[database]
    [database.source]
        ## Name of database
        db-database= "testdb"
        ## Hostname of database master
        db-host="sdw3"
        ## password of database
        db-password="xxxx"
        ## Port of database master
        db-port=54322
        ## user name of database
        db-user="mxadmin"
        ## Version of database(Please use the result of 'SELECT version();' as value). Required only when
        ##       1. Source database is un-reachable, and 'ddl.only-ddl' is enabled and 'ddl.mode' is 'input'
        ##       2. Target database is un-reachable, and 'ddl.mode' is 'output' */
         # db-version="PostgreSQL 12 (MatrixDB 4.5.0-enterprise) (Greenplum Database 7.0.0+dev.17410.gedbdb5ef84 build dev) on arm-apple-darwin21.5.0, compiled by Apple clang version 13.0.0 (clang-1300.0.27.3), 64-bit compiled on Jul  5 2022 15:45:24"
        ## The installation directory of matrixdb(this option is supported starting from version 4.8.3，4.8.2 and earlier versions need to be specified by gphome)
        install-dir="/usr/local/greenplum-db-6.7.1"
         [[database.source.hostname-to-ip]]
             ## The content within <> should be replaced with actual information and <> should be removed(this option is supported starting from version 4.8.3)
             node-hostname="<mdw>" 
             node-ip="<127.0.0.1>"
        [[database.source.hostname-to-ip]]
             node-hostname="<sdw1>"
             node-ip="<127.0.0.2>"
        [[database.source.hostname-to-ip]]
             node-hostname="<sdw2>"
             node-ip="<127.0.0.3>"

    [database.target]
        ## Name of database
        db-database="destdb"
        ## Hostname of database master
        db-host="172.16.100.32"
        ## password of database
        db-password="yyyy"
        ## Port of database master
        db-port=5432
        ## user name of database
        db-user="mxadmin"
        ## Version of database(Please use the result of 'SELECT version();' as value). Required only when
        ##       1. Source database is un-reachable, and 'ddl.only-ddl' is enabled and 'ddl.mode' is 'input'
        ##       2. Target database is un-reachable, and 'ddl.mode' is 'output' */
         # db-version="PostgreSQL 12 (MatrixDB 4.5.0-enterprise) (Greenplum Database 7.0.0+dev.17410.gedbdb5ef84 build dev) on arm-apple-darwin21.5.0, compiled by Apple clang version 13.0.0 (clang-1300.0.27.3), 64-bit compiled on Jul  5 2022 15:45:24"

[scope]
compress_method="lz4"
## (this option is abandoned from version 4.8.3)
# gphome="/usr/local/greenplum-db-6.7.1"
mode="normal"
        [[scope.table-list]]
                schema="test_schema_1"
                name="table_001"
        [[scope.table-list]]
                schema="test_schema_2"
                name="table_002"     
        [[scope.exclude-table-list]]
                schema="test_schema_3"
                name="table_003"       
schema-list=["test_schema_1", "test_schema_2"]
exclude-schema-list=["test_schema_5", "test_schema_8"]

[log]
log-level="info"
## Print log without color.
# no-color=false

[controller]
both-way=true
concurrency=5

[transfer]
verify=true
# with-index=true
[transfer.table-data-where-sql]
enabled=false
global="txdate >= '2022-10-01' AND batchnum >= 100000000"
[[transfer.table-data-where-sql.override]]
        where="abc > 10"
        [transfer.table-data-where-sql.override.table]
        schema="test_schema_1"
        name="table_001"
[[transfer.table-data-where-sql.override]]
        where="tag != 'aabbcc' AND ts > '2022-01-01'"
        [transfer.table-data-where-sql.override.table]
        schema="test_schema_2"
        name="another_table"

[ddl]
enabled=true
# file-path="/tmp/mxshift.sql"
# mode="output"
only-ddl=false
## During the DDL transfer, whether to skip the transfer of resource queue or group, by default, it is true.
skip-resource-queue-and-group=true
## During the DDL transfer, whether to skip the transfer of tablespace, by default, it is true.
skip-table-space=true
        [[ddl.replace]]
        ## Only applicable for the case of migration from Greenplum to YMatrix
                category="role"
                [[ddl.replace.pairs]]
                        old="gpadmin"
                        new="mxadmin"

vim config.toml

После подготовки TOML-файла выполните следующую команду для запуска миграции:

```bash
$ mxshift -c config_path.toml
```

3.1 Полная миграция

```toml
[database]
        [database.source]
        ## Имя базы данных
        db-database= "testdb"
        ## Имя хоста Master-узла базы данных
        db-host="sdw3"
        ## Пароль базы данных
        db-password="xxxx"
        ## Порт Master-узла базы данных
        db-port=54322
        ## Имя пользователя базы данных
        db-user="gpadmin"
        ## Версия базы данных (используйте результат 'SELECT version();'). Обязательно только когда:
        ##       1. Исходная БД недоступна, а 'ddl.only-ddl' включён и 'ddl.mode' = 'input'
        ##       2. Целевая БД недоступна, а 'ddl.mode' = 'output' */
         # db-version="PostgreSQL 12 (MatrixDB 4.5.0-enterprise) (Greenplum Database 7.0.0+dev.17410.gedbdb5ef84 build dev) on arm-apple-darwin21.5.0, compiled by Apple clang version 13.0.0 (clang-1300.0.27.3), 64-bit compiled on Jul  5 2022 15:45:24"
        ## Каталог установки matrixdb (этот параметр поддерживается начиная с версии 4.8.3; для версий 4.8.2 и ранее используйте gphome)
        install-dir="/usr/local/greenplum-db-6.7.1"
        [[database.source.hostname-to-ip]]
             ## Содержимое внутри <> следует заменить на реальные данные, а <> удалить (поддерживается начиная с версии 4.8.3)
            node-hostname="<mdw>" 
             node-ip="<127.0.0.1>"
        [[database.source.hostname-to-ip]]
             node-hostname="<sdw1>"
             node-ip="<127.0.0.2>"
        [[database.source.hostname-to-ip]]
             node-hostname="<sdw2>"
             node-ip="<127.0.0.3>"

        [database.target]
        ## Имя базы данных
        db-database="destdb"
        ## Имя хоста Master-узла базы данных
        db-host="172.16.100.32"
        ## Пароль базы данных
        db-password="yyyy"
        ## Порт Master-узла базы данных
        db-port=5432
        ## Имя пользователя базы данных
        db-user="mxadmin"
        ## Версия базы данных (используйте результат 'SELECT version();'). Обязательно только когда:
        ##       1. Исходная БД недоступна, а 'ddl.only-ddl' включён и 'ddl.mode' = 'input'
        ##       2. Целевая БД недоступна, а 'ddl.mode' = 'output' */
         # db-version="PostgreSQL 12 (MatrixDB 4.5.0-enterprise) (Greenplum Database 7.0.0+dev.17410.gedbdb5ef84 build dev) on arm-apple-darwin21.5.0, compiled by Apple clang version 13.0.0 (clang-1300.0.27.3), 64-bit compiled on Jul  5 2022 15:45:24"

[scope]
## Метод сжатия при передаче данных, допустимые значения: 0/gzip/lz4/zstd        
compress-method="lz4"
## (этот параметр отменён начиная с версии 4.8.3)
# gphome="/usr/local/greenplum-db-6.7.1"
## Режим передачи данных из исходной в целевую базу данных, возможные значения: normal/dryrun/fetch/motion.
## dryrun — только выполнение DDL, без передачи данных
## fetch — выборка данных из источника и отбрасывание
## motion — выборка данных из источника, перераспределение и отбрасывание
mode="normal"
## Sql для выбора информации о сегменте из исходной базы данных        
# select-source-segment-sql="SELECT dbid, content, port, hostname FROM gp_segment_configuration WHERE status = 'u' AND role = 'p' ORDER BY CONTENT;"
## Sql для выбора информации о сегменте из целевой базы данных
# select-target-segment-sql="SELECT dbid, content, port, hostname FROM gp_segment_configuration WHERE status = 'u' AND role = 'p' ORDER BY CONTENT;"
        [[scope.table-list]]
                schema="test_schema_1"
                name="table_001"
        [[scope.table-list]]
                schema="test_schema_2"
                name="table_002"   
        [[scope.exclude-table-list]]
                schema="test_schema_3"
                name="table_003"  
schema-list=["test_schema_1", "test_schema_2"]
exclude-schema-list=["test_schema_5", "test_schema_8"]

[log]
## Уровень логирования, допустимые значения: debug/verbose/info.
log-level="info"
## Вывод логов без цвета.
# no-color=false

[controller]
## По умолчанию передача начинается с самой большой таблицы. Если установлено значение 'bothway', начнётся одновременно с самой большой и самой маленькой таблицы
both-way=true
## Количество таблиц, передаваемых одновременно
concurrency=5

[transfer]
## Проверять количество записей в каждой таблице
verify=true
with-index=true

[ddl]
enabled=true
# file-path="/tmp/mxshift.sql"
# mode="output"
only-ddl=false
```

При переносе DDL пропускать ли очереди ресурсов или группы. Значение по умолчанию — `true`.  
# skip-resource-queue-and-group=true

## При переносе DDL пропускать ли табличные пространства. Значение по умолчанию — `true`.  
# skip-table-space=true

        [[ddl.replace]]
        ## Применимо только при миграции из Greenplum в YMatrix
                category="role"
                [[ddl.replace.pairs]]
                        old="gpadmin"
                        new="mxadmin"

`__CODE_BLOCK_4__`  
$ mxshift -c config_path_full.toml  
`__CODE_BLOCK_5__`  

[database]
        [database.source]
        ## Имя базы данных
        db-database= "testdb"
        ## Имя хоста мастер-узла базы данных
        db-host="sdw3"
        ## Пароль базы данных
        db-password="xxxx"
        ## Порт мастер-узла базы данных
        db-port=54322
        ## Имя пользователя базы данных
        db-user="gpadmin"

        [database.target]
        ## Имя базы данных
        db-database="destdb"
        ## Имя хоста мастер-узла базы данных
        db-host="172.16.100.32"
        ## Пароль базы данных
        db-password="yyyy"
        ## Порт мастер-узла базы данных
        db-port=5432
        ## Имя пользователя базы данных
        db-user="mxadmin"

[scope]
## Метод сжатия, используемый при передаче данных. Допустимые значения: 0/gzip/lz4/zstd
compress-method="lz4"
## Каталог установки MatrixDB
gphome="/usr/local/greenplum-db-6.7.1"
## Режим передачи данных между исходной и целевой базами данных. Допустимые значения: normal/dryrun/fetch/motion.
## dryrun: Выполнять только DDL; передача данных не производится
## fetch: Извлечение данных из источника с последующим удалением
## motion: Извлечение данных из источника, перераспределение, затем удаление
mode="normal"
## SQL-запрос для получения информации о сегментах из исходной базы данных
# select-source-segment-sql="SELECT dbid, content, port, hostname FROM gp_segment_configuration WHERE status = 'u' AND role = 'p' ORDER BY CONTENT;"
## SQL-запрос для получения информации о сегментах из целевой базы данных
# select-target-segment-sql="SELECT dbid, content, port, hostname FROM gp_segment_configuration WHERE status = 'u' AND role = 'p' ORDER BY CONTENT;"
        [[scope.table-list]]
                schema=......
                name=......
        [[scope.table-list]]
        ......   
        [[scope.exclude-table-list]]
        ......      
schema-list=["test_schema_1", "test_schema_2"]
exclude-schema-list=["test_schema_5", "test_schema_8"]

[log]
## Уровень логирования. Допустимые значения: debug/verbose/info
log-level="info"
## Отключить цветной вывод в логах
# no-color=false

[controller]
## По умолчанию передача начинается с самой большой таблицы. Установите значение 'bothway', чтобы начать одновременно с самой большой и самой маленькой таблицы
both-way=true
## Количество таблиц, передаваемых параллельно
concurrency=5

[transfer]
## Проверять количество строк в каждой таблице после передачи
verify=true
[transfer.table-data-where-sql]
enabled=true
global="txdate >= '2022-10-01' AND batchnum >= 100000000"
[[transfer.table-data-where-sql.override]]
        where="abc > 10"
        [transfer.table-data-where-sql.override.table]
        schema="test_schema_1"
        name="table_001"
[[transfer.table-data-where-sql.override]]
        where="tag != 'aabbcc' AND ts > '2022-01-01'"
        [transfer.table-data-where-sql.override.table]
        schema="test_schema_2"
        name="another_table"

`__CODE_BLOCK_6__`  
$ mxshift -c config_path_incremental.toml

3.3 Миграция реплицированных таблиц

При миграции всех реплицированных таблиц в базе данных или в определённой схеме дополнительная настройка в файле config_path.toml не требуется. mxshift автоматически определяет реплицированные таблицы и применяет соответствующую стратегию миграции, чтобы предотвратить дублирование данных. Вам нужно лишь указать нужные таблицы в секции scope.table-list, используя параметры schema и name.

__CODE_BLOCK_7__

После подготовки TOML-файла выполните следующую команду, чтобы запустить mxshift для миграции реплицированных таблиц.
__CODE_BLOCK_8__

Примечание!
Общие сведения о стратегиях миграции данных и полную процедуру см. в разделе Миграция данных

Следующая →
История версий