52.4. Протокол потоковой репликации#

52.4. Протокол потоковой репликации

52.4. Протокол потоковой репликации #

Для инициализации потоковой репликации фронтенд отправляет параметр replication в сообщении запуска. Логическое значение true (или on, yes, 1) указывает бэкенду перейти в режим физической репликации walsender, в котором можно выполнять набор нижеприведенных команд репликации вместо SQL-запросов.

Передача значения database в качестве значения параметра replication указывает бэкенду перейти в режим логической репликации walsender, подключаясь к базе данных, указанной в параметре dbname. В режиме логической репликации walsender можно выполнять как команды репликации, показанные ниже, так и обычные SQL-команды.

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

Для целей тестирования команд репликации, вы можете установить соединение репликации через psql или любой другой инструмент, использующий libpq, с использованием строки подключения, включающей опцию replication, например:

psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"

Однако часто более полезно использовать pg_receivewal (для физической репликации) или pg_recvlogical (для логической репликации).

Все команды репликации регистрируются в журнале сервера, когда параметр log_replication_commands включен.

Команды, принимаемые в режиме репликации, включают:

IDENTIFY_SYSTEM #

Запрашивает сервер для идентификации. Сервер отвечает результатом в виде одной строки, содержащей четыре поля:

systemid (text)

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

timeline (int8)

Текущий идентификатор временной шкалы. Также полезно проверить, что резервная копия согласуется с основным сервером.

xlogpos (text)

Текущее местоположение сброса WAL. Полезно получить известное местоположение в журнале предварительной записи, с которого может начаться потоковая передача.

dbname (text)

База данных, подключенная или null.

SHOW name #

Запрашивает сервер для отправки текущего значения параметра времени выполнения. Это аналогично команде SQL SHOW.

name

Имя параметра времени выполнения. Доступные параметры документированы в Глава 18.

TIMELINE_HISTORY tli #

Запрашивает сервер для отправки файла истории таймлайна для таймлайна tli. Сервер отвечает результатом, представляющим собой одну строку с двумя полями. Хотя поля помечены как text, они фактически возвращают необработанные байты без преобразования кодировки.

filename (text)

Имя файла файла истории таймлайна, например, 00000002.history.

content (text)

Содержимое файла истории таймлайна.

CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL | LOGICAL output_plugin } [ ( option [, ...] ) ] #

Создайте физический или логический слот репликации. См. Раздел 25.2.6 для получения дополнительной информации о слотах репликации.

slot_name

Имя слота для создания. Должно быть допустимым именем слота репликации (см. Раздел 25.2.6.1).

output_plugin

Имя выходного плагина, используемого для логического декодирования (см. Раздел 46.6).

TEMPORARY

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

Поддерживаются следующие параметры:

TWO_PHASE [ boolean ]

Если значение true, то этот логический слот репликации поддерживает декодирование двухфазного подтверждения. С этой опцией команды, связанные с двухфазным подтверждением, такие как PREPARE TRANSACTION, COMMIT PREPARED и ROLLBACK PREPARED, декодируются и передаются. Транзакция будет декодирована и передана в момент PREPARE TRANSACTION. По умолчанию значение false.

RESERVE_WAL [ boolean ]

Если значение true, то этот физический слот репликации немедленно резервирует WAL. В противном случае, WAL резервируется только при подключении клиента потоковой репликации. По умолчанию значение false.

SNAPSHOT { 'export' | 'use' | 'nothing' }

Определяет, что делать с созданным снимком во время инициализации логического слота. 'export', который является значением по умолчанию, экспортирует снимок для использования в других сессиях. Эта опция не может быть использована внутри транзакции. 'use' будет использовать снимок для текущей транзакции, выполняющей команду. Эта опция должна использоваться в транзакции, и CREATE_REPLICATION_SLOT должна быть первой командой, выполняемой в этой транзакции. Наконец, 'nothing' просто будет использовать снимок для логического декодирования, как обычно, но ничего больше с ним не будет делать.

В ответ на эту команду сервер отправит результат в виде одной строки, содержащей следующие поля:

slot_name (text)

Имя только что созданного слота репликации.

consistent_point (text)

Местоположение WAL, в котором слот стал согласованным. Это самое раннее местоположение, с которого может начаться потоковая передача на этом слоте репликации.

snapshot_name (text)

Идентификатор снимка, экспортированного командой. Снимок действителен до выполнения новой команды на данном соединении или закрытия соединения репликации. Null, если созданный слот является физическим.

output_plugin (text)

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

CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] } #

Для обеспечения совместимости с более старыми версиями, по-прежнему поддерживается альтернативный синтаксис команды CREATE_REPLICATION_SLOT.

