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

Работа с WAL-файлами

Сведения

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

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

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

Процесс архивирования 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-архив используются следующие параметры (конфигурационный файл 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-файла, инициируемый СУБД.

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

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

  1. Задайте в конфигурационном файле copywala.yaml значения для параметров:

    • wal_destination_uri – путь к хранилищу для архивированных WAL-файлов.
    • restore_instance_name – наименование экземпляра БД для восстановления (соответствует уникальному имени экземпляра агента — instance_name, полученному при инициализации приложения).

  2. Установите значение в настройках БД (postgresql.conf) restore_command='copywala restore-wal %f %p'.

Результат​

При восстановлении СУБД запросит WAL-файл (или *.history), выполняя команду, указанную в restore_command:

2025-08-28 14:58:03.981 INF 00000001000000030000002A: wal restored pg_wal/XLOGRECORD storage=s2 time_elapsed=114.872333ms

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

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

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

Просмотр заархивированных WAL-файлов​

подсказка

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

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

Просмотр информации о заархивированных WAL-файлах

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

  1. Настройте в конфигурационном файле copywala.yaml параметр wal_destination_uri для архивирования WAL-файлов в заданное хранилище. При использовании нестандартного размера WAL-сегментов настройте параметр wal_segment_size. По умолчанию данный параметр равен 16777216 - 16 МБ.
  2. Выполните команду: copywala wals show [--auto-wal-segment-size].
Флаг --auto-wal-segment-size

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

2025-12-22 14:05:42.114 [2373695] INF auto detected WAL segment size: 16777216

Результат​

В результате выполнения команды выведется таблица с временными линиями и информацией о WAL-файлах в них. Пример выходных данных:

$ copywala wals show
+-----+------------+-----------------+--------------------------+--------------------------+---------------+----------------+--------+
| TLI | PARENT TLI | SWITCHPOINT LSN | START SEGMENT            | END SEGMENT              | SEGMENT RANGE | SEGMENTS COUNT | STATUS |
+-----+------------+-----------------+--------------------------+--------------------------+---------------+----------------+--------+
|   1 |          0 | 0/0             | 0000000100000018000000DF | 000000010000001900000026 |            72 |             72 | OK     |
|   2 |          1 | 18/E2000E60     | 0000000200000018000000E2 | 000000020000001D00000004 |          1059 |           1059 | OK     |
+-----+------------+-----------------+--------------------------+--------------------------+---------------+----------------+--------+

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

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

  • В хранилище для данной БД нет WAL-файлов:

    2025-12-02 13:59:51.571 ERR wals show failed err="auto detect wal file size failed: no wals found in storage"

  • Отсутствие прав на просмотр хранилища:

    ERR wals verify failed err="request wal files from local storage: open /backups/db0_019a02c3-6783-7e22-805d-925a2df93937/wals: permission denied"

  • Неверно настроенная конфигурация:

    ERR init config err="config file parsing error: uri: \"test:///backups\" | provided schema is not supported"

Валидация заархивированных WAL-файлов​

подсказка

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

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

Валидация заархивированных WAL-файлов

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

  1. Настройте в конфигурационном файле copywala.yaml параметр wal_destination_uri для архивирования WAL-файлов в заданное хранилище. При использовании нестандартного размера WAL-сегментов настройте параметр wal_segment_size. По умолчанию данный параметр равен 16777216 байт (16 МБ).
  2. Выполните команду: copywala wals verify [--timeline] [--integrity] [--use-cache] [--clean-cache] [--auto-wal-segment-size].
Доступные флаги

  • --timeline проверяет корректность текущей временной линии, в то время как --integrity анализирует WAL-сегменты: выводит их общее количество, показывает количество невалидных сегментов и отображает информацию о возможных пропусках и проблемах с валидностью WAL-сегментов. Оба флага можно запускать как вместе, так и отдельно.
  • --use-cache применяется для использования кеша при --integrity проверке (по умолчанию кеширование выключено), в то время как --clean-cache позволяет сбросить текущий кеш и, при использовании кеша, заново обработать или вычислить данные, хранящиеся в кеше.
  • --auto-wal-segment-size используется для автоматического определения размера сегмента WAL-файла на основе размера первого WAL-файла, находящегося в хранилище. Чтобы понять, какой размер WAL-файла определился автоматически, обратите внимание на следующую строку (значение в байтах):
2025-12-22 14:05:42.914 [2373695] INF auto detected WAL segment size: 16 MB

Результат​

В результате выполнения команды будет выведена информация по заданным проверкам. Пример выходных данных:

$ copywala wals verify --integrity --timeline

[verify] integrity check status: OK
[verify] integrity check details:
+-----+--------------------------+--------------------------+----------------+--------+
| TLI | START                    | END                      | SEGMENTS COUNT | STATUS |
+-----+--------------------------+--------------------------+----------------+--------+
|   1 | 0000000100000018000000DF | 0000000100000018000000E1 |              3 |  FOUND |
|   2 | 0000000200000018000000E2 | 000000020000001D00000004 |           1059 |  FOUND |
+-----+--------------------------+--------------------------+----------------+--------+
[verify] timeline check status: OK
[verify] timeline check details:
Highest timeline found in storage: 2
Current cluster timeline: 2

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

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

  • При запуске команды copywala wals verify размер WAL-сегментов сверяется с текущим размером сегмента в БД, в случае отличия будет выведено сообщение:

    ERR wals verify failed err="segment size from db are not equal to auto detected from first wal file: 16777216 != 35651584"

  • В хранилище для данной БД нет WAL-файлов:

    ERR wals verify failed err="auto detect wal file size failed: no wals found in storage"

  • Отсутствие прав на просмотр хранилища:

    ERR wals verify failed err="request wal files from local storage: open /backups/db0_019a02c3-6783-7e22-805d-925a2df93937/wals: permission denied"

  • Неверно настроенная конфигурация:

    ERR init config err="config file parsing error: uri: \"test:///backups\" | provided schema is not supported"