Перейти к основному содержимому

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

примечание

Исполнять сценарий необходимо от имени пользователя postgres.

Описание сценария​

Функциональность copywala catchup используется для синхронизации данных между основным (primary) узлом и репликами кластера базы данных. Она обеспечивает приведение состояния реплик в соответствие с актуальным состоянием данных на primary-узле.

Синхронизация используется в случаях, когда реплика:

  • не может догнать primary из-за отсутствующих WAL-файлов;
  • была отключена на длительное время и существенно отстала от основного сервера;
  • требует актуализации состояния после сбоя;
  • подключается к кластеру после длительного простоя.
Особенности catchup

  • Не требует наличия каталога резервных копий.
  • В качестве метода доставки WAL-файлов поддерживается только потоковый режим.
  • Во время выполнения catchup нельзя выполнять DDL-команды CREATE TABLESPACE и DROP TABLESPACE.
  • Копирование внешних каталогов не поддерживается (за исключением каталога с табличными пространствами).

Настройка функциональности copywala catchup осуществляется с помощью параметров секции catchup_policy конфигурационного файла copywala.yaml.

Параметры секции catchup_policy

catchup_policy:
strategy: pbr.policy.backup.strategy.full # стратегия синхронизации

# параметры для основного узла (primary)
master_params:
workers_no: 4 # количество параллельных рабочих процессов (workers), одновременно на одном воркере загружается только один файл
wals_workers_no: 4 # количество параллельных рабочих процессов (workers), необходимых для передачи WAL-файлов через репликационный протокол
max_pending_wals: -1 # размер очереди WAL-файлов на отправку. Останавливает синхронизацию (catchup), если лимит очереди WAL-файлов на отправку превышен. По умолчанию выключен
wal_stream_tmp_dir: # директория для временного хранения WAL-файлов
progress_latency: 0.1 # шаг в долях от размера резервной копии, на котором в логах отображается прогресс (0.1 - каждые 10%)
write_file_timeout: 30m # тайм-аут загрузки одного файла, если файл не успел загрузиться за это время, то синхронизация (catchup) обрывается
fast_checkpoint: false # флаг для переключения типа контрольной точки
allow_replica_hosts: # хосты всех узлов кластера, с которых мастеру разрешено подключаться к серверу реплики
- 10.40.48.109
s2tp:
enable_tls: true # флаг использования TLS-протокола
max_connections: 16 # максимальное количество TCP-соединений, которое может быть открыто при взаимодействии с сервером реплики одновременно
read_timeout: 5m # тайм-аут одного запроса на чтение, не учитывается при загрузке файла
write_timeout: 5m # тайм-аут одного запроса на запись, не учитывается при загрузке файла
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета

# параметры для узла-реплики (standby)
replica_params:
s2tp:
addresses: # адреса, на которых запускается сервер реплики и ожидаются подключения от primary. Если используется Pangolin Manager или другие инструменты управления кластером, убедитесь, что указанные адреса доступны с мастера
- 0.0.0.0:29505
mtls: false # флаг включения взаимодействия по mTLS
max_connections: 16 # максимальное количество TCP-соединений, которое может быть открыто при взаимодействии с сервером реплики одновременно
read_timeout: 5m # тайм-аут одного запроса на чтение, не учитывается при загрузке файла
write_timeout: 5m # тайм-аут одного запроса на запись, не учитывается при загрузке файла
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета

Выполнение синхронизации возможно в одном из режимов, который задается в конфигурационном файле copywala.yaml в параметре catchup_policy.strategy:

Режим catchupОписание
pbr.policy.backup.strategy.fullПолное копирование данных с primary на реплику. Используется для полной синхронизации реплики и включает передачу всех данных с последующим приведением состояния реплики в соответствие с primary-узлом
pbr.policy.backup.strategy.archiveПолное копирование данных с primary на реплику без потоковой передачи WAL-файлов
подсказка