READ_REPLICATION_SLOT slot_name #

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

В ответ на эту команду сервер вернет результат в виде одной строки, содержащей следующие поля:

slot_type (text)

Тип слота репликации, либо physical, либо NULL.

restart_lsn (text)

Слот репликации restart_lsn.

restart_tli (int8)

Идентификатор временной шкалы, связанный с restart_lsn, следующий за текущей историей временной шкалы.

START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] #

Сообщает серверу начать потоковую передачу WAL, начиная с WAL-позиции XXX/XXX. Если указана опция TIMELINE, потоковая передача начинается на временной линии tli; в противном случае выбирается текущая временная линия сервера. Сервер может ответить ошибкой, например, если запрошенная часть WAL уже была переработана. В случае успеха сервер отвечает сообщением CopyBothResponse и затем начинает потоковую передачу WAL на клиентскую сторону.

Если имя слота указано с помощью slot_name, оно будет обновляться по мере продвижения репликации, чтобы сервер знал, какие сегменты WAL и, если hot_standby_feedback включен, какие транзакции все еще нужны резервной копии.

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

После передачи всех WAL на временную линию, которая не является последней, сервер завершает передачу, выходя из режима COPY. Когда клиент подтверждает это, также выходя из режима COPY, сервер отправляет результат с одной строкой и двумя столбцами, указывающими следующую временную линию в истории этого сервера. Первый столбец содержит идентификатор следующей временной линии (тип int8), а второй столбец содержит местоположение WAL, где произошло переключение (тип text). Обычно позиция переключения - это конец WAL, который был передан, но есть случаи, когда сервер может отправить некоторые WAL из старой временной линии, которые он сам еще не воспроизвел перед продвижением. Наконец, сервер отправляет два сообщения CommandComplete (одно, которое завершает CopyData, а другое, которое завершает само START_REPLICATION), и готов принять новую команду.

Все данные WAL отправляются в виде серии сообщений CopyData. (Это позволяет смешивать другую информацию; в частности, сервер может отправить сообщение ErrorResponse, если он столкнется с ошибкой после начала потоковой передачи). Содержимое каждого сообщения CopyData от сервера к клиенту содержит сообщение одного из следующих форматов:

XLogData (B) #
Byte1('w')

Идентифицирует сообщение как данные WAL.

Int64

Начальная точка данных WAL в этом сообщении.

Int64

Текущий конец WAL на сервере.

Int64

Время системных часов сервера в момент передачи, выраженное в микросекундах с полуночи 2000-01-01.

Byten

Секция потоковых данных WAL.

Одна запись WAL никогда не разбивается на два сообщения XLogData. Когда запись WAL пересекает границу страницы WAL и, следовательно, уже разделена с использованием продолжающих записей, она может быть разделена на границе страницы. Другими словами, первая основная запись WAL и ее продолжающие записи могут быть отправлены в разных сообщениях XLogData.

Primary keepalive message (B) #
Byte1('k')

Определяет сообщение как keepalive отправителя.

Int64

Текущий конец WAL на сервере.

Int64

Время системных часов сервера в момент передачи, выраженное в микросекундах с полуночи 2000-01-01.

Byte1

1 означает, что клиент должен ответить на это сообщение как можно скорее, чтобы избежать разрыва соединения по тайм-ауту. 0 в противном случае.

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

Standby status update (F) #
Byte1('r')

Идентифицирует сообщение как обновление статуса получателя.

Int64

Местоположение последнего байта WAL + 1, полученного и записанного на диск на резервном сервере.

Int64

Местоположение последнего байта WAL + 1, записанного на диск в режиме ожидания.

Int64

Местоположение последнего байта WAL + 1, примененного на резервном сервере.

Int64

Время системных часов клиента в момент передачи, выраженное в микросекундах с полуночи 2000-01-01.

Byte1

Если 1, клиент запрашивает сервер ответить на это сообщение немедленно. Это может использоваться для проверки доступности сервера, чтобы проверить, что соединение все еще работает нормально.

Hot standby feedback message (F) #
Byte1('h')

Идентифицирует сообщение как сообщение обратной связи горячего резервирования.

Int64

Время системных часов клиента в момент передачи, выраженное в микросекундах с полуночи 2000-01-01.

Int32

Текущий глобальный xmin резервной копии, исключая catalog_xmin из любых слотов репликации. Если и это значение, и следующее catalog_xmin равны 0, это рассматривается как уведомление о том, что обратная связь горячей резервной копии больше не будет отправляться по этому соединению. Позднее сообщения с ненулевыми значениями могут возобновить механизм обратной связи.

