Catchup: синхронизация реплики с основным узлом
примечание
Исполнять сценарий необходимо от имени пользователя postgres.
Описание сценария
Функциональность copywala catchup используется для синхронизации данных между основным (primary) узлом и репликами кластера базы данных. Она обеспечивает приведение состояния реплик в соответствие с актуальным состоянием данных на primary-узле.
Синхронизация используется в случаях, когда реплика:
- не может догнать primary из-за отсутствующих WAL-файлов;
- была отключена на длительное время и существенно отстала от основного сервера;
- требует актуализации состояния после сбоя;
- подключается к кластеру после длительного простоя.
Особенности
catchup- Не требует наличия каталога резервных копий.
- В качестве метода доставки WAL-файлов поддерживается только потоковый режим.
- Во время выполнения
catchupнельзя выполнять DDL-командыCREATE TABLESPACEиDROP TABLESPACE. - Копирование внешних каталогов не поддерживается (за исключением каталога с табличными пространствами).
Настройка функциональности copywala catchup осуществляется с помощью параметров секции catchup_policy конфигурационного файла copywala.yaml.
Параметры секции catchup_policy
# --------------------------------------
# Настройка подключения к целевой БД
# --------------------------------------
target_db:
host: localhost
port: 5433
user: {username}
password: password
database: postgres
# опция получения секретов подключения к БД через утилиту pg_auth_config
is_pg_auth_config_enabled: false # параметр позволяет применять аутентификацию пользователей при помощи pg_auth_config # если значение выставлено true, то в данном разделе параметр password указывать не нужно
pg_auth_config_plugins_path: /usr/lib/pbr/copywala # путь к каталогу, содержащему плагины аутентификации
vault_database_engine_static_role: # имя статической роли в хранилище секретов для получения доступов к БД. Значение пустое по умолчанию
query_params: search_path=pbr # параметр позволяет настроить набор значений, специфичных для Pangolin/PostgreSQL, при подключении к базе данных
# по умолчанию применяется глобальный tls
tls:
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Возможность загрузки TLS-сертификатов из HashiCorp Vault / Secret Management System (SecMan)
# --------------------------------------
vault: # настройки подключения
server: "<vault-url>"
namespace: "<namespace>"
path: "<mount-path>" # путь к точке монтирования хранилища секретов
kv_version: v2 # версия формата формата KV-хранилища
approle:
role_id: <role-id> # уникальный идентификатор роли
secret_id: <secret-id> # секретный ключ роли. Либо указывается явно, либо прописывается wrapping_secret_id_file_path
# auth_method: approle # метод аутентификации
# wrapping_secret_id_file_path: /var/pbr/cw.wrapped.secret.vlt # путь к файлу для хранения wrapping token
# wrapping_secret_id_ttl: 8h # время жизни wrapping token (например, 10m - 10 минут, 6h - 6 часов)
# --------------------------------------
# Параметры подключения к KMS HashiCorp Vault
# --------------------------------------
kms:
server: "<vault-url>" # URL сервера KMS
namespace: "<namespace>" # пространство имен в KMS HashiCorp Vault
path: "<mount-path>" # путь к точке монтирования хранилища секретов
kv_version: v2 # версия формата KV-хранилища
approle: # вариант авторизации в KMS по роли и ключа роли
role_id: "<role-id>" # уникальный идентификатор роли
secret_id: "<secret-id>" # секретный ключ роли. Либо указывается явно, либо прописывается wrapping_secret_id_file_path
# auth_method: approle # метод аутентификации
# wrapping_secret_id_file_path: /var/pbr/cw.wrapped.secret.vlt # путь к файлу для хранения wrapping token
# wrapping_secret_id_ttl: 8h # время жизни wrapping token (например, 10m - 10 минут, 6h - 6 часов)
userpass: # вариант авторизации в KMS по логину и паролю
# username:
# password:
# auth_method:
# --------------------------------------
# Настройки БД для хранения информации о выполненных задачах резервного копирования и восстановления данных
# --------------------------------------
pbra_db:
host: localhost
port: 5433
user: {username}
password: password
database: postgres
is_pg_auth_config_enabled: false # параметр позволяет применять аутентификацию пользователей при помощи pg_auth_config # если значение выставлено true, то в данном разделе параметр password указывать не нужно
vault_database_engine_static_role: # имя статической роли в хранилище секретов для получения доступов к БД. Значение пустое по умолчанию
query_params: search_path=pbr # параметр позволяет настроить набор значений, специфичных для Pangolin/PostgreSQL, при подключении к базе данных
tls:
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Назначение резервной копии (обязательный параметр без restore_data_path)
# --------------------------------------
# local-fs:///home/postgres/backups/
# ddboost://srv-10-15.host/storage-unit
# s3://srv-10-20.host/bucket-08-9992
# s2://srv-10-25.host:port
backup_destination_uri: local-fs:///home/postgres/backups/
# --------------------------------------
# Назначение директории для архивирования WAL-файлов
# --------------------------------------
# local-fs:///home/postgres/backups/wals/
# s3://srv-10-20.host/wals-bucket/
# s2://srv-10-25.host:port/wals/
wal_destination_uri: local-fs:///home/postgres/backups/wals/
# --------------------------------------
# Секция параметров multi-restore (механизм восстановления WAL-файлов из нескольких хранилищ)
# --------------------------------------
wal_restore:
multi_restore_wal_uris: ["s2://srv-10-25.host:29509/path1", "s2://srv-10-26.host:29509/path2"] # список хранилищ WAL-файлов. Значение параметра формируется автоматически при вызове copywala restore-wal prepare-multi-restore
multi_restore_cache_path: /var/pbr/copywala/multi-restore.wals.cache # путь к кеш-файлу с информацией о хранилищах и диапазонах WAL-файлов, которые в них находятся
# --------------------------------------
# Директория для восстановления данных (обязательный параметр без backup_destination_uri)
# --------------------------------------
restore_data_path: local-fs:///pgdata/06/data
# --------------------------------------
# Наименование экземпляра БД для восстановления
# --------------------------------------
restore_instance_name: NAME_UUID # пример: db1_0198ad69-1a19-7b7f-9f46-f200942fd61c
# --------------------------------------
# Настройка повторных попыток при возникновении ошибок при записи РК
# --------------------------------------
retrier:
timeout: 10s # максимальное время выполнения запроса
retries: 5 # максимальное количество попыток
delay_period: 1s # период задержки
# --------------------------------------
# Размер WAL-файла (опционально, по умолчанию 16777216 (16MB))
# --------------------------------------
wal_segment_size: 16MB
# --------------------------------------
# Конфигурация S3
# --------------------------------------
s3:
region: ru-test # регион s3
access_id: <id> # идентификатор пользователя
secret_key: <key> # секретный ключ
use_path_style: false # если параметр имеет значение true, задействуется формат полного URL с указанием пути (path-style addressing); если false – название бакета включается непосредственно в доменное имя.
disable_request_checksums: false # проверка контрольных сумм запросов
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Конфигурация S2
# --------------------------------------
s2:
checksum_algorithm: DISABLED # выбор алгоритма вычисления контрольной суммы. Допустимые значения: DISABLED (по умолчанию), CRC32
storage_path: "" # значение по умолчанию пустое. Задается пользователем для возможности выбора одного из дополнительных хранилищ, пример: /var/pbr/s2/backups
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
s2tp_enabled: true # флаг использования протокола S2TP для взаимодействия copywala и storage service (s2). По умолчанию – true. Используется только в рамках операций передачи данных при создании и восстановлении резервных копий. gRPC остается как основной протокол для взаимодействия с S2, кроме переноса данных.
# при значении false – используется gRPC для всех взаимодействий
s2tp:
addresses: # массив адресов сервера s2
- "<host_1:port_1>"
- "<host_2:port_2>"
# ...
# Важно: порты, указанные в этом массиве должны совпадать с портам из storage-service.yaml блока s2.s2tp.addresses.
# Хосты, указанные в этом массиве должны совпадать с значением параметра backup_destination_uri файла copywala.yaml.
enable_tls: true # флаг использования TLS-протокола
max_connections: 16 # максимальное количество открытых соединений к серверу (на все указанные в массиве s2tp.addresses адреса)
read_timeout: 5m # таймаут для операции чтения
write_timeout: 5m # таймаут для операции записи
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Конфигурация DDBoost (Data Domain Boost)
# --------------------------------------
ddboost:
enc_creds_path: "<path-to-enc-creds-file>" # путь к учетным данным (защищенным преобразованием) для подключения к хранилищу DDBoost (заполняется опционально). При заданном значении параметры username и password в секции storage игнорируются
client_settings:
ddboost_lib_path: libDDBoost.so # путь к динамической библиотеке DDBoost (по умолчанию — libDDBoost.so). Если не задана переменная LD_LIBRARY_PATH или в ней отсутствует нужный путь, укажите здесь полный путь к файлу
read_client_side_decompress: false # флаг включения распаковки на стороне клиента. При значении false распаковка выполняется на стороне сервера. При значении true – на стороне клиента, что позволяет снизить нагрузку на сеть
client_type: 0 # тип клиента, который подключается к DDBoost. Для copywala значение менять не требуется
buffer_size: 0 # размер буфера ввода-вывода. 0 означает использование размер буфера по умолчанию
auto_create_storage_unit: true # автоматически создавать отдельное хранилище (storage_unit) в системе Data Domain для резервных копий, если оно еще не создано
storage:
username: "<username>" # имя пользователя для подключения к хранилищу DDBoost. Игнорируется если в copywala.yaml задан параметр enc_creds_path
password: "<password>" # пароль для подключения к хранилищу DDBoost. Игнорируется если в copywala.yaml задан параметр enc_creds_path
max_conns_no: 16 # максимальное количество одновременных соединений с DDBoost; соединения переиспользуются из пула, если они не простаивали дольше max_idle_time, иначе при необходимости создается новое соединение, если не превышен лимит max_conns_no
max_idle_time: 5m # допустимое время простоя соединения, после которого неактивное подключение закрывается и удаляется из пула соединений
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# Дополнительные параметры настройки TLS для DDBoost. Подробное описание параметров и допустимых значений смотрите в официальной документации DDBoost
use_tls: false # включает TLS. Обязательно установите true, если указан хоть один сертификат в секции ddboost.storage.tls или секции глобального TLS («Конфигурация TLS используемая по умолчанию для всех сетевых соединений»)
auth_mode: 0 # режим TLS: 1 - односторонний, 2 - двусторонний, 3 - анонимный
encr_strength: 0 # уровень TLS-шифрования: 1 - слабый, 2 - сильный
cert_verify_flag: 0 # битовая комбинация флагов проверки TLS-сертификатов и FQDN клиента/сервера: 0 – отключить проверку сертификатов, 1 – проверять FQDN сервера, 2 – проверять FQDN клиента. Например, при значении 3 будет проверяться FQDN и сервера и клиента
# --------------------------------------
# Настройки архивирования РК
# --------------------------------------
archive_settings:
upload_params:
part_payload_size: 32MB # размер парта передаваемых данных
checksum_algorithm: CRC32 # выбор алгоритма вычисления контрольной суммы. CRC32 – значение по умолчанию. Допустимые значения: DISABLED, CRC32, SHA256
compression_algorithm: S2 # выбор алгоритма сжатия данных при создании РК. S2 – значение по умолчанию. Допустимые значения: DISABLED, ZSTD, S2
# --------------------------------------
# Политика исполнения резервного копирования
# --------------------------------------
backup_policy:
strategy: pbr.policy.backup.strategy.full # выбор стратегии резервного копирования. Также доступно – pbr.policy.backup.strategy.delta
fast_checkpoint: false # флаг для переключения типа контрольной точки, по умолчанию spread (протяженная), при включении запускает принудительное создание контрольной точки сразу при начале создания базовой РК
workers_no: 2 # количество параллельных потоков, осуществляющих чтение из каталога PGDATA с диска (не включая WAL-файлы)
max_pending_wals: -1 # задает режим работы очереди (включение/отключение) и ее максимальный лимит для WAL-файлов, обрабатываемых в текущий момент (по умолчанию «-1» – очередь включена без ограничения размера)
progress_latency: 0.025 # шаг в долях от размера резервной копии, на котором сообщается прогресс
use_temporary_replication_slot: true # флаг включения использования временного слота репликации при выполнении резервного копирования: при true – используется временный слот репликации, при значении false – используется постоянный слот репликации
read_direct_io: false # режим чтения данных из файлов, исключая использование кеша ОС
write_direct_io: false # режим записи данных в файл без использования кеша ОС (актуально для локальных РК)
read_cache_size: # значение параметра должно быть кратно 4 КБ на Linux # используйте совместно с read_direct_io для РК произвольной папки (generic folder backup)
delta_max_steps: 3 # допустимое отставание реплики от главного узла при восстановлении, измеряемое количеством пропущенных шагов репликации
write_parts_workers_no: 4 # количество параллельных рабочих процессов (workers), выполняющих операцию записи отдельных партов
write_wals_workers_no: 4 # количество параллельных рабочих процессов (workers), выполняющих обработку WAL-файлов
verify_page_checksums: false # активация проверки контрольных сумм страниц во время исполнения РК
max_allowed_page_verification_failures: 0 # максимальное количество ошибок при проверке целостности страниц во время исполнения РК
backup_file_mode: 0400 # числовое представление прав доступа на создаваемые файлы
backup_dir_mode: 0700 # числовое представление прав доступа на создаваемые каталоги
wal_stream_tmp_dir: /tmp # директория для временного хранения WAL-файлов перед записью в резервную копию
protection_key_path: # путь к ключу в KMS HashiCorp Vault, необходимому для защитного преобразования при создании резервной копии
local_path: "<local-path>"
# vault_path: <path>
# vault_key: <key>
compress_tde: true # включает защитное преобразование на стороне copywala. Используется если включено сжатие (в copywala.yaml задан archive_settings.compression_algorithm) и в Pangolin включен TDE (в is_tde_on = on).
# Данный параметр игнорируется при резервном копировании чистого PostgreSQL, произвольных директорий (generic-folder) и других СУБД, в которых не используется защитное преобразование
extra_files: # список путей к дополнительным файлам, которые необходимо включить в резервную копию. По умолчанию пуст: это значит, что в архив резервной копии будут сохранены только данные из PGDATA и из связанных с ней табличных пространств
# файлы, указанные ниже, приведены для примера
- /etc/pangolin-pooler/pangolin-pooler.ini
- /etc/pangolin-manager/postgres.yml
# --------------------------------------
# Пример политики слияния (значения по умолчанию)
# --------------------------------------
merge_policy:
write_parts_workers_no: max(runtime.NumCPU()/2, 1) # количество одновременно работающих процессов для записи частей резервных копий. Устанавливается равным половине числа ядер CPU, но минимум один поток
read_parts_workers_no: max(runtime.NumCPU()/2, 1) # количество одновременно работающих процессов для чтения резервных копий. Равно половине количества ядер CPU, но не менее одного потока
verify_page_checksums: false # проверка контрольных сумм страниц PostgreSQL
max_allowed_page_verification_failures: 0 # максимальное число допустимых ошибок при проверке контрольных сумм страниц
verify_archive_checksums: true # проверка контрольных сумм всего архива резервной копии
read_direct_io: false # приложение будет использовать буферизованный ввод-вывод операционной системы при чтении данных
write_direct_io: false # приложение будет использовать буферизованный ввод-вывод операционной системы при записи данных
# --------------------------------------
# Параметры синхронизации узлов кластера БД
# --------------------------------------
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> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/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> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Конфигурация архивирования WAL-файлов
# --------------------------------------
wal_archiving:
is_multi_wal_archiving_enabled: false # многопоточный режим архивации WAL-файлов
multi_wal_archiving_workers_no: 4 # количество потоков для параллельной передачи WAL-файлов в хранилище
wal_batch_size: 100 # 100 по умолчанию. Чтобы отключить ограничение размера пакета, установите значение равным 0 или любому отрицательному целому числу
# Archive WALs in CWL
is_wal_archiving_in_cwl_enabled: false # включение/отключение архивации журналов предзаписи WAL в CWL
wal_archiving_cwl_max_file_size: 1GB # максимальный размер CWL-архива с WAL-сегментами
force_switch_cwl_lock_timeout: 15s # Максимальное время ожидания командой copywala archive-wal force-switch-cwl освобождения эксклюзивной блокировки, удерживаемой процессом copywala archive-wal при архивировании WAL-файлов в CWL-архив
wal_compression_algorithm: S2 # алгоритм сжатия WAL-файлов. S2 – значение по умолчанию. Допустимые значения: DISABLED, ZSTD, S2, LZ4
is_archive_logs_to_file_only: false # флаг отключения логирования сообщений уровня INFO в стандартный поток ошибок (stderr). При значении true – сообщения уровня INFO записываются только в журнал Copywala
dir_mode: 0700 # настройка прав доступа для каталогов создаваемых при архивировании
file_mode: 0600 # настройка прав доступа для архивируемых WAL-файлов
wal_file_mode: 0600 # числовое представление прав доступа на создаваемые файлы
wal_dir_mode: 0700 # числовое представление прав доступа на создаваемые каталоги
wal_prefetch_size: 0 # включение и регулировка многопоточной загрузки WAL-файлов. По умолчанию выключено
wal_prefetch_dir: "" # путь к директории для хранения предзагруженных WAL-файлов. По умолчанию пустое значение означает что, директория создается в каталоге pg_wal
# --------------------------------------
# Политика восстановления (ниже приведены значения по умолчанию)
# --------------------------------------
restore_policy:
workers_no: runtime.NumCPU()
jobs_queue_size: 16 # размер очереди задач на распаковку партов архива
progress_latency: 0.1 # шаг в долях от размера резервной копии, на котором сообщается прогресс (0.1 - каждые 10%)
reverse_restore: false # порядок восстановления резервных копий данных. При true – восстановление производится в обратном порядке, при false – восстановление идет последовательно
verify_page_checksums: false # активация проверки контрольных сумм страниц во время восстановления
max_allowed_page_verification_failures: 0 # максимальное количество ошибок при проверке целостности страниц во время восстановления
verify_archive_checksums: true # проверка контрольных сумм всего архива
read_direct_io: false # режим чтения данных из файлов, исключая использование кеша ОС
write_direct_io: false # режим записи данных в файлы, исключая использование кеша ОС (не доступно для generic folder backups)
protection_key_path: # путь к ключу в KMS HashiCorp Vault, необходимому для защитного преобразования при восстановлении из резервной копии
local_path: "<local-path>"
# vault_path: <path>
# vault_key: <key>
# --------------------------------------
# Конфигурация TLS используемая по умолчанию для всех сетевых соединений (DB, S2, S3, ...)
# --------------------------------------
tls:
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Конфигурация Prometheus (подробное описание атрибутов по умолчанию и обязательных атрибутов каждого поля см. в документации)
# --------------------------------------
prometheus:
push_model:
jobname:
address:
process_collector_opts:
report_errors:
pid:
namespace:
frequency:
req_timeout:
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
pull_model:
endpoint: /metrics
address:
process_collector_opts:
report_errors:
pid:
namespace:
handler_opts:
timeout:
max_requests_in_flight:
disable_compression:
log_errors:
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HarhiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Опциональные настройки приложения
# --------------------------------------
app:
agent_id_file_path: /etc/pbr/pbr.agent.id # путь к файлу, содержащему идентификатор агентcкого приложения
copywala_dir: /etc/pbr/copywala # рабочая директория
allow_concurrent_create_backup: false # управляет возможностью запуска нескольких операций создания резервных копий одновременно
agent_id_file_mode: 0400 # числовое представление прав доступа на создаваемые файлы
copywala_dir_mode: 0700 # числовое представление прав доступа на создаваемые каталоги
creds_private_key_path: /var/pbr/copywala/priv.key # путь к приватному ключу приложения
copywala_plugins_dir: /usr/lib/pbr/copywala # путь к директории, где находится плагин защитного преобразования
go_mem_limit: 2GB # мягкий лимит heap-памяти для сборщика мусора Go. При достижении лимита сборщик мусора начинает работать с большей частотой, чтобы удерживать потребление памяти в заданных пределах (в документации go – GOMEMLIMIT)
# если параметр не указан в copywala.yaml, лимит памяти будет автоматически установлен в размере 1/4 от общего объема RAM, доступного в системе (например, при 32 ГБ оперативной памяти лимит составит 8 ГБ)
# если задано значение 0 – будут использоваться настройки Go по умолчанию
# при указании значения – будет установлен заданный лимит
go_gc_percent: 100 # процент роста heap-памяти перед запуском сборки мусора. Значение 100 означает, что сборка мусора запускается после увеличения объёма heap в 2 раза относительно объема после предыдущей сборки (в документации go – GOGC)
# более подробное описание параметров приведено в документации go https://go.dev/doc/gc-guide (см. GOMEMLIMIT и GOGC)
# --------------------------------------
# Настройка параметров подключения к Platform V Monitor (OPM) и Единый клиент (SDK) Platform V Monitor (MSDK)
# --------------------------------------
audit:
central_audit: # секция с подключением к Platform V Monitor (OPM)
address: "<https://audit.example.com>"
tls: # (опционально) сертификаты для подключения к хранилищу через tls
rootca: # пути к сертификату удостоверяющего центра
local_path: "<tls/root.crt>" # путь к локальному файлу
vault_path: "<path>" # путь к секрету в HashiCorp Vault/SecMan
vault_key: "<key>" # ключ внутри JSON-секрета
cert: # пути к сертификату сервера
local_path: "<tls/cert.crt>"
vault_path: "<path>" # путь к секрету в HashiCorp Vault/SecMan
vault_key: "<key>" # ключ внутри JSON-секрета
key: # пути к ключу сервера
local_path: "<tls/cert.key>"
vault_path: "<path>" # путь к секрету в HashiCorp Vault/SecMan
vault_key: "<key>" # ключ внутри JSON-секрета
msdk_audit: # секция с подключением к Единый клиент (SDK) Platform V Monitor (MSDK)
address: "<https://audit.msdk.example.com>"
tls: # (опционально) сертификаты для подключения к хранилищу через tls
rootca: # пути к сертификату удостоверяющего центра
local_path: "<tls/root.crt>" # путь к локальному файлу
vault_path: "<path>" # путь к секрету в HashiCorp Vault/SecMan
vault_key: "<key>" # ключ внутри JSON-секрета
cert: # пути к сертификату сервера
local_path: "<tls/cert.crt>"
vault_path: "<path>" # путь к секрету в HashiCorp Vault/SecMan
vault_key: "<key>" # ключ внутри JSON-секрета
key: # пути к ключу сервера
local_path: "<tls/cert.key>" # путь к локальному файлу
vault_path: "<path>" # путь к секрету в HashiCorp Vault/SecMan
vault_key: "<key>" # ключ внутри JSON-секрета
retrier: # настройка повторных попыток при возникновении ошибок при отправке событий аудита
timeout: 10s # максимальное время выполнения запроса
retries: 5 # максимальное количество попыток
delay_period: 1s # период задержки
# --------------------------------------
# Настройка ведения журналов приложения
# --------------------------------------
log:
path: /var/log/pbr/copywala.log # путь к лог-файлу
dir_mode: 0700 # настройка прав доступа на создаваемые каталоги. Значения необходимо задавать в восьмеричной системе счисления с ведущим нулем.
file_mode: 0600 # настройка прав доступа на создаваемые файлы. Значения необходимо задавать в восьмеричной системе счисления с ведущим нулем.
max_size: 100 # максимальный размер лог-файла в мегабайтах. По умолчанию `100 МБ`
max_age: 90 # максимальный возраст лог-файла в днях
max_backups: 10 # максимальное количество резервных копий лог-файлов, которые будут храниться. Если выбрано 0, то количество файлов не ограничено
use_local_time: true # параметр определяет, в каком формате будут записываться метки времени в имена файлов при ротации. Если выбрано true, используется локальное системное время, при false (и по умолчанию) – `UTС`.
compress_backups: false # параметр определяет необходимость сжатия файлов. Если выбрано true, лог-файлы будут сжаты, если false, лог-файлы будут храниться без сжатия
Выполнение синхронизации возможно в одном из режимов, который задается в конфигурационном файле 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 при смене ролей между узлами).
- На репликах должна существовать или быть создана целевая директория для данных (
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.dev.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.dev.example). В результате проверка сравнения сallow_replica_hostsможет завершиться ошибкой, если там указаны FQDN или IP. Чтобы избежать таких проблем, рекомендуется в значенииreplica_params.s2tp.addresses:- либо явно указать FQDN-имена хостов реплик (например,
srv-xx-xx.db.dev.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.
:caption: Пример корректной конфигурации с использованием 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
:caption: Пример корректной конфигурации с использованием 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) приведен в секции «Дополнительные возможности».
Предусловия
Перед началом синхронизации убедитесь, что:
-
На основном узле и всех узлах-репликах установлены:
- Pangolin Manager;
- утилита copywala.
-
На всех узлах кластера установлено расширение
pgcopywalaверсии 1.1, обеспечивающее выполнение команд copywala через протокол PostgreSQL.ВажноПри использовании расширения
pgcopywalaверсии 1.0 обязательно выполните обновление до версии 1.1 в соответствии с инструкцией. -
В конфигурационном файле 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.
-
Запустите кластер и убедитесь, что все узлы находятся в рабочем состоянии:
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.
:caption: Пример запроса
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::caption: Пример сообщений на основном узле
...
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(установлена не актуальная версия расширения)::caption: Пример сообщений на основном узле
...
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-логики:
:caption: Пример сообщений на основном узле
...
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 master
2026-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.
:caption: Пример запроса
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 | Текст ошибки |