Создание дельта-копий

Дельта-копия — это резервная копия, которая создается при инкрементальном копировании и содержит только те данные, которые изменились с момента последней резервной копии (полной или дельта-копии). Использование дельта-копий позволяет экономить дисковое пространство при хранении архивов и сократить время резервного копирования по сравнению с полным копированием.

В CopyWala создание дельта-копий возможно в одной из стратегий:

Стратегия	Описание
delta	Инкрементальное копирование на уровне файлов: для файлов с постраничной структурой копируются только измененные страницы (по LSN), а обычные файлы сохраняются полностью при любом изменении
ptrack	Инкрементальное копирование на уровне отдельных страниц данных (блоков по 8 КБ) с использованием расширения PostgreSQL / Platform V Pangolin DB ptrack. Обеспечивает более высокую скорость копирования по сравнению со стратегией delta. В стратегии ptrack файлы с не страничной структурой копируются полностью при каждом запуске резервного копирования

Стратегия delta

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

Запускается сканирование всех файлов базы данных, расположенных в каталоге PGDATA.

• Для файлов с постраничной структурой копируются только измененные страницы. Для этого используется LSN — Log Sequence Number, последовательный номер в журнале. При создании РК фиксируется LSN первой страницы каждого файла. На следующем этапе копируются только те страницы, у которых текущий LSN превышает зафиксированный в предыдущем бэкапе.
• Обычные файлы сохраняются полностью, если произошло любое изменение. Проверка выполняется по дате изменения и размеру. При этом дополнительно сохраняются метаданные.

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

примечание

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

1. Включите стратегию delta, для этого в конфигурационном файле copywala.yaml в секции backup_policy для параметра strategy задайте значение pbr.policy.backup.strategy.delta:

   backup_policy:
       strategy: pbr.policy.backup.strategy.delta

2. Настройте количество дельта-копий, которые будут создаваться между полными резервными копиями. Для этого используйте параметр delta_max_steps в разделе backup_policy. Параметр определяет максимальное количество последовательных дельта-копий перед созданием следующей полной резервной копии:

   backup_policy:
       delta_max_steps: 3

   примечание

   Если параметр delta_max_steps не задан в copywala.yaml, используется значение по умолчанию — 3 дельта-копии.

3. Запустите снятие резервной копии командой copywala create-backup.

Результат

• При первом запуске создается полная резервная копия.

• При последующих запусках создается дельта-копия пока не будет достигнуто максимальное количество delta_max_steps.

  Формат имени дельта-копии

  :name: backup-name-explanation

  Имя дельта-копии формируется по шаблону:

  <timestamp>_<backup_uuid>_delta_<end_lsn>_from_<start_lsn>.cwl

  где:

  • <timestamp> — дата и время создания резервной копии в формате YYYY-MM-DD-HH-MM;
  • <backup_uuid> — уникальный идентификатор резервной копии;
  • delta — тип резервной копии (резервная копия delta);
  • <end_lsn> — конечный LSN (Log Sequence Number), до которого включены изменения в резервную копию;
  • <start_lsn> — начальный LSN, начиная с которого были накоплены изменения относительно предыдущей резервной копии;
  • .cwl — расширение файла резервной копии.

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

  Пример содержимого директории резервных копий

  Пример показывает содержимое директории резервных копий при delta_max_steps = 3.

  $ ls backups/test_06_07_019f3625-4480-77d8-ad10-f2980111eeb8/backups/
  
  2026-07-06-09-54_019f3635-3f6f-71c5-b6b1-98d8533c67b0_full_00000001000000000000001A.cwl
  2026-07-06-10-00_019f363a-c170-7ce9-8c0d-af2e9f94c9ee_delta_00000001000000000000001D_from_00000001000000000000001A.cwl
  2026-07-06-10-04_019f363e-527c-71db-ac8c-81410eff9dc3_delta_00000001000000000000001F_from_00000001000000000000001D.cwl
  2026-07-06-10-05_019f363f-3555-79ea-b5d4-4db50e163218_delta_000000010000000000000021_from_00000001000000000000001F.cwl
  2026-07-06-10-06_019f363f-fdc1-7438-a84b-8f768f308d93_full_000000010000000000000023.cwl

  где test_06_07_019f3625-4480-77d8-ad10-f2980111eeb8 – полное уникальное наименование экземпляра агента instance_name.

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

• Не удалось установить подключение к целевой базе данных.
• Закончилось место на диске.
• Возникла ошибка при создании слота репликации.

Стратегия ptrack

Стратегия ptrack использует расширение PostgreSQL / Platform V Pangolin DB ptrack для создания инкрементальных резервных копий на уровне отдельных страниц данных (блоков по 8 КБ). В этой стратегии файлы с не страничной структурой копируются полностью при каждом запуске резервного копирования.

Важно

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

Причина связана с особенностями работы ptrack. При создании резервной копии ptrack формирует карту измененных страниц (ptrack map), а copywala копирует в архив только страницы, указанные в этой карте.

После формирования ptrack map в файле может продолжаться изменение данных. Эти изменения не отражены в карте, поэтому в архив они не попадают.

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