Int32

Эпоха глобального xmin xid на резервной копии.

Int32

Самый низкий catalog_xmin из всех слотов репликации на резервной копии. Установлено в 0, если на резервной копии отсутствует catalog_xmin или если отключена обратная связь горячей резервной копии.

Int32

Эпоха catalog_xmin xid на резервной копии.

START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ] #

Серверу указывается начать передачу WAL для логической репликации, начиная с местоположения WAL XXX/XXX или confirmed_flush_lsn слота (см. Раздел 51.19), в зависимости от того, что больше. Такое поведение упрощает клиентам избегать обновления своего локального статуса LSN, когда нет данных для обработки. Однако, начало с другого LSN, чем запрошено, может не обнаружить определенные виды ошибок клиента; поэтому клиент может захотеть проверить, что confirmed_flush_lsn соответствует его ожиданиям перед выполнением START_REPLICATION.

Сервер может ответить с ошибкой, например, если слот не существует. В случае успеха сервер отвечает сообщением CopyBothResponse, а затем начинает передавать WAL в клиентскую часть.

Сообщения внутри сообщений CopyBothResponse имеют тот же формат, который описан для START_REPLICATION ... PHYSICAL, включая два сообщения CommandComplete.

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

SLOT slot_name

Имя слота для потоковой передачи изменений. Этот параметр обязателен и должен соответствовать существующему логическому слоту репликации, созданному с помощью CREATE_REPLICATION_SLOT в режиме LOGICAL.

XXX/XXX

Местоположение WAL для начала потоковой передачи.

option_name

Имя опции, переданной в плагин логического декодирования слота. См. Раздел 52.5 для опций, которые принимаются стандартным плагином (pgoutput).

option_value

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

DROP_REPLICATION_SLOT slot_name [ WAIT ] #

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

slot_name

Имя слота для удаления.

WAIT

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

BASE_BACKUP [ ( option [, ...] ) ] #

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

LABEL 'label'

Устанавливает метку резервной копии. Если не указано никакой, будет использована метка резервной копии "base backup". Правила экранирования для метки такие же, как для стандартной SQL-строки с включенной опцией standard_conforming_strings.

TARGET 'target'

Говорит серверу, куда отправить резервную копию. Если целью является client, что является значением по умолчанию, данные резервной копии отправляются клиенту. Если это server, данные резервной копии записываются на сервере в путь, указанный в опции TARGET_DETAIL. Если это blackhole, данные резервной копии не отправляются никуда; они просто отбрасываются.

Для цели server требуется привилегия суперпользователя или предоставление роли pg_write_server_files.

TARGET_DETAIL 'detail'

Предоставляет дополнительную информацию о цели резервного копирования.

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

PROGRESS [ boolean ]

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

CHECKPOINT { 'fast' | 'spread' }

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

WAL [ boolean ]

Если установлено значение true, включите необходимые сегменты WAL в резервную копию. Это включит все файлы между началом и окончанием резервного копирования в каталоге pg_wal базового каталога tar-файла. По умолчанию значение false.

WAIT [ boolean ]

Если установлено значение true, резервное копирование будет ждать, пока последний необходимый сегмент WAL не будет заархивирован, или выдаст предупреждение, если архивирование WAL не включено. Если установлено значение false, резервное копирование не будет ни ждать, ни предупреждать, оставляя клиенту ответственность за обеспечение доступности необходимого журнала. Значение по умолчанию — true.

COMPRESSION 'method'

Указывает серверу сжать резервную копию с использованием указанного метода. В настоящее время поддерживаются методы gzip, lz4 и zstd.

COMPRESSION_DETAIL detail

Указывает детали для выбранного метода сжатия. Это следует использовать только в сочетании с опцией COMPRESSION. Если значение является целым числом, оно указывает уровень сжатия. В противном случае, это должен быть список элементов, разделенных запятыми, каждый из которых имеет форму keyword или keyword=value. В настоящее время поддерживаемые ключевые слова: level, long и workers.

Ключевое слово level устанавливает уровень сжатия. Для gzip уровень сжатия должен быть целым числом от 1 до 9 (по умолчанию Z_DEFAULT_COMPRESSION или -1), для lz4 целым числом от 1 до 12 (по умолчанию 0 для быстрого режима сжатия), а для zstd целым числом между ZSTD_minCLevel() (обычно -131072) и ZSTD_maxCLevel() (обычно 22), (по умолчанию ZSTD_CLEVEL_DEFAULT или 3).

Ключевое слово long включает режим дальнего соответствия, для улучшенного коэффициента сжатия, за счет увеличения использования памяти. Режим дальнего соответствия поддерживается только для zstd.

