Создание резервной копии вручную

примечание

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

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

Инициирование процесса создания резервной копии вручную.

Предусловие

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

Важно

По умолчанию настройками copywala запрещен одновременный запуск снятия нескольких РК через copywala create-backup в целях исключения избыточной нагрузки на БД и защиты от случайного повторного запуска.

Данное поведение можно отключить, установив в конфигурационном файле copywala.yaml в разделе app поле allow_concurrent_create_backup равным значению true:

app:
  copywala_dir: /var/pbr/copywala/
  allow_concurrent_create_backup: true

При снятии РК с включенным по умолчанию режимом защиты от одновременного снятия нескольких резервных копий в директории copywala_dir создается специальный файл create-backup.lock. Этот файл служит индикатором того, что один из экземпляров copywala уже начал процедуру резервного копирования. Когда другой экземпляр пытается запустить процесс create-backup и находит указанный файл, он немедленно прерывается с сообщением об ошибке.

Учитывайте следующее:

• При запуске РК пользователь может задать путь к файлу с конфигурацией и переопределить поле copywala_dir, блокировка запуска будет работать только при одинаковых настройках рабочей папки copywala_dir. Рекомендуем убедиться, что директория copywala_dir единая для всех выполняемых операций create-backup.
• По завершении процедуры резервного копирования созданный файл блокировки автоматически удаляется, позволяя запустить новый процесс.
• В случае внезапного сбоя или прекращения операции снятия резервной копии, файл блокировки также удаляется системой, за исключением ситуаций, когда copywala получает сигнал SIGKILL. В таком случае система не успевает удалить файл самостоятельно, и ответственность за удаление файла ложится на пользователя.

Также обратите внимание:

• в конфигурационном файле copywala.yaml поле compression_algorithm предназначено для выбора алгоритма сжатия данных при создании резервных копий. По умолчанию выставлено значение S2.

  compression_algorithm: S2 # допустимые значения: DISABLED, ZSTD, S2

• Если в качестве хранилища для резервных копий используется DDBoost:

  • При создании резервной копии многопоточная запись не поддерживается из-за ограничений DDBoost. При запуске команды на резервное копирование автоматически будет установлено количество потоков записи равным единице, независимо от заданного значения (задается в copywala.yaml параметром backup_policy.write_parts_workers_no).
  • При восстановлении данных их резервной копии многопоточный режим работает без ограничений.

Работа в режиме direct_io

Режим direct_io позволяет работать напрямую с памятью приложения, тем самым повышая производительность за счет исключения дополнительного этапа кеширования.

• read_direct_io отвечает за чтение данных непосредственно с диска, минуя кеш операционной системы.

• write_direct_io отвечает за запись данных в архив в режиме прямого ввода-вывода.

  Важно

  Параметр write_direct_io применим только при создании локального архива. В данном режиме не требуется дополнительный кеш, поскольку формат архива адаптирован для прямой записи, включая автоматическое выравнивание завершающего блока по 4 Кбайт. Чтобы избежать ошибок, параметр part_payload_size в разделе конфигурации archive_settings.upload_params также должен быть кратен 4 Кбайт.

backup_policy:
  read_direct_io: false
  write_direct_io: false

Дополнительные настройки сценария

В разделе перечисляются необязательные параметры, расширяющие возможности основного сценария.

Настройка ограничения очереди WAL-файлов (при потоковой репликации)

В процессе резервного копирования WAL-файлы поступают по протоколу репликации в локальную файловую систему (определяется значением wal_stream_tmp_dir) и затем отправляются в целевое хранилище, заданное параметром wal_destination_uri.

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

Для предотвращения таких ситуаций используется параметр max_pending_wals (конфигурационный файл copywala.yaml раздел backup_policy):

backup_policy:
  max_pending_wals: -1

max_pending_wals определяет режим работы очереди WAL-файлов (включение/отключение) и задает их максимальное допустимое количество, которое может одновременно находиться в обработке. В это значение входят как WAL-файлы, находящиеся в очереди, так и WAL-файлы, которые уже обрабатываются воркерами. Например, при max_pending_wals=14 и write_wals_workers_no=4 в очереди может быть только 10 файлов, так как 4 будут в обработке у воркеров.

Возможные значения параметра max_pending_wals

Значение	Описание
-1 (задано по умолчанию)	Очередь включена без ограничения размера. Внимание! Использование данного значения может привести к переполнению диска, который используется как временное хранилище перед записью WAL-файлов в резервную копию.
0	Очередь отключена: поступающие WAL-файлы немедленно передаются воркерам для обработки. При отсутствии доступных воркеров прием WAL-файлов приостанавливается до их освобождения. Если ожидание превышает значение wal_sender_timeout (настройки БД файл postgresql.conf), то: резервное копирование прерывается с ошибкой. Текст ошибки (отформатирован для упрощения восприятия) 2026-04-08 18:43:54.587 [993659] ERR app: run: copywala err= "saving wals: process replication messages: process next message: acknowledge replication message: receive message from pangolin server: receive message failed: unexpected EOF" архив с незавершенной РК удаляется.
любое целое число > 0	При достижении или превышении указанного значения: резервное копирование прерывается с ошибкой. Текст ошибки (отформатирован для упрощения восприятия) 2026-04-10 14:53:54.942 [2366509] ERR failed to write backup aborting package=pangolin.engine err= "saving wals: process replication messages: process next message: switch WAL segment: write current WAL segment: 000000010000047300000010: limit of WAL files waiting to be written is reached max_pending_wals value: 100 suggestions: - increase backup_policy.write_wals_workers_no - increase or disable backup_policy.max_pending_wals stopping WAL delivery gateway" архив с незавершенной РК удаляется.

