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

Отложенная доставка WAL-файлов в удаленное хранилище

примечание

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

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

Ограничения​

Режим отложенной доставки несовместим с архивацией WAL-файлов в CWL-архив. Параметр is_wal_archiving_in_cwl_enabled в copywala.yaml должен быть равен false (или не задан).

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

  1. Задайте параметры отложенной доставки в файле copywala.yaml в секции wal_archiving:

Параметр

Описание

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

force_local

Флаг включения режима локального накопления WAL-файлов:

  • true — WAL-файлы сохраняются в локальную директорию, указанную в wal_local_destination_uri
  • false — WAL-файлы архивируются напрямую в wal_destination_uri

false

wal_local_destination_uri

URI локальной директории для накопления WAL-файлов. Поддерживается только схема local-fs:///...

Не задано

upload_wals_workers_no

Количество параллельных рабочих процессов для выгрузки WAL-файлов в удаленное хранилище

4

upload_wals_batch_size

Количество WAL-файлов (пачка), выгружаемая за одну итерацию

100

Установите force_local: true, укажите путь к локальной директории в wal_local_destination_uri и при необходимости переопределите заданные по умолчанию значения для параметров upload_wals_workers_no и upload_wals_batch_size.

Пример заполненных параметров

wal_archiving:
  force_local: true
  wal_local_destination_uri: local-fs:///pgarclogs/copywala
  upload_wals_workers_no: 4
  upload_wals_batch_size: 100

  1. Включите архивирование WAL-файлов в настройках СУБД в файле postgresql.conf задав параметры:

    archive_mode = on
    archive_command = 'copywala archive-wal %f %p'

    При архивировании каждый WAL-файл сохраняется в локальную директорию wal_local_destination_uri с суффиксом .upload-ready.

    Важно

    При просмотре (copywala wals show) и валидации (copywala wals verify) заархивированных WAL-файлов учитываются только те файлы, которые расположены в wal_destination_uri. WAL-файлы из wal_local_destination_uri команды не учитывают.

  2. Выполните команду copywala archive-wal upload-wals для выгрузки накопленных WAL-файлов в удаленное хранилище (ознакомьтесь со справкой по команде ниже).

    Справка по команде copywala archive-wal upload-wals

    Описание:

    Выгружает накопленные локально WAL-файлы (с суффиксом .upload-ready) в удаленное хранилище, указанное в параметре wal_destination_uri конфигурационного файла copywala.yaml.

    Алгоритм работы команды

    1. После запуска команды устанавливается блокировка на файл /var/pbr/copywala/upload-wals.lock вызовом flock для защиты от параллельных запусков (путь к каталогу настраивается параметром app.copywala_dir в copywala.yaml). Если процесс выгрузки уже запущен, будет выведено сообщение об ошибке:

      ERR can't run upload-wals: another process seems to already perform uploading

    2. Считываются и фильтруются по суффиксу .upload-ready файлы из wal_local_destination_uri.

    3. Определяется пачка WAL-файлов размером upload_wals_batch_size (по умолчанию 100) запускается upload_wals_workers_no (по умолчанию 4) рабочих потоков для параллельной выгрузки в хранилище wal_destination_uri.

    4. После загрузки каждый локальный WAL-файл удаляется.

    5. Выполняется повтор шагов c - d, пока все WAL-файлы не будут выгружены.

    примечание

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

    Синтаксис:

        
    copywala archive-wal upload-wals [flags]

    Обязательные параметры:

    Нет.

    Опциональные параметры:

    [flags] – доступны следующие флаги:

    ФлагОписание
    -h|--helpПоказать справку по команде
    -c|--config <path to copywala config>Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
    --statВключает вывод статистики прогресса выгрузки WAL-файлов

    ```output title="Пример вывода команды с флагом --stat"

    $ copywala archive-wal upload-wals --stat

    ... 2026-09-04 17:52:50.550 [1938242] INF wal uploading stats app=copywala cmd=upload-wals batch=1/13 storage="s2://203.0.113.44:29509?ssl=true" uploaded_wals=10 workers=4 batch_size=10 time_elapsed=345.448592ms time_upload=225.891278ms total_bytes=23309335 upload_bytes=23309335 from=000000010000000000000028 to=000000010000000000000031 2026-09-04 17:52:50.551 [1938242] INF 000000010000000000000032: wal archived app=copywala cmd=upload-wals ... 2026-09-04 17:52:50.562 [1938242] INF wal uploading stats app=copywala cmd=upload-wals batch=2/13 storage="s2://203.0.113.44:29509?ssl=true" uploaded_wals=10 workers=4 batch_size=10 time_elapsed=38.952596ms time_upload=32.232684ms total_bytes=1246684 upload_bytes=1246684 from=000000010000000000000032 to=00000001000000000000003B 2026-09-04 17:52:50.563 [1938242] INF 00000001000000000000003F: wal archived app=copywala cmd=upload-wals ... 2026-09-04 17:52:51.160 [1938242] INF upload locally accumulated wals completed app=copywala cmd=upload-wals



Описание параметров прогресса выгрузки

Поле

Описание

batch

Номер текущей пачки (N) и общее количество пачек (M) WAL-файлов в формате N/M

storage

URI целевого хранилища, в которое выгружаются WAL-файлы

uploaded_wals

Количество WAL-файлов, выгруженных в текущей пачке

workers

Количество параллельных рабочих потоков

batch_size

Размер пачки (настраивается параметром upload_wals_batch_size в copywala.yaml)

time_elapsed

Общее время обработки пачки

time_upload

Время, затраченное на передачу данных в хранилище

total_bytes

Общий размер выгружаемых WAL-файлов в байтах

upload_bytes

Количество байт, переданных в хранилище

from

Имя первого WAL-файла в пачке

to

Имя последнего WAL-файла в пачке

::::

Способы запуска выгрузки

Команда может быть запущена вручную, внешней СРК, по расписанию через cron или таймеры systemd.

Результат​

После выполнения команды copywala archive-wal upload-wals WAL-файлы выгружаются в удаленное хранилище без суффикса .upload-ready, а локальные копии с суффиксом удаляются:

Пример вывода команды
$ copywala archive-wal upload-wals

2026-09-04 17:52:50.441 [1938242] INF uploading wals app=copywala cmd=upload-wals workers_no=4 batch_size=10 local_uri=local-fs:///pgarclogs/copywala/test-1.2.3.host_019ff09d-de79-7e7f-8e30-68d2e7404c16/wals upload_uri="s2://203.0.113.44:29509?ssl=true"
2026-09-04 17:52:50.466 [1938242] INF 000000010000000000000028: wal archived app=copywala cmd=upload-wals
...
2026-09-04 17:52:51.160 [1938242] INF upload locally accumulated wals completed app=copywala cmd=upload-wals

примечание

При включенном многопоточном режиме архивации (is_multi_wal_archiving_enabled: true) информация об архивации отдельных WAL-файлов (<wal_name>: wal archived...) в лог не выводится.

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

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

  • Параллельный процесс выгрузки уже запущен:

    ERR can't run upload-wals: another process seems to already perform uploading

  • Параметр wal_local_destination_uri не задан:

    ERR config param 'wal_archiving.wal_local_destination_uri' is empty but required

  • Включена архивация WAL-файлов в CWL-архив (несовместимо с отложенной доставкой):

    ERR uploading wals collected in CWL is not supported: config param 'is_wal_archiving_in_cwl_enabled' must be disabled

  • Недостаточно места на диске для накопления WAL-файлов.

  • Отсутствие прав на запись в локальную директорию wal_local_destination_uri.

  • Отсутствие прав на запись в удаленное хранилище wal_destination_uri.