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

Сведения

В текущей версии утилита copywala была переименована. При ручном вызове необходимо использовать новое имя исполняемого файла – pangolin-copywala.

• Запрос создания резервной копии вручную
• Создание дельта-копий
• Создание резервной копии произвольной папки

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

подсказка

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

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

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

Предусловие

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

Важно

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

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

app:
 copywala_dir: /opt/pangolin-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

Работа в режиме 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-файлов помогает:

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

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

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

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	Использованный алгоритм сжатия

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

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

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

Создание дельта-копий

Дельта-резервная копия базы данных – это способ сохранять только те данные, которые были изменены с момента формирования предшествующей резервной копии. Реализация возможности создания дельта-копий является важной функцией, поскольку она способствует существенной экономии временных ресурсов при выполнении последующих операций копирования и снижает затраты дискового пространства при долгосрочном хранении архивов.

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

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

Запускается сканирование всех файлов базы данных, расположенных в каталоге PGDATA.

• Для файлов с постраничной структурой копируются только измененные страницы (проверка по LSN).
• Обычные файлы сохраняются полностью, если произошло любое изменение (проверка по дате последнего изменения файла); при этом дополнительно сохраняются метаданные.

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

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

Настройка ограничения очереди 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-файлов помогает:

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

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

Стратегия резервного копирования настраивается в конфигурационном файле copywala.yaml в разделе backup_policy параметром strategy.

Доступны 2 стратегии резервного копирования:

• снятие полной резервной копии: pbr.policy.backup.strategy.full
• снятие дельта-копии: pbr.policy.backup.strategy.delta

При включении стратегии снятия дельта-копий необходимо настроить количество создаваемых дельт между снятиями полных резервных копий. Данное поведение настраивается параметром delta_max_steps раздела backup_policy. По умолчанию снимается 3 дельта-копии.

backup_policy:
    strategy: pbr.policy.backup.strategy.delta # Включает режим дельта-копирования
    delta_max_steps: 3 # Максимальное число последовательных дельта-копий

Запуск РК выполняется стандартной командой: copywala create-backup.

Внимание!

При первом запуске создается полная РК, при последующих запусках создается дельта-копия пока не будет достигнуто максимальное количество delta_max_steps. Далее поведение повторится: будет создана полная РК и несколько дельта-копий.

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

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

Создание резервной копии произвольной папки

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

Сценарий предназначен для создания резервной копии произвольной директории.

Важно

Функциональность реализована только для резервных копий, которые сохранены в локальное хранилище.

Внимание!

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

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

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

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

• read_direct_io отвечает за чтение данных непосредственно с диска, минуя кеш операционной системы.
• read_cache_size определяет объем выделяемой памяти для внутреннего кеша чтения, его значение обязательно должно быть кратно 4 Кбайт на ОС Linux.
• write_direct_io отвечает за запись данных в архив в режиме прямого ввода-вывода.

Важно

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

backup_policy:

  read_direct_io: false
  read_cache_size: # используйте совместно с read_direct_io
  write_direct_io: false

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

Инициируйте создание резервной копии произвольной папки через CLI компонента Copywala командой copywala create-backup generic-folder <directory-path>.

Результат

После выполнения команды начнется процесс резервного копирования выбранной папки.

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

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

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