Если используется собственная система хранения WAL-файлов, а на узле-реплике настроены параметры archive_command/restore_command для получения и применения WAL-файлов, рекомендуется использовать режим pbr.policy.backup.strategy.archive. В этом режиме после копирования данных реплика догоняет primary-узел за счет применения WAL-файлов из архивного хранилища.

Предусловие​

  1. Установите утилиту copywala}} на всех узлах кластера (установка на узлах-репликах необходима для возможности работы catchup при смене ролей между узлами).

    Важно

    Для выполнения административных операций на всех узлах должны быть созданы и настроены пользователи backup_user или copywala_user. Описание по созданию и настройке приведено в руководстве по установке, Установка из RPM-пакета, раздел Установка Copywala, секция Предусловия.

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

  3. В конфигурационном файле copywala.yaml для всех узлов кластера в секции catchup_policy задайте значения для параметров:

Параметр

Описание

catchup_policy.strategy

Режим catchup. Значение должно быть одинаковым на всех узлах кластера

Секция catchup_policy.master_params

Параметры основного (primary) узла

Параметры секции catchup_policy.master_params

master_params:
workers_no: 4 # количество параллельных рабочих процессов (workers), одновременно на одном воркере загружается только один файл
wals_workers_no: 4 # количество параллельных рабочих процессов (workers), необходимых для передачи WAL-файлов через репликационный протокол
max_pending_wals: -1 # размер очереди WAL-файлов на отправку. Останавливает синхронизацию (catchup), если лимит очереди WAL-файлов на отправку превышен. По умолчанию выключен
wal_stream_tmp_dir: # директория для временного хранения WAL-файлов
progress_latency: 0.1 # шаг в долях от размера резервной копии, на котором в логах отображается прогресс (0.1 - каждые 10%)
write_file_timeout: 30m # тайм-аут загрузки одного файла, если файл не успел загрузиться за это время, то синхронизация (catchup) обрывается
fast_checkpoint: false # флаг для переключения типа контрольной точки
allow_replica_hosts: # хосты всех узлов кластера, с которых мастеру разрешено подключаться к серверу реплики
- 10.40.48.109
s2tp:
enable_tls: true # флаг использования TLS-протокола
max_connections: 16 # максимальное количество TCP-соединений, которое может быть открыто при взаимодействии с сервером реплики одновременно
read_timeout: 5m # тайм-аут одного запроса на чтение, не учитывается при загрузке файла
write_timeout: 5m # тайм-аут одного запроса на запись, не учитывается при загрузке файла
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета

Секция catchup_policy.replica_params

Параметры узлов-реплик

Параметры секции catchup_policy.replica_params

replica_params:
s2tp:
addresses: # адреса, на которых запускается сервер реплики и ожидаются подключения от primary. Если используется Pangolin Manager или другие инструменты управления кластером, убедитесь, что указанные адреса доступны с мастера
- 0.0.0.0:29505
mtls: false # флаг включения взаимодействия по mTLS
max_connections: 16 # максимальное количество TCP-соединений, которое может быть открыто при взаимодействии с сервером реплики одновременно
read_timeout: 5m # тайм-аут одного запроса на чтение, не учитывается при загрузке файла
write_timeout: 5m # тайм-аут одного запроса на запись, не учитывается при загрузке файла
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета

# --------------------------------------
Важные правила настройки параметров

  1. Секции master_params и replica_params необходимо заполнять на всех узлах кластера. Это требуется для корректной работы функциональности catchup при смене ролей между узлами.

  2. Параметр replica_params.s2tp.addresses является обязательным. При его отсутствии синхронизация завершится с ошибкой:

    addresses are not provided: cannot init s2tp server
  3. Формат адресов в master_params.allow_replica_hosts и replica_params.s2tp.addresses должен быть одинаковым:

    • если в allow_replica_hosts указаны FQDN-имена (например, srv-xx-xx.db.example), то в replica_params.s2tp.addresses также должны быть указаны FQDN;
    • если в allow_replica_hosts указаны IP-адреса, то в replica_params.s2tp.addresses также должны быть указаны IP-адреса.
  4. При указании в replica_params.s2tp.addresses значения 0.0.0.0, оно будет заменено на значение из /etc/hostname, которое обычно содержит короткое имя хоста (например, srv-xx-xx, а не srv-xx-xx.db.example). В результате проверка сравнения с allow_replica_hosts может завершиться ошибкой, если там указаны FQDN или IP. Чтобы избежать таких проблем, рекомендуется в значении replica_params.s2tp.addresses:

    • либо явно указать FQDN-имена хостов реплик (например, srv-xx-xx.db.example:29505);
    • либо явно указать IP-адреса реплик (например, 192.0.2.1:29505).
  5. По умолчанию для взаимодействия между узлами кластера используется TLS-шифрование. Для его корректной работы необходимо настроить сертификаты в разделах replica_params.s2tp.tls и master_params.s2tp.tls. Для отключения TLS на реплике удалите раздел replica_params.s2tp.tls и на primary-узле в разделе master_params.s2tp установите параметр enable_tls: false.

Пример корректной конфигурации с использованием FQDN

catchup_policy:
strategy: pbr.policy.backup.strategy.full
master_params:
workers_no: 4
wals_workers_no: 4
write_file_timeout: 30m0s
fast_checkpoint: true
allow_replica_hosts:
- replica-1.example
- replica-2.example
s2tp:
enable_tls: true
max_connections: 16
read_timeout: 5m
write_timeout: 5m
replica_params:
s2tp:
addresses:
- replica-1.example:29505
mtls: false
max_connections: 16
read_timeout: 5m
write_timeout: 5m

Пример корректной конфигурации с использованием IP-адресов

catchup_policy:
strategy: pbr.policy.backup.strategy.full
master_params:
workers_no: 4
wals_workers_no: 4
write_file_timeout: 30m0s
fast_checkpoint: true
allow_replica_hosts:
- 192.0.2.1
- 192.0.2.2
s2tp:
enable_tls: true
max_connections: 16
read_timeout: 5m
write_timeout: 5m
replica_params:
s2tp:
addresses:
- 192.0.2.1:29505
mtls: false
max_connections: 16
read_timeout: 5m
write_timeout: 5m

Последовательность выполнения​

к сведению

Ниже описан сценарий выполнения catchup c использованием Pangolin Manager — оркестратором кластера Pangolin, обеспечивающим высокую доступность PostgreSQL-кластера и поддержку переключения ролей между узлами. Синхронизация реплики в этом сценарии выполняется с помощью компонента pangolin-manager-ctl, который управляет процессом восстановления и актуализации состояния узлов-реплик.

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

Предусловия

Перед началом синхронизации убедитесь, что:

  1. На основном узле и всех узлах-репликах установлены:

    • Pangolin Manager;
    • утилита copywala.
  2. На всех узлах кластера установлено расширение pgcopywala версии 1.1, обеспечивающее выполнение команд copywala через протокол PostgreSQL.

    Важно

    При использовании расширения pgcopywala версии 1.0 обязательно выполните обновление до версии 1.1 в соответствии с инструкцией.

  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 # флаг передачи параметров как аргументы командой строки, а не переменные окружения. Важно: передача через переменные окружения не поддерживается в текущей реализации, поэтому не меняйте значение данного параметра

Последовательность действий

к сведению

