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

примечание

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

Проблематика

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

При восстановлении на точку во времени (PITR) PostgreSQL запрашивает WAL-файлы через restore_command. Если restore_command обращается только к одному хранилищу, восстановление может завершиться с ошибкой из-за отсутствия части необходимых WAL-файлов.

Для решения этой проблемы реализован механизм multi-restore: восстановление WAL-файлов из нескольких хранилищ. При восстановлении на точку во времени (PITR) multi-restore позволяет последовательно запрашивать WAL-файлы из нескольких хранилищ, обеспечивая восстановление полной цепочки WAL-файлов даже после смены хранилища.

Важно

Механизм multi-restore поддерживает только смену параметра wal_destination_uri. Все остальные параметры в конфигурационном файле copywala.yaml должны быть одинаковыми для всех хранилищ, из которых выполняется восстановление.

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

Функциональность восстановления WAL-файлов из нескольких хранилищ включает три этапа:

1. Подготовка

   Пользователь выполняет команду copywala restore-wal prepare-multi-restore, передав в нее URI тех хранилищ, в которых заархивированы WAL-файлы. В ходе выполнения команды:

   • в конфигурационном файле copywala.yaml создается секция wal_restore (если ее не было), и в значении параметра wal_restore.multi_restore_wal_uris сохраняется список URI хранилищ;
   • из каждого хранилища списка запрашиваются WAL-файлы для экземпляра restore_instance_name;
   • на основе полученного списка WAL-файлов создается кеш-файл multi_restore.wals.cache, содержащий информацию о соответствии WAL-файлов и хранилищ, в которых они находятся. Расположение кеш-файла можно изменить с помощью параметра wal_restore.multi_restore_cache_path в copywala.yaml. По умолчанию файл создается в каталоге, указанном в параметре copywala_dir файла copywala.yaml. Если параметр не задан, используется каталог /var/pbr/copywala/;
   • сформированный кеш-файл используется при последующих вызовах restore_command для ускорения поиска требуемого WAL-сегмента.

   При каждом запуске copywala restore-wal prepare-multi-restore кеш-файл формируется заново.

   Пример содержания multi_restore.wals.cache

   {
     "prepared_for_instance_name": "test_019f5a44-a1a9-7431-8876-6fc9122044bd",
     "storages": [
       {
         "uri": "local-fs:///home/postgres/backups/wals_first_dir",
         "wals": [
           {
             "wal_start": "000000010000000000000019",
             "wal_end": "000000010000000000000067"
           },
           {
             "wal_start": "00000001000000000000006F",
             "wal_end": "000000010000000000000075"
           }
         ],
         "history_files": []
       },
       {
         "uri": "local-fs:///home/postgres/backups/wals_second_dir",
         "wals": [
           {
             "wal_start": "000000010000000000000068",
             "wal_end": "00000001000000000000006E"
           }
         ],
         "history_files": []
       },
       {
         "uri": "local-fs:///home/postgres/backups/wals_third_dir",
         "wals": [
           {
             "wal_start": "000000010000000000000076",
             "wal_end": "00000001000000000000007C"
           }
         ],
         "history_files": []
       }
     ]
   }

   Подсказка

   Поле history_files содержит список файлов истории временных шкал (timeline), присутствующих в соответствующем хранилище.

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

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

2. Восстановление

   При запуске PostgreSQL и выполнении restore_command Copywala:

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

   Copywala использует хранилище по умолчанию, указанное в параметре wal_destination_uri если:

   • multi_restore.wals.cache недоступен или не содержит информации о хранилищах;
   • запрошенный WAL-файл отсутствует в multi_restore.wals.cache.

3. Отключение

   После завершения восстановления пользователь выполняет команду copywala restore-wal disable-multi-restore.

   В результате:

   • очищается значение параметра wal_restore.multi_restore_wal_uris в файле copywala.yaml;
   • удаляются файлы кеша, созданные для работы механизма multi-restore.

Предусловия

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

1. Выполнено восстановление данных PGDATA и табличных пространств из резервной копии.
2. Настроен сетевой доступ ко всем хранилищам, в которые выполнялось архивирование WAL-файлов.

Пользователем получен список URI хранилищ WAL-файлов.

примечание

