Утилита резервного копирования CopyWala
copywala — утилита командной строки для резервного копирования и восстановления данных Postgres-like совместимых БД.
Сведения
В текущей версии утилитаcopywala была переименована. При ручном вызове необходимо использовать новое имя исполняемого файла – pangolin-copywala.
Список консольных команд
Просмотр списка консольных команд
примечание
Для всех команд доступны опциональные флаги -h|--help, -c|--config путь к файлу конфигурации (по умолчанию используется copywala.yaml).
copywala db init-repository
copywala init <name>
copywala create-backup
copywala create-backup generic-folder <directory-path>
copywala restore <путь к файлу РК>
Опциональные флаги:
[-d|–destination | директория, в которую необходимо производить восстановление]
[-t|--tablespace-mapping | соответствие между предыдущим и новым местоположением табличного пространства]
[--allow-default-tablespaces | использовать пути табличных пространств, сохраненных во время создания РК]
[--dry-run | проверка возможности восстановления из заданной резервной копии]
copywala restore latest
Опциональные флаги:
[-d|–destination | директория, в которую нужно производить восстановление]
[-t|--tablespace-mapping | соответствие между предыдущим и новым местоположением табличного пространства]
[--allow-default-tablespaces | использовать пути табличных пространств, сохраненных при создании РК]
[--dry-run | проверка возможности восстановления из заданной резервной копии]
copywala backups inventory
Опциональные флаги:
[--local | локальное хранилище]
[--s2 | хранилище s2]
[--s3 | хранилище s3]
[--detail | детальный вывод]
copywala retention policy show
copywala retention policy set
Опциональные флаги:
[--max-full-backups | максимальное количество РК]
[--retention-period | максимальный интервал]
copywala retention backup set <archive uri>
Опциональный флаг:
[--retention-protection | временной интервал защиты РК от удаления]
copywala retention clean-outdated-backups
copywala healthcheck
copywala config show
copywala fuse <mount-directory> <archive-uri-or-path>
Опциональные флаги:
[--cache-swap-size | размер кеша подкачки]
[--cache-dir | путь к директории с выгружаемым кешем]
copywala cwl info <путь к файлу РК>
copywala verify <путь к файлу РК>
copywala archive-wal <название WAL-файла> <путь к WAL-файлу>
copywala restore-wal <название WAL-файла> <путь к WAL-файлу>
copywala storage backups <instance_name>
copywala storage instances <name_prefix>
copywala wals show
copywala wals verify
Опциональные флаги:
[--integrity | анализ WAL-сегментов, вывод их количества и отображение информации о возможных пропусках*]
[--timeline | проверка текущей временной линии*]
[--clean-cache | сброс текущего кеша]
[--use-cache | применяется для использования кеша при --integrity проверке (по умолчанию кеширование выключено)]
copywala backup-tasks show
Опциональный флаг:
[--detail | вывод детальной информации о задаче РК]
copywala backups history
Опциональный флаг:
[--detail | вывод детальной информации о РК]
copywala backups show
copywala completion [bash|zsh|...]
copywala version
Обзор возможностей
Возможность | Описание |
|---|---|
Создание полной резервной копии | Операция включает в себя сохранение всех элементов базы данных, файлов, индексов, конфигураций и настроек, что позволяет восстановить всю систему целиком в первоначальном состоянии в случае возникновения технических проблем, сбоев или утраты данных |
Создание дельта-копии | Метод, при котором сохраняются только те данные, которые изменились с момента предыдущего резервного копирования любого типа (полного или дельта), что позволяет существенно сократить затраты дискового пространства и ускорить процесс резервирования и восстановления |
Восстановление экземпляра базы данных из резервной копии | Восстановление выполняется из полной резервной копии или последовательного набора дельта-копий, что позволяет вернуть состояние базы данных на нужный момент времени, восстанавливая как саму структуру данных, так и внесенные изменения вплоть до последнего известного состояния перед потерей данных |
Высокогранулярное восстановление | Возможность восстановления отдельных баз данных, включая восстановление конкретных объектов с использованием технологии fuse |
Гибкие политики резервного копирования | Настройка правил создания резервных копий с учетом требований к частоте и расписанию |
Эффективное использование ресурсов | Сжатие и дедупликация на источнике оптимизируют исходящий трафик и использование CPU сервера СУБД |
Контроль целостности | Процедура проверки целостности резервной копии, инициируемая по требованию |
Просмотр списка резервных копий БД | Формирование перечня имеющихся резервных копий вместе с метаинформацией |
Параллельное выполнение | Одновременная обработка внутренних операций команд несколькими параллельными потоками |
Поддержка S3-совместимых хранилищ для записи и чтения РК и WAL-сегментов | Технология гарантирует высокий уровень доступности, устойчивости к сбоям и производительности, обеспечивая управление ресурсами хранения независимо от аппаратной инфраструктуры организации. За счет поддержки стандарта S3 API открывается доступ к разнообразным сервисам облачного хранения от множества поставщиков услуг |
Сведения
Для ведения и администрирования централизованного каталога резервных копий продуктом Platform V CopyWala используйте CopyWala из поставкипродукта Platform V CopyWala.
Установка и настройка
Утилита copywala поставляется в виде rpm/deb-пакета в рамках дистрибутива продукта СУБД Pangolin.
Ручная установка
-
Выполните установку компонента
Copywala:- SberLinux, РЕД ОС, CentOS
- Astra Linux
- Альт СП
sudo dnf install pangolin-copywala-{version_component}-{OS}.x86_64.rpmsudo apt install pangolin-copywala-{version_component}-{OS}.x86_64.debsudo apt-get install pangolin-copywala-{version_component}-{OS}.x86_64.rpmПример заполненной команды:
sudo yum install pangolin-copywala-1.1.0-altlinux10.x86_64.rpm
Настройте пользователя backup_user:
-
Если пользователь существует, выдайте ему следующие разрешения:
-- Разрешить наследование ролей (для работы pg_read_all_settings)
ALTER USER backup_user WITH INHERIT;
-- Предоставить доступ к чтению системных настроек
GRANT pg_read_all_settings TO backup_user;
-- Предоставить права на чтение системных представлений и функций, используемых для диагностики и наблюдения за работой сервера
GRANT pg_monitor TO backup_user; -
Если пользователя не существует, создайте его:
CREATE ROLE backup_user WITH PASSWORD '<пароль>';
ALTER ROLE backup_user WITH
NOSUPERUSER
INHERIT
NOCREATEROLE
NOCREATEDB
LOGIN
REPLICATION
NOBYPASSRLS;Предоставьте ему следующие разрешения:
BEGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_start(text, boolean) TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_stop(boolean) TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup_user;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup_user;
GRANT pg_read_all_settings TO backup_user;
GRANT pg_monitor TO backup_user;
COMMIT;
Проверьте наличие записей в файле pg_hba.conf для подключения пользователя backup_user:
host postgres backup_user 127.0.0.1/32 scram-sha-256
host replication backup_user 127.0.0.1/32 scram-sha-256
Создайте схему для хранения метаданных в резервных копиях:
CREATE SCHEMA pbr AUTHORIZATION backup_user;
-
Заполните параметры в конфигурационном файле
/etc/pangolin-copywala/copywala.yaml:Пример заполненных параметров
# --------------------------------------
# Настройка подключения к целевой БД
# --------------------------------------
target_db:
host: localhost
port: 5433
user: username
password: password
database: postgres
# опция получения секретов подключения к БД через утилиту pg_auth_config
is_pg_auth_config_enabled: false # параметр позволяет применять аутентификацию пользователей при помощи pg_auth_config # если значение выставлено true, то в данном разделе параметр password указывать не нужно
pg_auth_config_plugins_path: /usr/lib/pbr/copywala # путь к каталогу, содержащему плагины аутентификации
query_params: search_path=pbr # параметр позволяет настроить набор значений, специфичных для Pangolin/PostgreSQL, при подключении к базе данных
# по умолчанию применяется глобальный tls
tls:
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Возможность загрузки TLS-сертификатов из защищенного хранилища секретов
# --------------------------------------
vault: # настройки подключения
server: <vault-url>
namespace: <namespace>
path: <mount-path> # путь к точке монтирования хранилища секретов
kv_version: v2 # версия формата хранилища ключей-значений
approle:
role_id: <role-id> # уникальный идентификатор роли
secret_id: <secret-id> # секретный ключ роли. Либо указывается явно, либо прописывается wrapping_secret_id_file_path
auth_method: approle # метод аутентификации
wrapping_secret_id_file_path: /var/pbr/cw.wrapped.secret.vlt # путь к файлу для хранения wrapping token
wrapping_secret_id_ttl: 8h # время жизни wrapping token (например, 10m - 10 минут, 6h - 6 часов)
# --------------------------------------
# Настройки БД для хранения информации о выполненных задачах резервного копирования и восстановления данных
# --------------------------------------
pbra_db:
host: localhost
port: 5433
user: username
password: password
database: postgres
is_pg_auth_config_enabled: false # параметр позволяет применять аутентификацию пользователей при помощи pg_auth_config # если значение выставлено true, то в данном разделе параметр password указывать не нужно
query_params: search_path=pbr # параметр позволяет настроить набор значений, специфичных для Pangolin/PostgreSQL, при подключении к базе данных
tls:
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Назначение резервной копии (обязательный параметр без restore_data_path)
# --------------------------------------
# local-fs:///home/postgres/backups/
# s3://srv-10-20.host/bucket-08-9992
# s2://srv-10-25.host:port
backup_destination_uri: local-fs:///home/postgres/backups/
# --------------------------------------
# Назначение директории для архивирования WAL-файлов
# --------------------------------------
# local-fs:///home/postgres/backups/wals/
# s3://srv-10-20.host/wals-bucket/
wal_destination_uri: local-fs:///home/postgres/backups/wals/
# --------------------------------------
# Директория для восстановления данных (обязательный параметр без backup_destination_uri)
# --------------------------------------
restore_data_path: local-fs:///pgdata/data/data
# --------------------------------------
# Наименование экземпляра БД для восстановления
# --------------------------------------
restore_instance_name: NAME_UUID # пример: db1_0198ad69-1a19-7b7f-9f46-f200942fd61c
# --------------------------------------
# Настройка повторных попыток при возникновении ошибок при записи РК
# --------------------------------------
retrier:
timeout: 10s # максимальное время выполнения запроса
retries: 5 # максимальное количество попыток
delay_period: 1s # период задержки
# --------------------------------------
# Размер WAL-файла (опционально, по умолчанию 16777216 (16MB))
# --------------------------------------
wal_segment_size: 16MB
# --------------------------------------
# Конфигурация S3
# --------------------------------------
s3:
region: ru-test # регион s3
access_id: <id> # идентификатор пользователя
secret_key: <key> # секретный ключ
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Конфигурация S2
# --------------------------------------
s2:
storage_path: "" # значение по умолчанию пустое. Задается пользователем для возможности выбора одного из дополнительных хранилищ, пример: /var/pbr/s2/backups
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Настройки архивирования РК
# --------------------------------------
archive_settings:
upload_params:
part_payload_size: 32MB # размер части передаваемых данных
checksum_algorithm: CRC32 # выбор алгоритма вычисления контрольной суммы. CRC32 – значение по умолчанию. Допустимые значения: DISABLED, CRC32, SHA256
compression_algorithm: S2 # выбор алгоритма сжатия данных при создании РК. S2 – значение по умолчанию. Допустимые значения: DISABLED, ZSTD, S2
# --------------------------------------
# Политика исполнения резервного копирования
# --------------------------------------
backup_policy:
strategy: pbr.policy.backup.strategy.full # выбор стратегии резервного копирования. Также доступно – pbr.policy.backup.strategy.delta
fast_checkpoint: false # флаг для переключения типа контрольной точки, по умолчанию spread (протяженная), при включении запускает принудительное создание контрольной точки сразу при начале создания базовой РК
workers_no: 2 # количество параллельных потоков, которые бэкап выполняет одновременно
progress_latency: 0.025 # шаг в долях от размера бэкапа, на котором сообщается прогресс
read_direct_io: false # режим чтения данных из файлов, исключая использование кеша ОС
write_direct_io: false # режим записи данных в файл без использования кеша ОС (актуально для локальных РК)
read_cache_size: # значение параметра должно быть кратно 4 КБ на Linux # используйте совместно с read_direct_io для РК произвольной папки (generic folder backup)
delta_max_steps: 3 # допустимое отставание реплики от главного узла при восстановлении, измеряемое количеством пропущенных шагов репликации
write_parts_workers_no: 1 # количество параллельных рабочих процессов (workers), выполняющих операцию записи отдельных частей
verify_page_checksums: false # активация проверки контрольных сумм страниц во время исполнения РК
max_allowed_page_verification_failures: 0 # максимальное количество ошибок при проверке целостности страниц во время исполнения РК
# --------------------------------------
# Конфигурация архивирования WAL-файлов
# --------------------------------------
wal_archiving:
is_multi_wal_archiving_enabled: false # многопоточный режим архивации WAL-файлов
multi_wal_archiving_workers_no: 4 # количество потоков для параллельной передачи WAL-файлов в хранилище
wal_batch_size: 100 # 100 по умолчанию. Чтобы отключить ограничение размера пакета, установите значение равным 0 или любому отрицательному целому числ
# Archive WALs in CWL
is_wal_archiving_in_cwl_enabled: false # включение/отключение архивации журналов предзаписи WAL в CWL
wal_archiving_cwl_max_file_size: 1GB # максимальный размер CWL-архива с WAL-сегментами
wal_compression_algorithm: S2 # алгоритм сжатия WAL-файлов. S2 – значение по умолчанию. Допустимые значения: DISABLED, ZSTD, S2, LZ4
# --------------------------------------
# Политика восстановления (ниже приведены значения по умолчанию)
# --------------------------------------
restore_policy:
workers_no: runtime.NumCPU()
reverse_restore: false # порядок восстановления резервных копий данных. При true – восстановление производится в обратном порядке, при false – восстановление идет последовательно
verify_page_checksums: false # активация проверки контрольных сумм страниц во время восстановления
max_allowed_page_verification_failures: 0 # максимальное количество ошибок при проверке целостности страниц во время восстановления
verify_archive_checksums: true # проверка контрольных сумм всего архива
jobs_queue_size: 16 # размер очереди задач на распаковку частей архива
progress_latency: 0.1 # шаг в долях от размера бэкапа, на котором сообщается прогресс (0.1 - каждые 10%)
read_direct_io: false # режим чтения данных из файлов, исключая использование кеша ОС
write_direct_io: false # режим записи данных в файлы, исключая использование кеша ОС (не доступно для generic folder backups)
# --------------------------------------
# Конфигурация TLS используемая по умолчанию для всех сетевых соединений (DB, S2, S3, ...)
# --------------------------------------
tls:
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Конфигурация Prometheus (подробное описание атрибутов по умолчанию и обязательных атрибутов каждого поля подробнее смотрите в документации)
# --------------------------------------
prometheus:
push_model:
jobname: <jobname>
address: <address>
process_collector_opts:
report_errors: true
pid: 0 # по умолчанию PID текущего процесса
namespace: <namespace>
frequency: 10s
req_timeout: 8s
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
pull_model:
endpoint: /metrics
address: <address>
process_collector_opts:
report_errors: true
pid: 0 # по умолчанию PID текущего процесса
namespace: <namespace>
handler_opts:
timeout: 8s
max_requests_in_flight: 0 # количество запросов не ограничено
disable_compression: false
log_errors: true
tls: # опционально
rootca:
local_path: tls/root.crt # путь к локальному файлу
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
cert:
local_path: tls/cert.crt
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
key:
local_path: tls/cert.key
# vault_path: <path> # путь к секрету в HashiCorp/SecMan
# vault_key: <key> # ключ внутри json-секрета
# --------------------------------------
# Опциональные настройки приложения
# --------------------------------------
app:
agent_id_file_path: /etc/pangolin-copywala/pbr.agent.id # путь к файлу, содержащему идентификатор агентского приложения
copywala_dir: /opt/pangoilin-copywala # рабочая директория
allow_concurrent_create_backup: false # управляет возможностью запуска нескольких операций создания резервных копий одновременно
# --------------------------------------
# Настройка ведения журналов приложения
# --------------------------------------
log:
path: /opt/pangolin-copywala/pangolin-copywala.log # путь к лог-файлу
max_size: 100 # максимальный размер лог-файла в мегабайтах. По умолчанию `100 МБ`
max_age: 90 # максимальный возраст лог-файла в днях
max_backups: 10 # максимальное количество резервных копий лог-файлов, которые будут храниться. Если выбрано 0, то количество файлов не ограничено
use_local_time: true # параметр определяет, в каком формате будут записываться метки времени в имена файлов при ротации. Если выбрано true, используется локальное системное время, при false (и по умолчанию) – UTС
compress_backups: false # параметр определяет необходимость сжатия файлов. Если выбрано true, лог-файлы будут сжаты, если false, лог-файлы будут храниться без сжатия
Инициализируйте экземпляр CopyWala командой copywala init <name>.
Где <name> – имя агента (agent_name), используемое для автоматического формирования уникального имени экземпляра агента (instance_name).
Настройте в конфигурационном файле copywala.yaml значение backup_destination_uri для указания места назначения резервных копий:
backup_destination_uri: /home/postgres/backups
Проверка работоспособности
Убедитесь в успешности установки и настройки, выполнив команду copywala healthcheck.
Работоспособность сервиса Copywala
Описание сценария
Проверка пользователем работоспособности сервиса Copywala.
Последовательность выполнения
Инициируйте проверку работоспособности Copywala через CLI компонента Copywala командой copywala healthcheck.
Результат
В результате выполнения команды будет выведено сообщение, которое отобразит статус работоспособности компонента Copywala:
$ copywala healthcheck
Config [OK]
Logging [OK]
Target DB [OK]
PBRA DB [OK]
________________________________________
Overall System [OK]
Исключительный сценарий
-
Если одна из проверок не пройдет, то вместо
OKбудет выведеноFAILED:$ copywala healthcheck
Config [OK]
Logging [OK]
Target DB [FAILED]
2025-03-26 15:53:35.418 ERR Target DB err="cannot parse `postgres://postgres:xxxxxx@local host:15432/?application_name=copywala`: failed to parse as URL (invalid character \" \" in host name)"
PBRA DB [OK]
________________________________________
Overall System [FAILED]
Error: copywala healthcheck failed -
В случае неудачной проверки конфигурационного файла (например, отсутствуют необходимые параметры или неверно указаны), будет выведено:
$ copywala healthcheck --config .local/bad-config.yaml
Config [FAILED]
Error: open .local/bad-config.yaml: no such file or directory
Сценарии использования
Сведения
При выполнении приведенных сценариев использования утилиты необходимо учитывать изменение в вызове утилиты:copywala → pangolin-copywala.