При использовании Pangolin Manager остановка реплики и ее последующий запуск после завершения синхронизации выполняются автоматически средствами Pangolin Manager.

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

    pangolin-manager-ctl -c /etc/pangolin-manager/postgres.yml list

    Команда выводит список узлов кластера и их текущее состояние.

  2. На реплике, которую необходимо синхронизировать, выполните команду (пример команды):

    pangolin-manager-ctl -c /etc/pangolin-manager/postgres.yml reinit pangolin_cluster pangolin02

    где:

    • pangolin_cluster — имя кластера;
    • pangolin02 — имя реплики, для которой запускается синхронизация.

    Имя кластера и имя реплики можно получить из вывода команды list, выполненной на шаге 1.

Результат​

Реплика содержит актуальную копию данных основного узла кластера. При успешном завершении синхронизации в логах Pangolin Manager будет выведено сообщение:

2026-05-08 08:29:45,176 INFO: replica has been created using copywala

Дополнительную информацию о задачах catchup можно получить из таблицы pbr_catchup_tasks, которая расположена в схеме pbr служебной базы данных, определенной в copywala.yaml в секции pbra_db.

Пример запроса

select * from pbr.pbr_catchup_tasks;
-[ RECORD 1 ]-------+-------------------------------------
id | <task_id>
replica_hosts | replica-1.example:29505
strategy | pbr.policy.backup.strategy.full
status | pbr.tasks.status.started
processed_data_size | 0
total_data_size | 331649455941
wal_size | 0
started_at | 2026-07-29 10:10:47.963667+03
finished_at |
created_at | 2026-07-29 10:10:47.849777+03
updated_at | 2026-07-29 10:10:48.124417+03
error_text |

Описание полей таблицы pbr_catchup_tasks

ПолеОписание
idУникальный идентификатор задачи catchup (UUID)
replica_hostsАдрес(ы) узлов-реплик, участвующих в синхронизации (формат: host:port)
strategyСтратегия синхронизации (pbr.policy.backup.strategy.full или pbr.policy.backup.strategy.archive)
statusСтатус задачи (например, pbr.tasks.status.started)
processed_data_sizeОбъем уже обработанных данных (в байтах)
total_data_sizeОбщий объем данных, необходимых для синхронизации (в байтах)
wal_sizeОбъем обработанных WAL-файлов (в байтах)
started_atВремя начала выполнения задачи
finished_atВремя завершения задачи (пустое значение, если задача не завершена)
created_atВремя создания записи о задаче
updated_atВремя последнего обновления записи
error_textТекст ошибки

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

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

  • Не удалось установить подключение к основному узлу.

  • Не удалось установить подключение к узлу-реплике.

  • Закончилось место на диске.

  • Возникла ошибка при создании слота репликации.

  • На основном узле отсутствует расширение pgcopywala:

    Пример сообщений на основном узле
    ...
    2026-07-29 16:56:00.503 [9316] INF run catchup on master
    ...
    2026-07-29 16:56:00.512 [9316] ERR app: run: copywala err="'pgcopywala' extension is not installed"
    2026-07-29 16:56:00.512 [9316] ERR run: catchup receive err="'pgcopywala' extension is not installed"
    ...

  • Расширение pgcopywala установлено не в схеме pbr (установлена не актуальная версия расширения):

    Пример сообщений на основном узле

    ...
    2026-07-29 16:58:50.377 [9631] INF run catchup on master
    ...
    2026-07-29 16:58:50.382 [9631] ERR app: run: copywala err="'pgcopywala' extension functions not found in 'pbr' schema; update or install a newer version of 'pgcopywala'"
    2026-07-29 16:58:50.382 [9631] ERR run: catchup receive err="'pgcopywala' extension functions not found in 'pbr' schema; update or install a newer version of 'pgcopywala'"
    ...

  • У пользователя, от имени которого узел-реплика подключается к основному узлу, нет прав для запуска catchup-логики:

    Пример сообщений на основном узле

    ...
    2026-07-29 17:06:10.481 [10248] INF run catchup on master
    ...
    2026-07-29 17:06:10.489 [10248] ERR app: run: copywala err="user replica_user has no permissions to execute 'copywala_catchup_send' in 'pbr' schema; grant the required permissions on 'pbr' schema"
    2026-07-29 17:06:10.489 [10248] ERR run: catchup receive err="user replica_user has no permissions to execute 'copywala_catchup_send' in 'pbr' schema; grant the required permissions on 'pbr' schema"
    ...