При проверке целостности архива, созданного в стратегии ptrack, вывод команды copywala verify будет соответствовать выводу успешной проверки:

:caption: Пример вывода

2026-07-15 11:22:32.727 [441056] INF copywala 1.3.x (e1a4e632) compiled at 2026-07-08_14:24:14
2026-07-15 11:22:33.177 [441056] INF finished reading parts package=cwl
2026-07-15 11:22:33.177 [441056] INF Verification succeeded without errors

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

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

   SELECT extnamespace::regnamespace, extversion FROM pg_catalog.pg_extension WHERE extname = 'ptrack'::name;

2. Если расширение включено, производится поиск последней полной резервной копии, из которой извлекается LSN, зафиксированный на момент ее создания.

3. Данный LSN сравнивается с LSN из запроса:

   SELECT ptrack_schema.ptrack_init_lsn();

   Если LSN ptrack меньше или равен LSN из полной копии, возможно корректное создание резервной копии с ptrack. В противном случае автоматически создается полная резервная копия.

4. После проверки выполняется pg_start_backup и запрашивается список файлов с битовой картой измененных страниц:

   SELECT path, pagemap FROM ptrack_schema.ptrack_get_pagemapset(lsn);

   где lsn — LSN из последней полной резервной копии.

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

6. Копируются оставшиеся служебные файлы (конфигурации, WAL-журналы и так далее) и выполняется pg_stop_backup.

Предварительные условия

Убедитесь, что в PostgreSQL / Platform V Pangolin DB включено расширение ptrack не ниже версии 2.4. Для этого используйте команду CREATE EXTENSION IF NOT EXISTS ptrack SCHEMA ptrack_schema;. Она проверит наличие расширения и установит его, если оно еще не активировано.

Внимание!

После начала использования ptrack для резервного копирования нельзя изменять его настройки в PostgreSQL / Platform V Pangolin DB, так как это приведет к удалению файла с данными об измененных страницах и, как следствие, созданию неконсистентной резервной копии. Подробнее про расширение ptrack читайте в документации Platform V Pangolin, в разделе «ptrack. Инкрементальное резервное копирование» документа «Описание расширений продукта СУБД Pangolin».

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

примечание

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

1. Включите стратегию ptrack, для этого в конфигурационном файле copywala.yaml в секции backup_policy для параметра strategy задайте значение pbr.policy.backup.strategy.ptrack:

   backup_policy:
       strategy: pbr.policy.backup.strategy.ptrack

2. Настройте количество дельта-копий, которые будут создаваться между полными резервными копиями. Для этого используйте параметр delta_max_steps в разделе backup_policy:

   backup_policy:
       delta_max_steps: 3

   примечание

   Если параметр delta_max_steps не задан в copywala.yaml, используется значение по умолчанию — 3 инкрементальные копии.

3. Запустите снятие резервной копии командой copywala create-backup.

Результат

• При первом запуске или при отсутствии предыдущих копий создается полная резервная копия. Также полная копия будет создана, если LSN ptrack больше LSN из полной копии.

• При последующих запусках создается ptrack-копия, содержащая только измененные страницы, пока не будет достигнуто максимальное количество delta_max_steps.

  Формат имени ptrack-копии

  Формат имени аналогичен {ref}дельта-копии <backup-name-explanation>, за исключением типа копии: после уникального идентификатора указывается ptrack вместо delta:

  <timestamp>_<backup_uuid>_ptrack_<end_lsn>_from_<start_lsn>.cwl

• После создания максимального количества ptrack-копий следующий запуск выполняет создание полной резервной копии, после чего цикл повторяется.

• В случае недоступности ptrack или неактуальности карты страниц автоматически создается полная резервная копия.

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

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

• Расширение ptrack не установлено или отключено.
• Карта отслеживания изменений страниц (ptrack map) не является актуальной для создания ptrack-копии.
• Не удалось установить подключение к целевой БД.
• Закончилось место на диске.
• Возникла ошибка при создании слота репликации.

Предупреждение ptrack map is not relevant, fallback to full backup

При запуске резервного копирования со стратегией ptrack может появиться предупреждение:

ptrack map is not relevant, fallback to full backup

Причины появления предупреждения

1. Размер битовой карты расширения ptrack не соответствует размерам кластера (ptrack.map_size)

   Параметр ptrack.map_size в postgresql.conf определяет размер битовой карты. Для больших баз данных значение по умолчанию может быть недостаточно, что приводит к «переполнению» карты и потере информации об измененных страницах.

   Например, для базы данных объемом ~520 ГБ значение ptrack.map_size = 300 (по умолчанию) может оказаться недостаточным. В этом случае функция ptrack_is_map_relevant() возвращает false, и предупреждение появляется в логах.

   Решение: Увеличьте ptrack.map_size в postgresql.conf до значения, равного N/1024, где N — объем кластера PostgreSQL / Platform V Pangolin DB в мегабайтах.

