Формат манифеста резервной копии

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

Манифест резервной копии представляет собой документ JSON в кодировке UTF-8. (Хотя в целом документы JSON должны быть представлены в Unicode, QHB допускает использование типов данных json и jsonb в любой поддерживаемой сервером кодировке. Для манифестов резервных копий подобное исключение не делается.) Этот документ JSON всегда содержит объект; ключи, находящиеся в этом объекте, описываются в разделе ниже.

Объект верхнего уровня в манифесте копии

Документ JSON, представляющий манифест копии, содержит следующие ключи.

PostgreSQL-Backup-Manifest-Version
Связанное с этим ключом значение всегда равно целому числу 1.

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

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

Manifest-Checksum
Этот ключ всегда находится в последней строке файла манифеста резервной копии. Связанное с ним значение является контрольной суммой всех предыдущих строк, вычисленной по алгоритму SHA256. Здесь используется фиксированный метод расчета контрольных сумм, чтобы клиенты могли провести инкрементальный синтаксический анализ манифеста. Хотя алгоритм SHA256 значительно дороже алгоритма CRC32C, обычно манифест достаточно мал, чтобы эти дополнительные вычисления ни на что особо не влияли.

Объект файла в манифесте копии

Это объект, описывающий один файл и содержащий ключ Path или Encoded-Path. Обычно он содержит ключ Path. Связанное строковое значение представляет собой путь к файлу относительно корневого каталога резервной копии. У файлов, расположенных в пользовательском табличном пространстве, первыми компонентами пути будут pg_tblspc и OID этого табличного пространства. Если путь является строкой не в кодировке UTF-8 или пользователь хочет, чтобы кодировались пути для всех файлов, то вместо ключа Path будет присутствовать ключ Encoded-Path. В нем содержатся те же данные, но закодированные в виде строки шестнадцатеричных цифр, каждая пара которых представляет один байт.

Всегда присутствуют следующие два ключа:

Size
Ожидаемый размер этого файла, в виде целого числа.

Last-Modified
Время последнего изменения файла, выданное сервером в процессе создания резервной копии. В отличие от других полей, хранящихся в копии, это поле не используется утилитой qhb_verifybackup. Оно добавлено исключительно для информации.

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

Checksum-Algorithm
Алгоритм, который применялся для расчета контрольной суммы этого файла. В настоящее время этот алгоритм будет одинаковым для всех файлов в манифесте резервной копии, но в будущих выпусках это может измениться. На данный момент поддерживаются алгоритмы CRC32C, SHA224, SHA256, SHA384 и SHA512.

Checksum
Контрольная сумма, вычисленная для этого файла и хранящаяся в виде последовательности шестнадцатеричных цифр, по две на каждый байт контрольной суммы.

Объект диапазона WAL в манифесте копии

Объект, описывающий диапазон WAL, всегда содержит три ключа:

Timeline
Временная шкала для этого диапазона записей WAL, в виде целого числа.

Start-LSN
Позиция LSN, с которой должно начаться воспроизведение на указанной временной шкале, чтобы эту резервную копию можно было применить для восстановления. LSN хранится в формате, принятом в QHB, т. е. в виде строки, состоящей из двух разделенных слэшем строк длиной от 1 до 8 шестнадцатеричных символов каждая.

End-LSN
Самый первый LSN, на котором может закончиться воспроизведение на указанной временной шкале при восстановлении из резервной копии. Он хранится в том же формате, что и Start-LSN.

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