Дополнительные возможности​

Повышение производительности синхронизации​

Для возможности повышения производительности предусмотрены следующие параметры:

catchup_policy:
master_params:
workers_no: 4 # количество параллельных рабочих процессов (workers), одновременно на одном воркере загружается только один файл
wals_workers_no: 4 # количество параллельных рабочих процессов (workers), необходимых для передачи WAL-файлов через репликационный протокол

Выполнение сatchup в «ручном режиме» (без использования Pangolin Manager)​

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

  2. В CLI copywala на узле-реплике запустите процесс получения данных с основного узла командой 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

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

    2026-05-20 13:35:17.962 [114] INF start catchup for pgdata path: /pgdata/data/
    2026-05-20 13:35:17.962 [114] INF wait to call <copywala catchup send> command on master...
    Важно

    Если команда 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. В CLI copywala на основном узле запустите передачу данных на реплику (реплики) командой 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

    Контролировать ход выполнения синхронизации можно только на основном узле следующими способами:

    • по логам утилиты copywala;

    • с помощью представления copywala_catchup_stat, которое расположено в БД, определенной в copywala.yaml в секции target_db. Пример запроса:

      SELECT * FROM copywala_catchup_stat;

      В представлении доступны следующие поля:

      ПолеОписание
      idИдентификатор операции catchup
      replica_hostsСписок узлов-реплик, участвующих в синхронизации
      processed_data_sizeОбъем уже обработанных данных
      total_data_sizeОбщий объем данных, необходимых для синхронизации
      wal_sizeОбъем уже обработанных WAL-файлов

      Если при очередном обращении к представлению данные не возвращаются, это значит, что процесс синхронизации завершен.

    В результате успешного завершения синхронизации на основном и узле-реплике в логах будет выведено сообщение:

    2026-05-20 13:46:45.758 [112] INF catchup complete
  4. Выполните необходимые действия по подготовке для запуска узла-реплики.

Результат

Реплика содержит актуальную копию данных основного узла кластера.

Дополнительную информацию о задачах catchup можно получить из таблицы pbr_catchup_tasks, которая расположена в схеме pbr служебной базы данных, определенной в copywala.yaml в секции pbra_db.

Пример запроса

select * from pbr.pbr_catchup_tasks;
-[ RECORD 1 ]-------+-------------------------------------
id | <task_id>
replica_hosts | replica-1.example:29505
strategy | pbr.policy.backup.strategy.full
status | pbr.tasks.status.started
processed_data_size | 0
total_data_size | 331649455941
wal_size | 0
started_at | 2026-07-29 10:10:47.963667+03
finished_at |
created_at | 2026-07-29 10:10:47.849777+03
updated_at | 2026-07-29 10:10:48.124417+03
error_text |

Описание полей таблицы pbr_catchup_tasks

ПолеОписание
idУникальный идентификатор задачи catchup (UUID)
replica_hostsАдрес(ы) узлов-реплик, участвующих в синхронизации (формат: host:port)
strategyСтратегия синхронизации (pbr.policy.backup.strategy.full или pbr.policy.backup.strategy.archive)
statusСтатус задачи (например, pbr.tasks.status.started)
processed_data_sizeОбъем уже обработанных данных (в байтах)
total_data_sizeОбщий объем данных, необходимых для синхронизации (в байтах)
wal_sizeОбъем обработанных WAL-файлов (в байтах)
started_atВремя начала выполнения задачи
finished_atВремя завершения задачи (пустое значение, если задача не завершена)
created_atВремя создания записи о задаче
updated_atВремя последнего обновления записи
error_textТекст ошибки