Утилита резервного копирования copywala

copywala - утилита командной строки для резервного копирования и восстановления данных PostgreSQL-совместимых БД.

Список консольных команд

Команды в разделе сгруппированы по их назначению:

• Служебные команды
• Создание резервной копии
• Восстановление данных из резервной копии
• Управление архивами резервных копий
• Работа с WAL-файлами
• Синхронизация узлов кластера БД

Подсказка

Для всех команд доступны флаги:

• -h|--help – показать справку по команде;
• -c|--config <path to copywala config> – по умолчанию используется /etc/pbr/copywala.yaml.

Для перехода к информации о команде нажмите на ее описание в таблице.

Служебные команды

Команда	Описание
copywala help	Справка по командам утилиты copywala
copywala version	Вывод версии установленной утилиты copywala
copywala init	Выполнение инициализации
copywala init keys	Запуск генерации пары криптографических ключей (приватного и публичного), необходимых для защитного преобразования учетных данных для подключения к хранилищам DDBoost
copywala init creds ddbost	Выполнение инициализации локального хранилища секретов c учетными данными необходимыми для подключения к хранилищам DDBoost
copywala init creds check	Выполняет проверку возможности чтения из локального хранилища секретов
copywala db init-repository	Инициализация репозитория для хранения служебной информации
copywala healthcheck	Проверка работоспособности утилиты Copywala
copywala healthcheck local-fs	Проверка подключения к локальному хранилищу
copywala healthcheck s2	Проверка подключения к хранилищу s2
copywala healthcheck s3	Проверка подключения к хранилищу s3
copywala healthcheck ddboost	Проверка подключения к хранилищу DDBoost
copywala config show	Вывод параметров конфигурационного файла copywala.yaml
copywala config set	Изменение конфигурационного файла утилиты Copywala
copywala db info	Вывод информации об экземпляре БД
copywala completion	Генерация скрипта для автодополнения команд утилиты copywala

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

Команда	Описание
copywala create-backup	Создание резервной копии в ручном режиме
copywala create-backup generic-folder <directory-path>	Создание резервной копии произвольной директории

Восстановление данных из резервной копии

Команда	Описание
copywala restore <archive uri or path>	Восстановление данных из резервной копии
copywala restore latest	Поиск и восстановление данных из последней резервной копии
copywala fuse <mount directory> <archive uri or path>	Восстановление кластера БД при помощи драйвера fuse

Управление архивами резервных копий

Команда	Описание
copywala cwl info <path to cwl archive>	Просмотр информации о CWL-архиве
copywala verify <path to cwl archive>	Валидация контрольных сумм файлов в CWL-архиве
copywala backups inventory	Инвентаризация резервных копий в указанных хранилищах
copywala backups history	Просмотр информации о созданных резервных копиях
copywala backups show	Просмотр параметров уже созданных резервных копий
copywala storage backups <instance-name>	Вывод списка резервных копий из хранилища
copywala backup-tasks show	Просмотр информации о задачах на создание РК
copywala retention backup set <archive uri>	Создание временной защиты резервной копии от удаления
copywala retention policy set	Настройка политики хранения для директории резервной копии согласно настройкам конфигурационного файла
copywala retention clean-outdated-backups	Удаление резервных копий, не соответствующих политике хранения
copywala retention policy show	Просмотр политик хранения
copywala storage instances <name-prefix>	Вывод списка с именами экземпляров баз данных, доступных в хранилище
copywala cwl extra-files list	Вывод списка всех дополнительных файлов, содержащихся в CWL-архиве
copywala cwl extra-files view	Просмотр содержимого указанного дополнительного файла из CWL-архива
copywala cwl extra-files extract	Извлечение дополнительного файла, входящего в состав CWL-архива

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

Команда	Описание
copywala archive-wal <WAL name> <path to WAL>	Архивация WAL-файла
copywala restore-wal <WAL name> <path to WAL>	Восстановление WAL-файла
copywala restore-wal prepare-multi-restore	Выполнение подготовки перед восстановлением WAL-файлов из нескольких хранилищ
copywala restore-wal disable-multi-restore	Отключение механизма multi-restore (восстановление WAL-файлов из нескольких хранилищ)
copywala wals show	Просмотр заархивированных WAL-файлов
copywala wals verify	Валидация заархивированных WAL-файлов
copywala archive-wal force-switch-cwl	Принудительное переключение CWL-архива
copywala unpack-wal	Распаковка WAL-файла

Синхронизация узлов кластера БД

Команда	Описание
copywala catchup receive	Запускает процесс получения и синхронизации данных с основного (primary) узла на узле-реплике. Команда выполняется на хосте реплики
copywala catchup send	Запускает процесс передачи данных с основного (primary) узла на реплику в соответствии с выбранной стратегией синхронизации. Команда выполняется на хосте primary-узла

Описание команд

copywala help

Описание:

Выводит справку по всем командам утилиты copywala или по определенной команде, если в параметрах указано имя команды.

Синтаксис:

copywala help [command] [flags]

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

