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

Архивация WAL-файлов

примечание

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

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

Процесс архивирования WAL-файла, инициируемый СУБД.

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

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

  1. Настройте в конфигурационном файле copywala.yaml параметр wal_destination_uri для архивирования WAL-файлов в выбранное хранилище.
  2. Включите архивирование WAL-файлов в настройках БД (postgresql.conf) путем установки значений archive_mode=on и archive_command='copywala archive-wal %f %p'.

Результат​

  • При создании нового WAL-файла СУБД запустит команду, указанную в archive_command, и архивирует WAL-файлы в заданное хранилище (вывод статистики и поддержка многопоточного режима не активированы):

    2025-09-02 12:51:45.341 INF 00000001000000760000007D: wal archived

  • При активации флага --stat выводится отдельная строка с дополнительной информацией (поддержка многопоточного режима не активирована):

    2025-09-02 12:51:45.891 INF 00000001000000760000007D: wal archived
    2025-09-02 17:51:48.763 INF wal archiving stats storage=local-fs:///home/postgres/backups/adf_019a24a3-90e5-7c33-b067-56b3f601fff2/wals archived_wals=1 workers=1 time_elapsed=15.739542ms time_compress=15.739042ms time_upload=250ns total_bytes=50331648 upload_bytes=1800 compress_ratio=27962.0 compress_algorithm=S2

  • При активации многопоточного режима архивации и передаче опции --stat команде архивирования archive_command='copywala archive-wal %f %p --stat':

    2025-10-28 12:14:36.742 INF wal archiving stats storage=local-fs:///home/postgres/backups/adf_019a24a3-90e5-7c33-b067-56b3f601fff2/wals archived_wals=12 workers=4 time_elapsed=365.250797ms time_compress=365.242233ms time_upload=3.508µs total_bytes=201326592 upload_bytes=21729907 compress_ratio=9.3 compress_algorithm=S2 batch_size=100 from=0000000100000008000000EB to=0000000100000008000000F6
Примечание

