Catchup: синхронизация реплики с основным узлом

Предусловия

1. Утилита copywala установлена на всех узлах кластера (установка на узлах-репликах необходима для возможности работы catchup при смене ролей между узлами).
2. На репликах должна существовать или быть создана целевая директория для данных (PGDATA). Путь к этой директории используется в обязательном флаге --datadir при вызове команды copywala catchup send.
3. В конфигурационном файле copywala.yaml основного узла и узлов-реплик заданы значения для параметров в секции catchup_policy.

Шаги сценария

1. Пользователь устанавливает на всех узлах кластера:

   • Pangolin Manager;
   • утилиту copywala.

2. Пользователь на всех узлах кластера устанавливает расширение pgcopywala (позволяет выполнять команды copywala через протокол PostgreSQL).

3. Пользователь заполняет конфигурационный файл Pangolin Manager (по умолчанию /etc/pangolin-manager/postgres.yml) следующим образом:

   postgresql: # корневая секция postgres
       create_replica_methods:
           - copywala
       copywala:
           command: copywala catchup receive --start_master_runner
           no_params: false

4. Пользователь запускает кластер и убеждается, что все узлы находятся в рабочем состоянии.

5. Пользователь на реплике выполняет команду запуска синхронизации.

6. Пользователь дожидается завершения синхронизации.

Альтернативный сценарий. Выполнение catchup в «ручном режиме» (без использования Pangolin Manager)

1. Пользователь останавливает узел-реплику (реплики).

2. Пользователь запускает процесс получения данных с основного узла. Для этого на узле-реплике выполняет команду copywala catchup receive.

   Справка по команде copywala catchup receive

   Описание:

   Запускает процесс получения и синхронизации данных с основного (primary) узла на узле-реплике. Команда выполняется на хосте реплики.

   Синтаксис:

       
   copywala catchup receive [flags]

   Обязательные параметры:

   Флаг	Описание
   --datadir <path_to_pgdata>	Путь к директории данных (PGDATA) на узле-реплике
   --connstring <string>	Строка подключения к основному серверу БД. Пример: host=master-host port=5432 user=postgres dbname=postgres
   --role <role>	Роль текущего сервера. Укажите значение replica

   Опциональные параметры:

   [flags] – доступны следующие флаги:

   Флаг	Описание
   -h|--help	Показать справку по команде
   -c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
   --scope	Имя кластера на котором будет запускаться команда
   -s|--start_master_runner	Автоматически запускать отправку данных с основного узла с помощью расширения pgcopywala (вызов copywala catchup send в таком случае происходит автоматически, а не в ручную). При использовании данного флага убедитесь, что на primary-узле установлено расширение pgcopywala

   Важно

   Если команда copywala catchup receive вызывается с флагом -s|--start_master_runner, шаг 3 выполнять не требуется, так как он будет выполнен автоматически.

   Перед использованием флага -s|--start_master_runner убедитесь, что на primary-узле установлено расширение pgcopywala, которое позволяет автоматически выполнять команду copywala catchup send через протокол PostgreSQL.

   В результате вызова copywala catchup receive с флагом -s|--start_master_runner будут выведены сообщения (пример вывода):

   2026-05-20 13:35:17.962 [114] INF start catchup for pgdata path: /pgdata/data/
   2026-05-20 13:46:45.758 [112] INF run catchup on master
   2026-05-20 13:46:45.758 [112] INF start sync files via pgcopywala extension
   ...

3. Пользователь запускает передачу данных на реплику (реплики) командой copywala catchup send <replica_addresses>.

   Справка по команде copywala catchup send

   Описание:

   Команда используется для передачи данных с основного сервера (primary) на реплику. Она применяется при создании новых реплик, а также при восстановлении существующих, если данные на реплике устарели и требуют синхронизации с основным сервером. Команду необходимо выполнять на основном узле.

   Синтаксис:

       
   copywala catchup send <replica_addresses> [flags]

   Обязательные параметры:

   <replica_addresses> – список адресов реплик в формате host:port, разделенных запятой, на которые будут отправляться данные с основного сервера.

   Опциональные параметры:

   [flags] – доступны следующие флаги:

   Флаг	Описание
   -h|--help	Показать справку по команде
   -c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml

   Важно

   Данный шаг опционален и требует выполнения, если на шаге 2 команда copywala catchup receive была вызвана без флага -s|--start_master_runner.

   Пользователь дожидается выполнения синхронизации реплики.

4. Пользователь выполняет необходимые действия по подготовке для запуска узла-реплики.

Исключительные сценарии

Будет выведено соответствующее сообщение для случаев:

• Не удалось установить подключение к основному узлу.
• Не удалось установить подключение к узлу-реплике.
• Закончилось место на диске.
• Возникла ошибка при создании слота репликации.
• На основном узле отсутствует расширение pgcopywala.