Нет.

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

• [command] – имя команды, по которой необходимо получить справку.
• [flags] – доступны следующие флаги:

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

copywala version

Описание:

Выводит версию установленной утилиты copywala.

Синтаксис:

copywala version [flags]

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

Нет.

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

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

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

Сценарии использования:

Вывод версии Copywala.

copywala init

Описание:

Запускает процесс инициализации утилиты copywala.

Синтаксис:

copywala init <agent_name> [flags]

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

<agent_name> – уникальное имя агента.

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

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

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

Сценарии использования:

Инициализация приложения.

copywala init keys

Описание:

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

В результате выполнения будет сгенерирована пара ключей:

• приватный – /var/pbr/copywala/priv.key;
• публичный – /var/pbr/copywala/priv.key.pub.

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

Путь к приватному ключу настраивается в конфигурационном файле copywala.yaml параметром:

app:
  creds_private_key_path: /var/pbr/copywala/priv.key # значение по умолчанию

Публичный ключ с постфиксом .pub будет сохранен в той же директории, что и приватный.

Синтаксис:

copywala init keys [flags]

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

Нет.

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

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

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

Важно

При принудительной повторной генерации (--force) необходимо повторно инициализировать локальное хранилище copywala init creds также с флагом --force.

copywala init creds ddboost

Описание:

Выполнение инициализации локального хранилища секретов c учетными данными для подключения к хранилищам DDBoost. Выполнение команды возможно только после запуска copywala init keys, так как над файлом, который создается командой copywala init creds ddboost, выполняется защитное преобразование с использованием ранее сгенерированного приватного ключа.

В результате будет создан файл с учетными данными по пути, указанному в параметре ddboost.enc_creds_path конфигурационного файла copywala.yaml (пример значения):

ddboost:
  enc_creds_path: /var/pbr/copywala/ddboost.creds

Важно

Перед выполнением команды убедитесь, что параметр ddboost.enc_creds_path конфигурационного файла copywala.yaml заполнен.

Синтаксис:

copywala init creds ddboost [flags]

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

Нет.

В команде должны быть переданы учетные данные одним из способов:

• Передача через стандартный ввод. Пример:

      echo '{"username": "user_example", "password": "password_example"}' | copywala init creds ddboost

• Передача через файл с помощью флага --file:

      copywala init creds ddboost --file ddboost.creds.json

  Файл должен быть в формате JSON и обязательно содержать поля username и password:

  {
    "username": "<user_example>",
    "password": "<password_example>"
  }

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

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

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

copywala init creds check

Описание:

Запускает проверку возможности чтения из локального хранилища секретов. В результате выполнения команды отображается загруженное из хранилища имя пользователя.

Синтаксис:

copywala init creds check [flags]

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

Нет.

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

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

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

copywala db init-repository

Описание:

Запускает процесс инициализации репозитория для хранения служебной информации утилиты copywala.

Синтаксис:

copywala db init-repository [flags]

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

Нет.

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

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

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

Сценарии использования:

Инициализация репозитория для хранения служебной информации в БД.

copywala healthcheck

Описание:

Запускает проверку работоспособности утилиты Copywala.

Синтаксис:

copywala healthcheck [flags]

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

Нет.

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

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

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

Сценарии использования:

Работоспособность утилиты Copywala.

copywala healthcheck local-fs

Описание:

Команда выполняет проверку доступа к хранилищу Local FS (локальная или сетевая файловая система), путь к которому указан в конфигурационном файле copywala.yaml в параметрах backup_destination_uri и wal_destination_uri.

Синтаксис:

copywala healthcheck local-fs [flags]

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

Нет.

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

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

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

Сценарии использования:

Проверка подключения компонента Copywala к хранилищам резервных копий.

copywala healthcheck s2

Описание:

Команда выполняет проверку подключения к хранилищу S2, путь к которому указан в конфигурационном файле copywala.yaml в параметрах backup_destination_uri и wal_destination_uri.

Синтаксис:

copywala healthcheck s2 [flags]

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

Нет.

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

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

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

Сценарии использования:

Проверка подключения компонента Copywala к хранилищам резервных копий.

copywala healthcheck s3

Описание:

Команда выполняет проверку подключения к хранилищу S3, путь к которому указан в конфигурационном файле copywala.yaml в параметрах backup_destination_uri и wal_destination_uri.

Синтаксис:

copywala healthcheck s3 [flags]

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

Нет.

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

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

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

Сценарии использования:

Проверка подключения компонента Copywala к хранилищам резервных копий.

copywala healthcheck ddboost

Описание:

Команда выполняет проверку подключения к хранилищу DDBoost, путь к которому указан в конфигурационном файле copywala.yaml в параметре backup_destination_uri.

Синтаксис:

copywala healthcheck ddboost [flags]

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

Нет.

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

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

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

Сценарии использования:

Проверка подключения компонента Copywala к хранилищам резервных копий.

copywala config show

Описание:

