Рекомендуемые драйверы #

Рекомендуется использовать драйверы, реализованные на языке Pure Go, чтобы избежать проблем с кроссплатформенной совместимостью утилиты. В частности, рекомендуется использовать следующие драйверы:

Важные замечания #

Ограничения #

Типы задач #

Создание начального файла конфигурации #

Чтобы создать файл конфигурации, выполните команду config-generate. Позже вы сможете изменить параметры конфигурации вручную. Структура файла конфигурации описана в Разделе 5.2.

Запуск загрузки данных из базы данных-источника в базу данных-приёмник #

Чтобы запустить загрузку данных из источника в приёмник, выполните команду load, указав файл конфигурации.

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

Остановка procopy #

procopy завершает работу автоматически после выполнения всех задач. Задача считается выполненной, если утилита procopy достигла конца таблицы.

Чтобы остановить работающую procopy, нажмите Ctrl+C. Однократное нажатие Ctrl+C запускает корректное завершение работы: утилита завершает выполнение и сохраняет всю информацию, необходимую для последующего возобновления. Этот процесс может занять несколько минут. Повторное нажатие Ctrl+C приводит к принудительной остановке. При следующем запуске в этом случае возможны многочисленные ошибки «unique constraint violation» (нарушение ограничения уникальности). Несмотря на это, procopy продолжит выполнение, однако восстановление может занять значительное время.

Обработка ошибок #