Файл ${PGDATA}/copywala_meta/wal_destination_uri.history содержит историю изменений wal_destination_uri, которые совершались только командой copywala config set. Если параметр wal_destination_uri в copywala.yaml изменялся вручную или внешней СРК, список хранилищ, в которых могут находиться WAL-файлы, необходимо уточнить у администраторов СРК.

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

1. Выполните команду copywala restore-wal prepare-multi-restore (ознакомьтесь со справкой по команде ниже), передав в нее необходимые хранилища.

   Справка по команде 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

   :caption: Пример успешного ответа
   
   2026-07-13 10:12:36.074 [129535] INF successfully add config param path=wal_restore.multi_restore_wal_uris value="[\"local-fs:///home/postgres/backups/wals_first_dir\"]"
   2026-07-13 10:12:36.089 [129535] INF cache for wals multi storage restore successfully prepared path=/var/pbr/copywala/multi_restore.wals.cache

2. Настройте в конфигурационном файле postgresql.conf целевую точку во времени, до которой требуется произвести восстановление.

к сведению

По умолчанию при восстановлении применяются все доступные WAL-файлы, данное поведение можно ограничить, задав один из параметров: recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, recovery_target_xid. Подробнее про это читайте в документации Platform V Pangolin.

Например, задайте контрольную точку во времени, используя параметр recovery_target_lsn. Установите его значение равным номеру журнала транзакций (LSN), полученному после завершения подготовки данных для таблицы test. Альтернативно можно задать точное время восстановления с помощью параметра recovery_target_time.

Чтобы сервер запускался после завершения процесса восстановления, установите в конфигурационном файле опцию:

recovery_target_action = 'promote'

Это позволит автоматически перевести сервер из режима восстановления в обычный рабочий режим сразу после достижения целевой точки восстановления.

3. Создайте файл для переключения сервера в режим восстановления:

touch /pgdata/db-restored/recovery.signal

4. Запустите сервер:

pg_ctl start -D /pgdata/db-restored/

5. Выполните команду copywala restore-wal disable-multi-restore (ознакомьтесь со справкой по команде ниже).

   Справка по команде 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

   :caption: Пример успешного ответа
   
   2026-07-13 10:19:21.906 [130593] INF successfully replace config param path=wal_restore.multi_restore_wal_uris value=[]
   2026-07-13 10:19:21.906 [130593] INF successfully removed wals cache for multi restore path=/var/pbr/copywala/multi_restore.wals.cache    

Результат

Восстановление на целевую точку во времени успешно выполнено.

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

Сценарий	Сообщение в выводе	Возможная причина	Решение
Отсутствует кеш-файл multi_restore.wals.cache	ERR determine storage for multi restore failed app=copywala err="read multi restore cache: open /var/pbr/copywala/multi_restore.wals.cache: no such file or directory"	Команда prepare-multi-restore не выполнялась перед восстановлением. Кеш-файл был удален вручную или командой copywala restore-wal disable-multi-restore. Путь к кеш-файлу в параметре wal_restore.multi_restore_cache_path не совпадает с фактическим расположением файла.	Выполните команду copywala restore-wal prepare-multi-restore. Убедитесь, что параметр wal_restore.multi_restore_cache_path в copywala.yaml указывает на правильный путь
Не найден WAL-файл	wal file is not found in cache: fallback to main storage	Запрошенный WAL-сегмент не попадает ни в один из диапазонов wal_start - wal_end в кеш-файле multi_restore.wals.cache. Возможные причины: WAL-файл был архивирован в хранилище, которое не было указано в команде prepare-multi-restore. WAL-файл был создан после выполнения copywala restore-wal prepare-multi-restore.	Добавьте недостающее хранилище и повторно выполните copywala restore-wal prepare-multi-restore с полным списком URI хранилищ
Кеш-файл поврежден	read multi restore cache: <error>	Не удалось прочитать файл multi_restore.wals.cache	Выполните команду copywala restore-wal prepare-multi-restore для пересоздания кеш-файла. Проверьте права доступа к директории, указанной в wal_restore.multi_restore_cache_path
Ошибка при записи кеш-файла	cache for wals multi storage restore preparation failed: <error>	Не удалось создать или записать файл multi_restore.wals.cache. Возможные причины: Недостаточно прав для записи в директорию, указанную в wal_restore.multi_restore_cache_path. Директория для кеш-файла не существует.	Проверьте права доступа пользователя к директории, указанной в wal_restore.multi_restore_cache_path. При необходимости предоставьте права на запись или измените путь к кеш-файлу.