Выводит параметры конфигурационного файла copywala.yaml, расположенного в /etc/pbr/copywala.yaml (если в параметрах команды явно не указан другой файл).

Синтаксис:

copywala config show [flags]

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

Нет.

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

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

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

Сценарии использования:

–

copywala config set

Описание:

Изменение значений параметров конфигурационного файла copywala.yaml. Если изменяемый параметр уже существует в copywala.yaml, его значение будет заменено на указанное в команде. Если параметр отсутствует, он будет добавлен в copywala.yaml с переданным значением.

Синтаксис:

copywala config set [flags]

Подсказка

В одной команде можно передавать сразу несколько флагов.

:caption: Пример вызова команды
copywala config set \
  --wal-destination-uri=s2://192.0.2.0:29509/storage/wals \
  --backup-destination-uri=s2://192.0.2.0:29509/storage/backups

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

Нет.

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
-n|--restore-instance-name <instance-name>	Изменение значения параметра restore_instance_name – уникальное имя экземпляра агента для восстановления
--wal-destination-uri <wal destination uri>	Изменение значения параметра wal_destination_uri – хранилище для WAL-файлов
--backup-destination-uri <backup destination uri>	Изменение значения параметра backup_destination_uri – хранилище для резервных копий
--fast-checkpoint	Изменение значения параметра backup_policy.fast_checkpoint – флаг для переключения типа контрольной точки, по умолчанию spread (протяженная), при включении запускает принудительное создание контрольной точки сразу при начале создания базовой РК
--read-direct-io	Изменение значения параметра backup_policy.read_direct_io – режим чтения данных из файлов, исключая использование кеша ОС
--write-direct-io	Изменение значения параметра backup_policy.write_direct_io – режим записи данных в файл без использования кеша ОС (актуально для локальных РК)
--verify-page-checksums	Изменение значения параметра backup_policy.verify_page_checksums – активация проверки контрольных сумм страниц во время исполнения РК
--workers-no <number of workers>	Изменение значения параметра backup_policy.workers_no – количество параллельных потоков, осуществляющих чтение из каталога PGDATA с диска (не включая WAL-файлы)
--write-parts-workers-no <number of workers>	Изменение значения параметра backup_policy.write_parts_workers_no – количество параллельных рабочих процессов (workers), выполняющих операцию записи отдельных партов
--write-wals-workers-no <number of workers>	Изменение значения параметра backup_policy.write_wals_workers_no – количество параллельных рабочих процессов (workers), выполняющих обработку WAL-файлов

История изменений хранилищ резервных копий и WAL-файлов

При изменении значений параметров wal_destination_uri или backup_destination_uri с помощью команды copywala config set дополнительно сохраняется история изменений в файлы, расположенные в директории ${PGDATA}/copywala_meta/:

Параметр	Файл истории
wal_destination_uri	${PGDATA}/copywala_meta/wal_destination_uri.history
backup_destination_uri	${PGDATA}/copywala_meta/backup_destination_uri.history

Формат файла истории — JSON-массив, где каждая запись содержит:

• uri – значение URI хранилища;
• mdf_at – временная метка изменения.

Пример содержимого файла wal_destination_uri.history:

[
  {
    "uri": "local-fs:///home/postgres/wals2",
    "mdf_at": "2026-07-03T13:25:45.972549307Z"
  },
  {
    "uri": "local-fs:///home/postgres/wals3",
    "mdf_at": "2026-07-03T13:26:56.736051656Z"
  },
  {
    "uri": "local-fs:///home/postgres/wals2",
    "mdf_at": "2026-07-08T09:47:04.979715669Z"
  }
]

Новая запись добавляется только если URI отличается от последнего записанного. Дубликаты не создаются.

Файлы истории сохраняются в директории ${PGDATA}/copywala_meta/, поэтому при резервном копировании они попадают в архив вместе со всеми файлами PGDATA и восстанавливаются при восстановлении из резервной копии, что обеспечивает непрерывность ведения истории.

copywala db info

Описание:

Выводит информацию об экземпляре базы данных, к которому подключена утилита copywala. По умолчанию информация выводится в YAML-формате (если в параметрах команды не указан флаг --json).

Синтаксис:

copywala db info [flags]

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

Нет.

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

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

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

Сценарии использования:

Вывод информации об экземпляре БД.

copywala completion

Описание:

Генерирует скрипт автодополнения команд утилиты copywala. Сгенерированный скрипт необходимо сохранить в файл и подключить его в конфигурации командной оболочки.

Синтаксис:

copywala completion <оболочка> [flags]

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

<оболочка> – укажите используемую командную оболочку:

• shell
• fish
• powershell
• zsh

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

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

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

Сценарии использования:

–

copywala create-backup

Описание:

Запуск создания резервной копии в ручном режиме.

Синтаксис:

copywala create-backup [flags]

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

Нет.

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

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

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

Сценарии использования:

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

copywala create-backup generic-folder

Описание:

Запуск создания резервной копии произвольной директории.

Ограничения