Если по какой-либо причине procopy не может применить строку, она сохраняет её ключ и сообщение об ошибке в CSV-файл <task_id>_index.csv в каталоге problem_rows.local.save_dir/<timestamp>. Если параметр problem_rows.local.save_dir не задан, используется каталог /tmp/<timestamp>/*.csv.

По умолчанию проблемные строки пропускаются, однако на практике такой подход чаще всего оказывается неприемлемым. В подобных случаях можно настроить параметр procopy_options, указав, где сохранять пакеты с проблемными строками, с помощью следующей настройки:

{
  "version": 1,
  "procopy_options": {
    "problem_rows": {
      "local": {
        "save_dir": "path_to_save_dir"
      }
    }
  }
}

При возникновении ошибки, которая приводит к сбою в работе procopy, диагностическая информация сохраняется в файл Procopy_panic_data_<текущее_время>.tar.gz.

Повторная загрузка проблемных строк #

Если при предыдущей загрузке возникли ошибки и вы их устранили, можно повторно загрузить проблемные строки без полной перезагрузки данных. Для этого выполните команду:

procopy load --file filename --reload-from TIMESTAMP

Здесь TIMESTAMP — имя каталога, в котором хранятся файлы-индексы для проблемных строк.

Если опять возникают ошибки, будут созданы новые файлы *_index.csv в каталоге с новой меткой времени TIMESTAMP.

Возобновление загрузки #

Утилита procopy поддерживает возобновление загрузки данных с точки последней остановки для задач типа Schema (схема), а также для задач типа Table (таблица), если соответствующие таблицы имеют ключи.

Если задача типа Query (запрос) не была завершена, её выполнение нельзя возобновить. Перед повторной загрузкой необходимо выполнить команду TRUNCATE.

В случае незавершённой задачи типа Table для таблицы без ключей (кучи) перед повторной загрузкой следует выполнить команду TRUNCATE, чтобы избежать дублирования строк.

Если параметр procopy_options.truncate имеет значение true или для конкретной задачи truncate установлен в true, соответствующая таблица будет очищена и загрузка данных начнётся с нуля.

Настройка параллелизма загрузки #

Распараллеливание процесса загрузки достигается за счёт:

Установите глобальные ограничения на количество потоков для чтения данных из источника и их загрузки в приёмник в параметрах конфигурации procopy_options.readers и procopy_options.loaders соответственно. По умолчанию оба параметра равны NumCPU/2.

Большие таблицы можно разделить на несколько частей по диапазонам уникальных ключей, чтобы каждая часть обрабатывалась отдельной задачей. Для этого необходимо задать глобальный параметр procopy_options.sub_task_rows или параметр task.sub_task_rows на уровне задачи.

Для каждой секции секционированной таблицы создаётся отдельная задача.

Настройка задач типа Table #

Параметры, относящиеся к задачам этого типа, задаются в разделе tasks.table файла конфигурации. Например:

tasks:
    - id: tab1
      table:
        source_table: source_table
        destination_table: destination_table
        exclude_columns:
            - field4
        include_columns:
            - field1
            - field2
            - field3
            - field4
        column_mapping:
            field1: field2
            field2: field1
        where: (COL1 IS NULL OR COL1 > 10) AND COL2 <> 'value'
      batch_bytes: 976.6KiB
      truncate: false
      transform:
        field1:
            null_to_value: ""
        field2:
            values_to_null:
                - "NULL"
                - NULL_VAL
                - INVALID
        field3:
            null_char_replace: "\n"
      snapshot_id: null

Чтобы настроить задачи типа Table (таблица), определите столбцы, которые в итоге будут загружены в таблицу в приёмнике:

Используйте параметр transform, чтобы задать правила преобразования значений NULL в указанных столбцах.

Используйте параметр where, чтобы ограничить количество загружаемых строк.

Настройка задач типа Schema #

Параметры, относящиеся к задачам этого типа, задаются в разделе tasks.schema файла конфигурации. Например:

tasks:
    - id: schema_task
      schema:
        source_schema: schema1
        destination_schema: schema2
        exclude_tables:
            - TABLE1
        include_tables:
            - TABLE1
            - TABLE2
            - TABLE2
        table_mapping:
            TABLE2: main_table
      batch_bytes: 976.6KiB
      truncate: false
      snapshot_id: null

Чтобы настроить задачи типа Schema (схема), определите, какие таблицы в итоге будут загружены:

Настройка задач типа Query #

Задачи типа Query (запрос) загружают в приёмник данные, полученные в результате выполнения запроса в источнике. Параметры, относящиеся к задачам этого типа, задаются в разделе tasks.query файла конфигурации. Например:

tasks:
    - id: tab2
      query:
        sql: SELECT id, name FROM users ORDER BY id
        destination_table: users_table
        destination_columns:
            - id
            - login
      batch_bytes: 976.6KiB
      truncate: false
      snapshot_id: null

При настройке задач типа Query в параметре tasks.query.destination_columns перечислите столбцы в том же порядке, в котором они указаны в запросе.

Настройка задач с указанием снимка #

В задачах, загружающих данные из PostgreSQL/Postgres Pro, можно указать снимок, для которого будет выполняться загрузка данных. Для этого выполните следующие шаги:

Пример фрагмента файла конфигурации для данной задачи может выглядеть следующим образом:

tasks:
- id: query_task
  query:
    sql: SELECT id, name FROM users ORDER BY id
    destination_table: users_table
    destination_columns:
        - id
        - login
  batch_bytes: 1000000
  truncate: false
  snapshot_id: 00000006-0000000000002007-1

В результате выполнения этой задачи строки данных будут загружены в том состоянии, в котором они находились на момент начала транзакции, даже если параллельные транзакции изменяли эти строки.

Для автоматического создания снимка при запуске загрузки данных задайте для параметра конфигурации procopy_options.enable_auto_snapshot значение true.

Перенос объектов типа BFILE #

При переносе объектов типа BFILE передаются только псевдонимы. Сами данные должны быть доступны в источнике или перенесены пользователем вручную.

config generate #

procopy config generate [-f|--format json|yaml] [-o|--output имя_файла]

Генерирует файл конфигурации для procopy.

load #

load -f|--file имя_файла [--log-level error|warn|info|debug]
[-s|--queue-size число_пакетов] [-q|--quiet]
[-r|--reload-from метка_времени] [--dry-run|--read-only]

Запускает загрузку данных между базами данных.