2. Установка расширения ptrack после создания полной резервной копии

   Если полная резервная копия была создана до активации расширения ptrack, а затем расширение было установлено, карта измененных страниц начинается с текущего LSN (логического номера последовательности). В этом случае LSN инициализации ptrack (ptrack_init_lsn()) оказывается позже LSN полной копии, и карта не покрывает изменения, накопленные с момента создания полной копии.

   Решение: После установки расширения ptrack создайте новую полную резервную копию вручную. Следующие запуски будут корректно использовать инкрементальное копирование с ptrack.

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

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

Настройка ограничения очереди WAL-файлов (при потоковой репликации)

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

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

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

backup_policy:
  max_pending_wals: -1

max_pending_wals определяет режим работы очереди WAL-файлов (включение/отключение) и задает их максимальное допустимое количество, которое может одновременно находиться в обработке. В это значение входят как WAL-файлы, находящиеся в очереди, так и WAL-файлы, которые уже обрабатываются воркерами. Например, при max_pending_wals=14 и write_wals_workers_no=4 в очереди может быть только 10 файлов, так как 4 будут в обработке у воркеров.

Возможные значения параметра max_pending_wals

Значение	Описание
-1 (задано по умолчанию)	Очередь включена без ограничения размера. Внимание! Использование данного значения может привести к переполнению диска, который используется как временное хранилище перед записью WAL-файлов в резервную копию.
0	Очередь отключена: поступающие WAL-файлы немедленно передаются воркерам для обработки. При отсутствии доступных воркеров прием WAL-файлов приостанавливается до их освобождения. Если ожидание превышает значение wal_sender_timeout (настройки БД файл postgresql.conf), то: резервное копирование прерывается с ошибкой. Текст ошибки (отформатирован для упрощения восприятия) 2026-04-08 18:43:54.587 [993659] ERR app: run: copywala err= "saving wals: process replication messages: process next message: acknowledge replication message: receive message from pangolin server: receive message failed: unexpected EOF" архив с незавершенной РК удаляется.
любое целое число > 0	При достижении или превышении указанного значения: резервное копирование прерывается с ошибкой. Текст ошибки (отформатирован для упрощения восприятия) 2026-04-10 14:53:54.942 [2366509] ERR failed to write backup aborting package=pangolin.engine err= "saving wals: process replication messages: process next message: switch WAL segment: write current WAL segment: 000000010000047300000010: limit of WAL files waiting to be written is reached max_pending_wals value: 100 suggestions: - increase backup_policy.write_wals_workers_no - increase or disable backup_policy.max_pending_wals stopping WAL delivery gateway" архив с незавершенной РК удаляется.

При выборе значения учитывайте:

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

Ограничение очереди WAL-файлов помогает:

• предотвратить переполнение диска;
• избежать аварийного завершения работы сервера;
• контролировать потребление ресурсов во время резервного копирования.

Использование механизма автоматического определения адреса основного сервера БД (primary)

Независимо от того, для какого узла БД (основного или реплики) создается резервная копия, информация о результате РК сохраняется в БД компонента pbra_db, расположенного на одном хосте с основным сервером БД (primary).

При создании резервной копии узла реплики, важно убедиться, чтобы были заданы параметры, которые необходимы для подключения к БД pbra_db. Настройка подключения утилиты copywala к БД pbra_db возможна следующими способами:

• C помощью механизма автоматического определения адреса основного узла.
• Явное определение параметров подключения (host и port) в секции pbra_db конфигурационного файла copywala.yaml.

Принцип работы механизма

Механизм использует встроенные функции и системные представления и работает следующим образом:

1. При запуске резервного копирования copywala подключается к целевой БД, указанной в конфигурационном файле copywala.yaml, секция target_db.

2. Определяется роль целевой БД с помощью функции pg_is_in_recovery():

   • true – подключение выполнено к реплике;
   • false – подключение выполнено к основному серверу.

3. Если установлено, что роль целевой БД – реплика:

   1. Адрес и порт основного сервера извлекаются из представления pg_stat_wal_receiver;
   2. Полученные значения используются для подключения к основному серверу: они подставляются вместо имеющихся в copywala.yaml (секция pbra_db, поля host и port).

Включение механизма автоматического определения адреса основного узла

1. Убедитесь, что у пользователя, выполняющего РК, есть права на чтение всех данных в представлении pg_stat_wal_receiver. Если прав нет, выдайте их одной из команд:

   • GRANT pg_monitor TO backup_user;

   • GRANT pg_read_all_stats TO backup_user;

2. В конфигурационном файле copywala.yaml:

   1. Проверьте, что в секции target_db заданы значения для параметров host и port.
   2. Проверьте, что в секции pbra_db для параметров host и port значения не заданы.

После создания резервной копии на узле-релике в логах copywala будет выведено сообщение:

pbra_db host and port are automatically switched to the master address obtained from pg_stat_wal_receiver

Важно

В случае, если в секции pbra_db для параметров host и port заданы значения и значение в параметре pbra_db.host отличается от значения в target_db.host, механизм автоматического определения адреса мастера не запускается.

Добавление в резервную копию дополнительных файлов

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