• Если выбранная для резервного копирования директория содержит символические ссылки, такие объекты будут проигнорированы и не будут включены в резервную копию. При восстановлении данных из резервной копии символические ссылки, существовавшие в исходной директории, не будут созданы.

  Если работа приложения или скриптов зависит от наличия символических ссылок, после восстановления потребуется их ручное воссоздание.

• Создание дельта-копий для операции copywala create-backup generic-folder не поддерживается. При каждом запуске резервного копирования создается полная копия выбранной директории, независимо от наличия предыдущих резервных копий.

Синтаксис:

copywala create-backup generic-folder <directory-path> [flags]

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

<directory-path> – директория для которой необходимо создать резервную копию.

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

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

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

Сценарии использования:

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

copywala restore

Описание:

Восстановление данных из резервной копии.

Синтаксис:

copywala restore <archive uri or path> [flags]

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

• <archive uri or path> – путь к CWL-архиву резервной копии из которой требуется восстановить данные.

• Если резервная копия содержит табличные пространства (tablespace), при вызове команды обязательно укажите один из флагов:

  Флаг	Описание
  -t|--tablespace-mapping </old-tablespace=/new-tablespace>	Задает соответствие между путями табличных пространств (tablespace) в резервной копии и их расположением на целевом сервере. Используется для восстановления табличных пространств в другое место. Для нескольких табличных пространств каждое соответствие пути исходного и целевого расположения рекомендуется указывать отдельным флагом -t|--tablespace-mapping. Пример значения: --tablespace-mapping="/pgdata/tablespaces/Tbl_t=/data/tbl_t"
  --allow-default-tablespaces	Использовать пути табличных пространств, сохраненных во время создания резервной копии. Имеет приоритет перед настройками, задаваемыми через флаг -t|--tablespace-mapping

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--allow-default-tablespaces	Использовать пути табличных пространств, сохраненных во время создания резервной копии. Имеет приоритет перед настройками, задаваемыми через флаг -t|--tablespace-mapping
--auto-create-tablespaces-dirs	Автоматически создает директории назначения для табличных пространств, переданных в флаге -t|--tablespace-mapping. Использование флага позволяет выполнять восстановление табличных пространств с изменением их расположения без предварительного ручного создания целевых каталогов.
--cpuprofile <path to file>	Включает сбор профиля использования CPU и сохраняет результаты в указанный файл (<path to file>) для последующего анализа производительности
-d|–destination <archive uri>	Директория, в которую необходимо произвести восстановление
--dry-run	Проверка корректности конфигурационного файла и возможности восстановления из заданной резервной копии
-t|--tablespace-mapping </old-tablespace=/new-tablespace>	Задает соответствие между путями табличных пространств (tablespace) в резервной копии и их расположением на целевом сервере. Используется для восстановления табличных пространств в другое место. Для нескольких табличных пространств каждое соответствие пути исходного и целевого расположения рекомендуется указывать отдельным флагом -t|--tablespace-mapping. Пример значения: --tablespace-mapping="/pgdata/tablespaces/Tbl_t=/data/tbl_t"

Сценарии использования:

• Восстановление данных из резервной копии.
• Восстановление данных из дельта-копии.

copywala restore latest

Описание: Поиск и восстановление данных из последней резервной копии.

Синтаксис:

copywala restore latest [flags]

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

Если резервная копия содержит табличные пространства (tablespace), при вызове команды обязательно укажите один из флагов:

Флаг	Описание
-t|--tablespace-mapping </old-tablespace=/new-tablespace>	Задает соответствие между путями табличных пространств (tablespace) в резервной копии и их расположением на целевом сервере. Используется для восстановления табличных пространств в другое место. Для нескольких табличных пространств каждое соответствие пути исходного и целевого расположения рекомендуется указывать отдельным флагом -t|--tablespace-mapping. Пример значения: --tablespace-mapping="/pgdata/tablespaces/Tbl_t=/data/tbl_t"
--allow-default-tablespaces	Использовать пути табличных пространств, сохраненных во время создания резервной копии. Имеет приоритет перед настройками, задаваемыми через флаг -t|--tablespace-mapping

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--allow-default-tablespaces	Использовать пути табличных пространств, сохраненных во время создания резервной копии. Имеет приоритет перед настройками, задаваемыми через флаг -t|--tablespace-mapping
--auto-create-tablespaces-dirs	Автоматически создает директории назначения для табличных пространств, переданных в флаге -t|--tablespace-mapping. Использование флага позволяет выполнять восстановление табличных пространств с изменением их расположения без предварительного ручного создания целевых каталогов.
-d|–-destination <archive uri>	Директория, в которую необходимо произвести восстановление
--dry-run	Проверка корректности конфигурационного файла и возможности восстановления из заданной резервной копии
-t|--tablespace-mapping </old-tablespace=/new-tablespace>	Задает соответствие между путями табличных пространств (tablespace) в резервной копии и их расположением на целевом сервере. Используется для восстановления табличных пространств в другое место. Для нескольких табличных пространств каждое соответствие пути исходного и целевого расположения рекомендуется указывать отдельным флагом -t|--tablespace-mapping. Пример значения: --tablespace-mapping="/pgdata/tablespaces/Tbl_t=/data/tbl_t"