Ключевое слово workers устанавливает количество потоков, которые должны использоваться для параллельного сжатия. Параллельное сжатие поддерживается только для zstd.

MAX_RATE rate

Ограничивает (регулирует) максимальное количество данных, передаваемых с сервера на клиент за единицу времени. Ожидаемая единица измерения - килобайты в секунду. Если указана эта опция, значение должно быть равно нулю или находиться в диапазоне от 32 кБ до 1 ГБ (включительно). Если передано значение ноль или опция не указана, ограничений на передачу не накладывается.

TABLESPACE_MAP [ boolean ]

Если значение true, включает информацию о символических ссылках, присутствующих в каталоге pg_tblspc, в файл с именем tablespace_map. Файл карты табличного пространства включает имя каждой символической ссылки, так как оно существует в каталоге pg_tblspc/, и полный путь этой символической ссылки. По умолчанию значение false.

VERIFY_CHECKSUMS [ boolean ]

Если значение true, то контрольные суммы проверяются во время создания базовой резервной копии, если они включены. Если значение false, то этот шаг пропускается. Значение по умолчанию - true.

MANIFEST manifest_option

Когда эта опция указывается со значением yes или force-encode, создается резервная копия манифеста и отправляется вместе с резервной копией. Манифест представляет собой список всех файлов, присутствующих в резервной копии, за исключением любых WAL-файлов, которые могут быть включены. Он также хранит размер, время последней модификации и, при необходимости, контрольную сумму для каждого файла. Значение force-encode принуждает кодировать все имена файлов в шестнадцатеричном формате; в противном случае, такая кодировка выполняется только для файлов, имена которых представляют собой последовательности октетов, не являющиеся UTF8. Опция force-encode предназначена в основном для тестирования, чтобы убедиться, что клиенты, которые читают манифест резервной копии, могут обработать этот случай. Для обеспечения совместимости с предыдущими версиями значение по умолчанию - MANIFEST 'no'.

MANIFEST_CHECKSUMS checksum_algorithm

Указывает алгоритм контрольной суммы, который должен быть применен к каждому файлу, включенному в резервную копию. В настоящее время доступны следующие алгоритмы: NONE, CRC32C, SHA224, SHA256, SHA384 и SHA512. По умолчанию используется CRC32C.

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

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

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

spcoid (oid)

Идентификатор табличного пространства OID имен или null, если это базовый каталог.

spclocation (text)

Полный путь к каталогу табличного пространства или null, если это базовый каталог.

size (int8)

Размер табличного пространства, примерный, в килобайтах (1024 байтах), если запрошен отчет о прогрессе; в противном случае - null.

После второго обычного набора результатов будет отправлено сообщение CopyOutResponse. Содержимое каждого сообщения CopyData будет содержать сообщение в одном из следующих форматов:

new archive (B)
Byte1('n')

Определяет сообщение как указание на начало нового архива. Будет создан один архив для основного каталога данных и один для каждого дополнительного табличного пространства; каждый будет использовать формат tar (следуя ustar формату обмена, указанному в стандарте POSIX 1003.1-2008).

String

Имя файла для этого архива.

String

Для основного каталога данных - пустая строка. Для других табличных пространств - полный путь к каталогу, из которого был создан этот архив.

manifest (B)
Byte1('m')

Определяет сообщение как указывающее на начало резервной копии манифеста.

archive or manifest data (B)
Byte1('d')

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

Byten

Data bytes.

progress report (B)
Byte1('p')

Идентифицирует сообщение как отчет о прогрессе.

Int64

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

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

Tar-архив для каталога данных и каждого табличного пространства будет содержать все файлы в этих каталогах, независимо от того, являются ли они файлами Tantor SE-1C или другими файлами, добавленными в тот же каталог. Единственные исключенные файлы:

  • postmaster.pid

  • postmaster.opts

  • pg_internal.init (найдено в нескольких каталогах)

  • Различные временные файлы и каталоги, создаваемые во время работы сервера PostgreSQL, такие как любой файл или каталог, начинающийся с pgsql_tmp и временные отношения.

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

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

  • pg_dynshmem, pg_notify, pg_replslot, pg_serial, pg_snapshots, pg_stat_tmp и pg_subtrans} копируются как пустые каталоги (даже если они являются символическими ссылками).

  • Файлы, отличные от обычных файлов и каталогов, такие как символические ссылки (кроме указанных выше каталогов) и специальные устройства и файлы операционной системы, пропускаются. (Символические ссылки в pg_tblspc сохраняются.)

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