Если в качестве хранилища используется локальное хранилище (wal_destination_uri: local-fs://...), то процесс архивации выполняется следующим образом:

  1. По указанному пути создается поддиректория .archiving.
  2. Запись WAL-файла осуществляется в данную поддиректорию.
  3. После завершения записи файла он перемещается в целевую директорию, указанную в wal_destination_uri в настройках copywala.yaml.

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

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

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

  • Закончилось место на диске.
  • Отсутствие прав на запись в хранилище.
  • Неверно настроенная конфигурация.

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

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

Поддержка многопоточного режима архивации WAL-файлов​

Активация параметра is_multi_wal_archiving_enabled в разделе wal_archiving в конфигурации copywala включает поддержку многопоточного режима архивации WAL-файлов при вызове команды copywala archive-wal.

Алгоритм работы:

  1. Команда copywala archive-wal вызывает механизм сканирования директории WAL-файлов.
  2. Система проверяет наличие готовых к архивации WAL-файлов в директории pg_wal/archive_status путем анализа их статуса.
  3. WAL-файлы передаются параллельно в удаленное хранилище, используя настраиваемое число рабочих потоков (количество потоков регулируется параметром multi_wal_archiving_workers_no в разделе wal_archiving).

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

Обзор статистики архивированных WAL-сегментов​

Для включения вывода статистики добавьте флаг --stat в команду архивирования: archive_command='copywala archive-wal %f %p --stat'. Статистика отобразит следующие метрики по итогам архивирования WAL-сегментов:

  • хранилище (storage);
  • количество заархивированных WAL-файлов (archived_wals);
  • число используемых потоков (workers);
  • общий объем WAL-файлов (total_bytes);
  • общее количество байтов, отправленных в хранилище (upload_bytes);
  • общее время архивирования всех WAL-файлов (time_elapsed);
  • общее время сжатия всех WAL-файлов (time_compress);
  • общее время передачи данных в хранилище (time_upload);
  • степень сжатия данных (compress_ratio);
  • используемый алгоритм сжатия (compress_algorithm);
  • первый заархивированный WAL-файл (from). Метрика применяется при включении многопоточного режима архивации;
  • последний заархивированный WAL-файл (to). Метрика применяется при и включении многопоточного режима архивации.
примечание

При активации многопоточного режима архивации и передаче опции --stat команде архивирования archive_command='copywala archive-wal %f %p --stat' введена дополнительная статистика с информацией о диапазоне заархивированных WAL-файлов (from — первый файл, to — последний).

Пример настроек

  • copywala.yaml:

    wal_archiving:
      is_multi_wal_archiving_enabled: true

  • postgresql.conf:

    archive_command=copywala archive-wal %f %p --stat

Архивирование WAL-файлов в CWL-архив​

Важно

Архивирование WAL-файлов в CWL-архив возможно только при использовании хранилища Local FS: в copywala.yaml задан wal_destination_uri: local-fs://....

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

Параметр

Описание

Значение по умолчанию

is_wal_archiving_in_cwl_enabled

Флаг включения архивации WAL-файлов в CWL-архив:

  • true – WAL-файлы собираются в CWL-архив в хранилище wal_destination_uri.
  • false – каждый WAL-файл сохраняется как отдельный файл в wal_destination_uri.

> При использовании wal_destination_uri: local-fs://... WAL-файлы и CWL-архивы сначала попадают в .archiving, а после завершения записи перемещаются в целевую директорию. Данный механизм позволяет исключить обработку WAL-файлов и CWL-архивов, находящихся в процессе формирования. Формирование CWL-архива завершается в случаях: > - достижения архивом размера, заданном в значении параметра wal_archiving_cwl_max_file_size > - принудительного переключения.

false

wal_archiving_cwl_max_file_size

Максимальный размер CWL-архива с WAL-сегментами, при достижении которого формирование текущего CWL-архива завершается и создается новый. Данный параметр используется только при is_wal_archiving_in_cwl_enabled: true.

> Также возможно принудительно завершить формирование текущего CWL-архива.

1GB

Примечание

Итоговый размер CWL-архива может превышать значение параметраwal_archiving_cwl_max_file_size. Это связано с тем, что проверка размера архива выполняется после выполнения команды copywala archive-wal, и если лимит не достигнут, запись WAL-файлов продолжается в тот же архив. Поскольку размер поступающих WAL-файлов заранее неизвестен, суммарный объем данных, записанных в CWL-архив до его завершения, может превысить заданное ограничение.

Механизм принудительного переключения CWL-архива​

Механизм принудительного переключения CWL-архива позволяет досрочно завершить текущий архив (до достижения им размера wal_archiving_cwl_max_file_size) и начать формирование нового.

После переключения:

  1. Текущий CWL-архив закрывается.
  2. Перемещается в целевую директорию.
  3. Становится доступным для внешних систем резервного копирования (СРК).

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

Важно

Механизм возможно использовать только при включенной архивации WAL-файлов в CWL-архив и использовании локального хранилища:

  • is_wal_archiving_in_cwl_enabled: true
  • wal_destination_uri: local-fs://...

Переключение CWL-архива осуществляется командой:

$ copywala archive-wal force-switch-cwl

Алгоритм переключения после ввода команды:

  1. Проверяется, не выполняется ли параллельно архивация WAL-файла в текущий CWL-архив. Проверка выполняется по наличию блокировки на Lock-файле <wal_destination_uri>/.archiving/wals.cwl.lock и продолжается в течение тайм-аута, заданного в параметре force_switch_cwl_lock_timeout (конфигурационный файл copywala.yaml раздел wal_archiving). По умолчанию – 15s (15 секунд).

  2. Во время ожидания разблокировки Lock-файла команда каждые 1/5 тайм-аута выводит предупреждение в лог, например:

    2026-03-27 15:00:18.261 [3555762] WRN waiting for unlock: /wals/.archiving/wals.cwl.lock
    2026-03-27 15:00:21.461 [3555762] WRN waiting for unlock: /wals/.archiving/wals.cwl.lock
    2026-03-27 15:00:24.662 [3555762] WRN waiting for unlock: /wals/.archiving/wals.cwl.lock
    2026-03-27 15:00:27.862 [3555762] WRN waiting for unlock: /wals/.archiving/wals.cwl.lock

  3. По истечению тайм-аута:

    • Если блокировка не была снята – переключение на новый CWL-файл не произойдет. В логе появится сообщение об ошибке:

      2026-03-27 15:00:30.062 [3555762] ERR timeout of waiting for unlock: /wals/.archiving/wals.cwl.lock

    • Если блокировка снята успешно, команда copywala archive-wal force-switch-cwl завершится успешно, в логе будут записи о завершении текущего CWL-файла и продолжении архивации:

      2026-03-27 15:08:33.055.132 [3557350] INF completed current CWL archive wals file cwl=/dest/db_<id>/wals/<wal_segment_range>.cwl
      2026-03-27 15:08:33.255 [3557350] INF wals archivation will be continued to new CWL file

Настройка логирования при архивации WAL-файлов​

Настройка логирования при архивации WAL-файлов определяется параметром is_archive_logs_to_file_only. Он задается в конфигурационном файле copywala.yaml в секции wal_archiving и может принимать следующие значения:

  • true — сообщения уровня INFO при архивации WAL-файлов записываются только в файл логов Copywala.
  • false (значение по умолчанию) — сообщения уровня INFO одновременно записываются в файл логов Copywala и в стандартный поток ошибок (stderr).