Сценарии использования:

Поиск и восстановление данных из последней резервной копии.

copywala fuse

Описание:

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

Синтаксис:

copywala fuse <mount directory> <archive uri or path> [flags]

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

• <mount directory> – каталог, в который монтируется архив, и через который его содержимое становится доступным как файловая система.
• <archive uri or path> – путь к CWL-архиву резервной копии из которой требуется восстановить данные.

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--cache-dir <path/to/cache/dir>	Директория на диске, в которую переносятся данные из оперативной памяти при превышении значения cache-swap-size. Значение по умолчанию — /tmp.
--cache-swap-size	Размер данных, выгружаемых из архива CWL и хранимых в оперативной памяти. При превышении указанного объема данные, находящиеся в памяти, выгружаются на диск в директорию, указанную в параметре cache-dir. По окончании работы временные данные автоматически удаляются (по умолчанию – 256 МБ)

Сценарии использования:

• Восстановление кластера БД при помощи драйвера fuse.
• Гранулярное восстановление базы данных.

copywala cwl info

Описание:

Выводит информацию о CWL-архиве.

Синтаксис:

copywala cwl info <path to cwl archive> [flags]

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

<path to cwl archive> – путь к CWL-архиву резервной копии о котором необходимо посмотреть информацию.

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

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

Сценарии использования:

Просмотр информации о CWL-архиве.

copywala verify

Описание:

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

Синтаксис:

copywala verify  <path to cwl archive> [flags]

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

<path to cwl archive> – путь к CWL-архиву резервной копии для которого необходимо выполнить проверку.

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--max-allowed-failures <failures num>	Максимально допустимое количество ошибок при проверке, после превышения которого операция будет прервана. По умолчанию используется значение -1, это означает, что проверка выполняется полностью, без досрочного завершения независимо от числа ошибок

Сценарии использования:

Валидация контрольных сумм файлов и метаданных CWL-архива.

copywala backups inventory

Описание:

Выполняет проверку резервных копий путем сопоставления записей о них в служебной БД (задается в copywala.yaml в секции pbra_db) с фактически существующими архивами резервных копий в хранилищах. Проверка позволяет убедиться, что архивы присутствуют, доступны и готовы к использованию. По умолчанию (без указания флагов) проверка выполняется по всем хранилищам.

Проверка возможна в одном из режимов:

Режим	Что проверяется	Результат
Базовая проверка (без флага --detail)	наличие файла по указанному URI; доступность файла для чтения; корректность заголовка архива; контрольная сумма архива.	Если файл доступен и читается — статус устанавливается в success. Если файл не найден, не доступен или возникла ошибка чтения — статус устанавливается в failed.
Детальная проверка (c флагом --detail)	Все то же, что в базовой проверке + сравниваются метаданные из архива резервной копии с данными в служебной БД.	Если файл доступен, читается и метаданные совпадают — статус success. Если файл доступен, но метаданные не совпадают — статус failed с ошибкой "backup info mismatch". В выводе отображаются конкретные различия между полями. Если файл не найден или не читается — статус failed с соответствующей ошибкой.

Синтаксис:

copywala backups inventory [flags]

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