При выборе значения учитывайте:

• размер одного WAL-файла;
• доступное дисковое пространство;
• скорость записи в хранилище.

Ограничение очереди WAL-файлов помогает:

• предотвратить переполнение диска;
• избежать аварийного завершения работы сервера;
• контролировать потребление ресурсов во время резервного копирования.

Использование механизма автоматического определения адреса основного сервера БД (primary)

Независимо от того, для какого узла БД (основного или реплики) создается резервная копия, информация о результате РК сохраняется в БД компонента pbra_db, расположенного на одном хосте с основным сервером БД (primary).

При создании резервной копии узла реплики, важно убедиться, чтобы были заданы параметры, которые необходимы для подключения к БД pbra_db. Настройка подключения утилиты copywala к БД pbra_db возможна следующими способами:

• C помощью механизма автоматического определения адреса основного узла.
• Явное определение параметров подключения (host и port) в секции pbra_db конфигурационного файла copywala.yaml.

Принцип работы механизма

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

1. При запуске резервного копирования copywala подключается к целевой БД, указанной в конфигурационном файле copywala.yaml, секция target_db.

2. Определяется роль целевой БД с помощью функции pg_is_in_recovery():

   • true – подключение выполнено к реплике;
   • false – подключение выполнено к основному серверу.

3. Если установлено, что роль целевой БД – реплика:

   1. Адрес и порт основного сервера извлекаются из представления pg_stat_wal_receiver;
   2. Полученные значения используются для подключения к основному серверу: они подставляются вместо имеющихся в copywala.yaml (секция pbra_db, поля host и port).

Включение механизма автоматического определения адреса основного узла

1. Убедитесь, что у пользователя, выполняющего РК, есть права на чтение всех данных в представлении pg_stat_wal_receiver. Если прав нет, выдайте их одной из команд:

   • GRANT pg_monitor TO backup_user;

   • GRANT pg_read_all_stats TO backup_user;

2. В конфигурационном файле copywala.yaml:

   1. Проверьте, что в секции target_db заданы значения для параметров host и port.
   2. Проверьте, что в секции pbra_db для параметров host и port значения не заданы.

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

pbra_db host and port are automatically switched to the master address obtained from pg_stat_wal_receiver

Важно

В случае, если в секции pbra_db для параметров host и port заданы значения и значение в параметре pbra_db.host отличается от значения в target_db.host, механизм автоматического определения адреса мастера не запускается.

Добавление в резервную копию дополнительных файлов

Информация представлена в разделе – Добавление дополнительных файлов в резервную копию.

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

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

1. Убедитесь, что настройки подключения к целевой базе данных и пути для хранения архивов резервных копий, указанные в файле конфигурации, являются корректными.

2. Запустите резервное копирование через CLI утилиты Copywala командой copywala create-backup. В процессе выполнения РК будут выведены сообщения вида:

   Пример лога:

   backup progress processed_data_size=106591084604 data_size=106811663601 pending_wals=0 wal_size=3942645760

   Атрибут	Значение в примере	Описание
   processed_data_size	106591084604	Объем данных (в байтах), который уже скопирован на данный момент
   data_size	106811663601	Общий объем (в байтах) данных, который необходимо скопировать
   pending_wals	0	Количество WAL-файлов, которые находятся в очереди на обработку и архивацию
   wal_size	3942645760	Общий размер WAL-файлов (в байтах), относящихся к текущей резервной копии

   Предупреждение о переполнении очереди WAL-файлов

   В процессе выполнения РК возможно появление сообщения уровня WARN следующего вида:

   WRN wals queue overflowed: 4 wals workers, 120 pending wals package=pangolin.engine

   Это означает, что количество WAL-файлов, которые ожидают обработки (120 pending wals), превышает число обработчиков (4 wals workers).

   В такой ситуации не рекомендуется прерывать текущий процесс создания РК и дать ему завершиться. Для предотвращения подобных ситуаций в будущем, увеличьте значение параметра write_wals_workers_no (конфигурационный файл copywala.yaml раздел backup_policy), чтобы увеличить количество обработчиков WAL-файлов.

   Рекомендуем настраивать write_wals_workers_no с учетом общего количества потоков: сумма workers_no, write_parts_workers_no и write_wals_workers_no не должна превышать количество доступных CPU.

   Увеличение числа потоков сверх количества ядер не дает прироста производительности и может привести к ее снижению.

Результат

По окончании процесса резервного копирования в лог выводятся информационные сообщения о завершении операции и ее результатах.

Пример:

2026-03-20 12:31:54.123 [49049] INF completing backup
2026-03-20 12:31:56.456 [49049] INF backup stats backup=/path/to/backup/<backup_name>.cwl time_elapsed=3.594412851s time_upload=146.225796ms total_bytes=1152819488 upload_bytes=211275776 compress_ratio=5.5 compress_algorithm=S2

Описание атрибутов сообщения backup stats:

Атрибут	Значение в примере	Описание
backup	/path/to/backup/<backup_name>.cwl	Полный путь к файлу РК
time_elapsed	3.594412851s	Время создания РК
time_upload	146.225796ms	Время, затраченное на передачу данных в хранилище
total_bytes	1152819488	Общий объем данных, скопированных при создании резервной копии (в байтах)
upload_bytes	211275776	Общий объем данных, переданных в хранилище (в байтах). Значение upload_bytes < total_bytes, так как используется сжатие данных
compress_ratio	5.5	Степень сжатия данных
compress_algorithm	S2	Использованный алгоритм сжатия

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

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

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