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-файлов из архивного хранилища.
Предусловие
-
Установите утилиту copywala}} на всех узлах кластера (установка на узлах-репликах необходима для возможности работы catchup при смене ролей между узлами).
ВажноДля выполнения административных операций на всех узлах должны быть созданы и настроены пользователи
backup_userилиcopywala_user. Описание по созданию и настройке приведено в руководстве по установке, Установка из RPM-пакета, раздел Установка Copywala, секция Предусловия. -
На репликах должна существовать или быть создана целевая директория для данных (
PGDATA). Путь к этой директории используется в обязательном флаге--datadirпри вызове командыcopywala catchup send. -
В конфигурационном файле
copywala.yamlдля всех узлов кластера в секцииcatchup_policyзадайте значения для параметров:
Параметр | Описание |
|---|---|
| Режим catchup. Значение должно быть одинаковым на всех узлах кластера |
Секция | Параметры основного (primary) узла Параметры секции |
Секция | Параметры узлов-реплик Параметры секции |
-
Секции
master_paramsиreplica_paramsнеобходимо заполнять на всех узлах кластера. Это требуется для корректной работы функциональности catchup при смене ролей между узлами. -
Параметр
replica_params.s2tp.addressesявляется обязательным. При его отсутствии синхронизация завершится с ошибкой:addresses are not provided: cannot init s2tp server -
Формат адресов в
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-адреса.
- если в
-
При указании в
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).
- либо явно указать FQDN-имена хостов реплик (например,
-
По умолчанию для взаимодействия между узлами кластера используется TLS-шифрование. Для его корректной работы необходимо настроить сертификаты в разделах
replica_params.s2tp.tlsиmaster_params.s2tp.tls. Для отключения TLS на реплике удалите разделreplica_params.s2tp.tlsи на primary-узле в разделеmaster_params.s2tpустановите параметрenable_tls: false.
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
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) приведен в секции «Дополнительные возможности».
Предусловия
Перед началом синхронизации убедитесь, что:
-
На основном узле и всех узлах-репликах установлены:
- Pangolin Manager;
- утилита copywala.
-
На всех узлах кластера установлено расширение
pgcopywalaверсии 1.1, обеспечивающее выполнение команд copywala через протокол PostgreSQL.ВажноПри использовании расширения
pgcopywalaверсии 1.0 обязательно выполните обновление до версии 1.1 в соответствии с инструкцией. -
В конфигурационном файле Pangolin Manager (по умолчанию
/etc/pangolin-manager/postgres.yml) заданы значения для параметров синхронизации:postgresql: # корневая секция postgrescreate_replica_methods:- copywalacopywala:command: copywala catchup receive --start_master_runnerno_params: false # флаг передачи параметров как аргументы командой строки, а не переменные окружения. Важно: передача через переменные окружения не поддерживается в текущей реализации, поэтому не меняйте значение данного параметра
Последовательность действий
При использовании Pangolin Manager остановка реплики и ее последующий запуск после завершения синхронизации выполняются автоматически средствами Pangolin Manager.
-
Запустите кластер и убедитесь, что все узлы находятся в рабочем состоянии:
pangolin-manager-ctl -c /etc/pangolin-manager/postgres.yml listКоманда выводит список узлов кластера и их текущее состояние.
-
На реплике, которую необходимо синхронизировать, выполните команду (пример команды):
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)
-
Остановите узел-реплику (реплики).
-
В 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 master2026-05-20 13:46:45.758 [112] INF start sync files via pgcopywala extension... -
В 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 -
-
Выполните необходимые действия по подготовке для запуска узла-реплики.
Результат
Реплика содержит актуальную копию данных основного узла кластера.
Дополнительную информацию о задачах 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 | Текст ошибки |