Нет.

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--detail	Выполнить инвентаризацию с детальной проверкой
--local	Проверка резервных копий, находящихся в хранилище Local FS (local-fs://)
--s2	Проверка резервных копий, находящихся в хранилище S2 (s2://)
--s3	Проверка резервных копий, находящихся в хранилище S3 (s3://)
--ddboost	Проверка резервных копий, находящихся в хранилище DDBoost (ddboost://)

примечание

Подробное описание типов хранилищ приведено в разделе Хранилища резервных копий.

Сценарии использования:

Инвентаризация резервных копий в указанных хранилищах.

copywala backups history

Описание:

Выводит информацию о созданных резервных копиях.

Синтаксис:

copywala backups history [flags]

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

Нет.

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

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

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

Сценарии использования:

Просмотр информации о созданных резервных копиях.

copywala backups show

Описание:

Выводит список созданных резервных копий с их основными параметрами.

Синтаксис:

copywala backups show [flags]

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

Нет.

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

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

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

Сценарии использования:

Просмотр информации о созданных резервных копиях.

copywala storage backups

Описание:

Выводит список существующих резервных копий текущего экземпляра или другого необходимого экземпляра.

Синтаксис:

copywala storage backups [instance-name] [flags]

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

Нет.

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

• [instance-name] – уникальное имя агента.

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

  Флаг	Описание
  -h|--help	Показать справку по команде
  -c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
  -u|--destination-uri <path to backups>	Путь до хранилища резервных копий. Если параметр не указан, используется значение из конфигурационного файла copywala.yaml параметр backup_destination_uri

Сценарии использования:

Вывод списка резервных копий из хранилища.

copywala backup-tasks show

Описание:

Выводит список задач на создание резервных копий.

Синтаксис:

copywala backup-tasks show [flags]

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

Нет.

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

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

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

Сценарии использования:

Просмотр информации о задачах на создание РК.

copywala retention backup set

Описание:

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

Синтаксис:

copywala retention backup set <archive uri> [flags]

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

<archive uri> – путь к CWL-архиву резервной копии из которой требуется восстановить данные.

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--retention-protection <protection time>	Временной интервал защиты резервной копии от удаления согласно политике хранения, например: 1d (1 день), 20h (20 часов). Для снятия защиты резервной копии и возможности ее удаления передайте флаг --retention-protection=0.

Сценарии использования:

Временная защита резервной копии от удаления.

copywala retention policy set

Описание:

Команда применяет политику хранения к директории резервных копий, определяя сроки хранения и условия удаления.

Политика хранения поддерживает два основных режима:

• Хранить фиксированное число полных резервных копий:

  Флаг: --max-full-backups=N, где N – число полных РК, которые необходимо хранить.

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

• Хранить резервные копии, позволяющие восстанавливать данные за установленное количество дней:

  Флаг: --retention-period=Kd, где K – количество дней, за которые необходимо обеспечить возможность восстановления данных.

  Применяется для обеспечения возможности полного восстановления на любой момент времени в пределах указанного периода. Все резервные копии, чьи поля завершения (finish_time) попадают в указанный интервал, остаются неприкосновенными, даже если начало (start_time) выходит за пределы окна. Если в указанное временное окно попадает дельта-копия, чья родительская РК (полная или дельта) не попала в это окно, родительская копия все равно остается защищенной от удаления.

Эти механизмы работают совместно: если политика ограничивает общее количество полных копий (max-full-backups), но некоторые из них входят в диапазон удерживаемых по критерию временных окон (retention-period), то приоритет отдается временной политике, и соответствующие копии останутся, даже если превышают лимит полных копий.

Например, если имеется три резервные копии, одна из которых входит в окно восстановления (retention-period), а максимальная разрешенная глубина хранения полных копий равна одной (max-full-backups=1), то сохранится лишь та копия, которая находится в временном интервале восстановления, а остальные две будут удалены.

Внимание!

Важно понимать:

1. Все резервные копии старше указанного числа дней (retention-period) автоматически удаляются.

2. Из оставшихся резервных копий сохраняется только указанное количество полных резервных копий (max-full-backups):

   • Если число полных резервных копий меньше либо равно количеству, указанному в max-full-backups, ничего удалено не будет.
   • Если полное количество резервных копий больше установленного ограничения (max-full-backups), полные РК (самые старые) будут удалены.

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

Синтаксис:

copywala retention policy set [flags]

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

Должен быть указан минимум один из флагов: --max-full-backups <number of backups> или --retention-period <d (days)/ h (hours)/ s (seconds)>.

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--max-full-backups <number of backups>	Задает количество полных резервных копий, сохраняемых в рамках политики хранения. Все связанные с ними дельта-копии также будут сохранены
--retention-period <d (days)/ h (hours)/ s (seconds)>	Задает временной интервал хранения, в течение которого будут храниться резервные копии

Сценарии использования:

Настройка политики хранения.

copywala retention clean-outdated-backups

Описание:

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

Синтаксис:

copywala retention clean-outdated-backups [flags]

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

Нет.

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

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

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

Сценарии использования:

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

copywala retention policy show

Описание:

Выводит список политик хранения резервных копий в виде таблицы.

Синтаксис:

copywala retention policy show [flags]

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

Нет.

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

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

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

Сценарии использования:

Просмотр политик хранения.

copywala storage instances

Описание:

Выводит список с именами экземпляров баз данных, для которых имеются резервные копии в хранилище.

Синтаксис:

copywala storage instances <name-prefix> [flags]

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

Нет.

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

• <name-prefix> – префикс имени экземпляра, используемый для фильтрации списка: выводятся только те экземпляры, имена которых начинаются с указанного значения.
• [flags] – доступны следующие флаги:

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

Сценарии использования:

Вывод списка с именами экземпляров баз данных, доступных в хранилище.

copywala cwl extra-files list

Описание:

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

Синтаксис:

copywala cwl extra-files list <path to cwl archive> [flags]

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

<path to cwl archive> – путь к CWL-архиву резервной копии.

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

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

Сценарии использования:

Просмотр дополнительных файлов, находящихся в резервной копии.

copywala cwl extra-files view

Описание:

Позволяет просмотреть содержимое указанного дополнительного файла из CWL-архива резервной копии.

Синтаксис:

copywala cwl extra-files view <path to cwl archive> --file <original path> [flags]

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

Флаг / Параметр	Описание
<path to cwl archive>	Путь к CWL-архиву резервной копии
-f|--file <original path>	Исходный путь к файлу в архиве (такой, как он был указан при создании резервной копии в параметре extra_files файла copywala.yaml)

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

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

Сценарии использования:

Просмотр дополнительных файлов, находящихся в резервной копии.

copywala cwl extra-files extract

Описание:

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

Синтаксис:

copywala cwl extra-files extract <path to cwl archive> --file <original path>=<new path>  [flags]

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

Флаг / Параметр	Описание
<path to cwl archive>	Путь к CWL-архиву резервной копии
-f|--file <original path>=<new path>	Пара «исходный путь = новый путь», задающая соответствие файла из архива пути в целевой директории. Для извлечения нескольких файлов укажите несколько флагов -f|--file

примечание

Если в команде используется URI, указывающий подключение к DDBoost через S2, его необходимо обязательно заключать в двойные кавычки.

Это требование связано с тем, что URI содержит символ &, который интерпретируется Bash как оператор фонового запуска команды.

Ниже приведен пример для команды copywala cwl info:

copywala cwl info "s2://<s2-host>/<ddboost-storage-unit>/path/in/ddboost/storage/unit?driver=ddboost&data_domain_host=<ddboost-host>"

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

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

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

Сценарии использования:

Извлечение дополнительных файлов из резервной копии.

copywala archive-wal

Описание:

Используется в archive_command (postgresql.conf) и выполняет передачу WAL-файлов из локальной директории базы данных в удаленное хранилище.

Синтаксис:

copywala archive-wal %f %p [flags]

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

%f — имя WAL-файла, который нужно заархивировать. %p — полный путь в файловой системе к WAL-файлу, который нужно заархивировать.

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

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

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

Сценарии использования:

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

copywala restore-wal

Описание:

Используется в restore_command (postgresql.conf) и выполняет восстановление WAL-файлов из удаленного хранилища.

Синтаксис:

copywala restore-wal %f %p [flags]

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

• %f — имя WAL-файла, который нужно восстановить.
• %p — путь в файловой системе, куда WAL-файл должен быть восстановлен.

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

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

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

Сценарии использования:

Восстановление WAL-файлов.

copywala restore-wal prepare-multi-restore

Описание:

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

• сохраняет список URI хранилищ в параметре wal_restore.multi_restore_wal_uris конфигурационного файла copywala.yaml;

• формирует кеш-файл multi_restore.wals.cache, в котором хранится информация о соответствии WAL-файлов и хранилищ, где они находятся. Кеш-файл используется при последующих вызовах restore_command для поиска необходимого WAL-файла.

  Расположение кеш-файла задается параметром wal_restore.multi_restore_cache_path в copywala.yaml. Если параметр не указан, файл создается в каталоге /var/pbr/copywala/.

Синтаксис:

copywala restore-wal prepare-multi-restore [flags]

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

Флаг	Описание
--uri <wal destination uri>	URI хранилища WAL-файлов. Может быть указан несколько раз

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

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

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

Сценарии использования:

Восстановление WAL-файлов из нескольких хранилищ.

copywala restore-wal disable-multi-restore

Описание:

Команда выполняет удаление кеш-файла и «сбрасывает» значение параметра multi_restore_wal_uris в copywala.yaml.

Синтаксис:

copywala restore-wal disable-multi-restore [flags]

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

Нет.

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

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

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

Сценарии использования:

Восстановление WAL-файлов из нескольких хранилищ.

copywala wals show

Описание:

Отображает информацию об архивированных WAL-файлах в виде временной шкалы с возможностью фильтрации по диапазону LSN, времени или именам WAL-файлов.

Синтаксис:

copywala wals show [flags]

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

Если в целевой БД используются WAL-файлы нестандартного размера (не 16 МБ), а в конфигурационном файле copywala.yaml не задан параметр wal_segment_size, то при выполнении команды copywala wals show обязательно укажите флаг --auto-wal-segment-size.

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

подсказка

Чтобы в дальнейшем не использовать флаг --auto-wal-segment-size:

1. Вызовите copywala wals verify --auto-wal-segment-size.

2. В результате вывода определите размер WAL-файла. Пример вывода:

   2026-01-22 13:13:41 [756] INF auto detected WAL segment size: 32MiB

3. Укажите данное значение в конфигурационном файле copywala.yaml для параметра wal_segment_size.

В дальнейшем, при вызове copywala wals verify, указание флага --auto-wal-segment-size не требуется.

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--auto-wal-segment-size	Автоматическое определение размера WAL-файла на основе последнего заархивированного файла
--filter-max-lsn <max LSN value>	Максимальное значение LSN для фильтрации WAL-файлов (по умолчанию – FFFFFFFF/FFFFFFFF)
--filter-min-lsn <min LSN value>	Минимальное значение LSN для фильтрации WAL-файлов (по умолчанию – 0/0)
--filter-max-time <max time>	Конечное время для фильтрации WAL-файлов (по умолчанию – текущее время)
--filter-min-time <min time>	Начальное время для фильтрации WAL-файлов (по умолчанию – 1970-01-01T03:00:00+03:00)
--filter-max-wal <wal name>	Имя WAL-файла, до которого будет выполняться фильтрация
--filter-min-wal <wal name>	Имя WAL-файла, начиная с которого будет выполняться фильтрация

Сценарии использования:

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

copywala wals verify

Описание:

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

Синтаксис:

copywala wals verify [flags]

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

Если в целевой БД используются WAL-файлы нестандартного размера (не 16 МБ), а в конфигурационном файле copywala.yaml не задан параметр wal_segment_size, то при выполнении команды copywala wals verify обязательно укажите флаг --auto-wal-segment-size.

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

подсказка

Чтобы в дальнейшем не использовать флаг --auto-wal-segment-size:

1. Вызовите copywala wals verify --auto-wal-segment-size.

2. В результате вывода определите размер WAL-файла. Пример вывода:

   2026-01-22 13:13:41 [756] INF auto detected WAL segment size: 32MiB

3. Укажите данное значение в конфигурационном файле copywala.yaml для параметра wal_segment_size.

В дальнейшем, при вызове copywala wals verify, указание флага --auto-wal-segment-size не требуется.

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--auto-wal-segment-size	Автоматическое определение размера WAL-файла на основе последнего заархивированного файла
--filter-max-lsn <max LSN value>	Максимальное значение LSN для фильтрации WAL-файлов (по умолчанию – FFFFFFFF/FFFFFFFF)
--filter-min-lsn <min LSN value>	Минимальное значение LSN для фильтрации WAL-файлов (по умолчанию – 0/0)
--filter-max-time <max time>	Конечное время для фильтрации WAL-файлов (по умолчанию – текущее время)
--filter-min-time <min time>	Начальное время для фильтрации WAL-файлов (по умолчанию – 1970-01-01T03:00:00+03:00)
--filter-max-wal <wal name>	Имя WAL-файла, до которого будет выполняться фильтрация
--filter-min-wal <wal name>	Имя WAL-файла, начиная с которого будет выполняться фильтрация
--integrity	Анализ WAL-файлов с выводом их общего количества, количества невалидных сегментов и информации о возможных пропусках и проблемах с валидностью WAL-сегментов. Не проверяет контрольные суммы WAL-файлов
--integrity-full	Анализ WAL-файлов аналогичный как при использовании флага --integrity, но дополнительно включая проверку контрольных сумм
--timeline	Проверка корректности текущей временной линии
--clean-cache	Очистка текущего кеша перед выполнением проверки. Флаг работает только вместе с флагом --integrity-full и используется совместно с --use-cache
--use-cache	Включение использования кеша при проверке целостности WAL-файлов (по умолчанию кеширование выключено). Флаг работает только вместе с флагом --integrity-full. Использования кеша позволяет пропустить уже проверенные WAL-файлы и ускорить выполнение команды.

примечание

Если флаги --integrity и --timeline не указаны при запуске, по умолчанию выполняются обе проверки.

Сценарии использования:

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

copywala archive-wal force-switch-cwl

Описание:

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

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

Синтаксис:

copywala archive-wal force-switch-cwl [flags]

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

Нет.

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

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

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

Сценарии использования:

Архивация WAL-файлов, Механизм принудительного переключения CWL-архива

copywala unpack-wal

Описание:

Распаковывает WAL-файл, который был сжат при архивировании.

Синтаксис:

copywala unpack-wal <path to wal file> [flags]

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

<path to wal file> – путь к WAL-файлу.

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

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

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

copywala catchup receive

Описание:

Запускает процесс получения и синхронизации данных с основного (primary) узла на узле-реплике. Команда выполняется на хосте реплики.

Синтаксис:

copywala catchup receive [flags]

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

Флаг	Описание
--datadir <path_to_pgdata>	Путь к директории данных (PGDATA) на узле-реплике
--connstring <string>	Строка подключения к основному серверу БД. Пример: host=master-host port=5432 user=postgres dbname=postgres
--role <role>	Роль текущего сервера. Укажите значение replica

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

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

Флаг	Описание
-h|--help	Показать справку по команде
-c|--config <path to copywala config>	Использовать конфигурационный файл, отличный от файла по умолчанию: /etc/pbr/copywala.yaml
--scope	Имя кластера на котором будет запускаться команда
-s|--start_master_runner	Автоматически запускать отправку данных с основного узла с помощью расширения pgcopywala (вызов copywala catchup send в таком случае происходит автоматически, а не в ручную). При использовании данного флага убедитесь, что на primary-узле установлено расширение pgcopywala

Сценарии использования:

Catchup: синхронизация реплики с основным узлом.

copywala catchup send

Описание:

Команда используется для передачи данных с основного сервера (primary) на реплику. Она применяется при создании новых реплик, а также при восстановлении существующих, если данные на реплике устарели и требуют синхронизации с основным сервером. Команду необходимо выполнять на основном узле.

Синтаксис:

copywala catchup send <replica_addresses> [flags]

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

<replica_addresses> – список адресов реплик в формате host:port, разделенных запятой, на которые будут отправляться данные с основного сервера.

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

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

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

Сценарии использования:

Catchup: синхронизация реплики с основным узлом.