pg_createsubscriber
pg_createsubscriber — преобразовать физическую реплику в новую логическую реплику
Синтаксис
pg_createsubscriber [параметр...] { -d | --database }имя_бд { -D | --pgdata }каталог_данных { -P | --publisher-server }строка_подключения
Описание
pg_createsubscriber создаёт новую логическую реплику из резервного сервера физической репликации. Все таблицы указанной базы данных включаются в схему логической репликации. Для каждой базы данных создаётся пара объектов публикации и подписки. Утилиту нужно запускать на целевом сервере.
После успешного запуска состояние целевого сервера не отличается от новой схемы логической репликации. Единственное отличие логической репликации от механизма pg_createsubscriber в том, как выполняется синхронизация данных. Утилита не копирует исходные данные таблицы, а лишь выполняет синхронизацию, что позволяет привести каждую таблицу в синхронизированное состояние.
Утилита pg_createsubscriber предназначена для крупных баз данных, поскольку при логической репликации больше всего времени уходит именно на начальное копирование данных. Кроме того, в результате длительной синхронизации обычно приходится применять много изменений (которые возникли при начальном копировании), из-за чего логическая реплика ещё дольше остаётся недоступной. Для небольших баз данных рекомендуется настраивать логическую репликацию с начальной синхронизацией данных. За подробностями обратитесь к параметру CREATE SUBSCRIPTION copy_data.
Параметры
pg_createsubscriber принимает следующие аргументы командной строки:
-a--allСоздавать одну подписку для каждой базы данных на целевом сервере, за исключением шаблонных баз данных и баз данных, к которым не разрешается подключение. Чтобы посмотреть список всех баз данных, подключитесь к исходному серверу, используя имя базы данных, заданное в строке подключения
--publisher-server; если имя не задано, будет использована база данныхpostgres, а если она не существует, будет использована база данныхtemplate1. Если указан этот параметр, используются автоматически сгенерированные имена для подписок, публикаций и слотов репликации. Этот параметр нельзя использовать вместе с--database,--publication,--replication-slotили--subscription.-dимя_бд--database=имя_бдИмя базы данных, в которой нужно создать подписку. Используйте несколько параметров
-d, чтобы указать несколько баз данных. Этот параметр нельзя использовать вместе с-a. Если параметр-dне указан, имя базы данных будет получено из параметра-P. Если имя базы данных не указано ни в параметре-d, ни в параметре-P, а также не указан параметр-a, возникнет ошибка.-Dкаталог--pgdata=каталогЦелевой каталог, содержащий каталог кластера физической реплики.
-n--dry-runДелать всё, кроме внесения изменений в целевой каталог.
-pпорт--subscriber-port=портНомер порта, через который целевой сервер принимает подключения. По умолчанию целевой сервер запускается с портом 50432, чтобы не допустить нежелательных клиентских подключений.
-Pстрока_подключения--publisher-server=строка_подключенияСтрока подключения к публикующему серверу. Подробности описаны в Подразделе 32.1.1.
-sкаталог--socketdir=каталогКаталог, в котором процесс postmaster будет создавать сокеты на целевом сервере. По умолчанию — текущий каталог.
-tсекунды--recovery-timeout=секундыМаксимальное время ожидания завершения восстановления (в секундах). Значение 0 (по умолчанию) отключает этот тайм-аут.
-T--enable-two-phaseВключает для подписки режим фиксации
two_phase. Когда указаны несколько баз данных, этот параметр единообразно применяется ко всем подпискам, созданным в этих базах данных. Значение по умолчанию —false.-Uимя_пользователя--subscriber-username=имя_пользователяИмя пользователя для подключения к целевому серверу. По умолчанию — имя текущего пользователя операционной системы.
-v--verboseВключает режим подробных сообщений. При включённом параметре pg_createsubscriber будет выводить сообщения о процессе выполнения и подробную информацию о каждом шаге в стандартный поток ошибок. Если указать этот параметр повторно, в стандартный поток ошибок будут выдаваться дополнительные отладочные сообщения.
--clean=тип_объектаУдалять все объекты указанного типа из указанных баз данных на целевом сервере.
publications: Всегда удаляются публикацииFOR ALL TABLES, установленные для этого подписчика. Указание этого типа объектов также удаляет все остальные публикации, реплицированные с исходного сервера.
Все объекты, выбранные для удаления, сохраняются в журнал индивидуально, в том числе при
--dry-run. Нет возможности повлиять на удаление выбранных объектов или остановить его, поэтому рассмотрите возможность создания резервной копии объектов с помощью pg_dump.--config-file=имя_файлаИспользовать указанный основной файл конфигурации сервера для целевого каталога данных. Утилита pg_createsubscriber использует команду
pg_ctlдля запуска и остановки целевого сервера. Этот параметр позволяет указывать фактический файл конфигурацииpostgresql.conf, если он хранится за пределами каталога данных.--publication=имяИмя публикации для настройки логической репликации. Используйте несколько параметров
--publication, чтобы указать несколько публикаций. Число публикаций должно совпадать с числом указанных баз данных, в противном случае выводится сообщение об ошибке. Публикации необходимо указывать в том же порядке, что и базы данных в соответствующем параметре. Если не указать этот параметр, публикации присваивается сгенерированное имя. Этот параметр нельзя использовать вместе с--all.--replication-slot=имяИмя слота репликации для настройки логической репликации. Используйте несколько параметров
--replication-slot, чтобы указать несколько слотов репликации. Число слотов должно совпадать с числом указанных баз данных, в противном случае выводится ошибка. Слоты репликации необходимо указывать в том же порядке, что и базы данных в соответствующем параметре. Если не указать этот параметр, слоту репликации присваивается имя подписки. Этот параметр нельзя использовать вместе с--all.--subscription=имяИмя подписки для настройки логической репликации. Используйте несколько параметров
--subscription, чтобы указать несколько подписок. Число подписок должно совпадать с числом указанных баз данных, в противном случае выводится ошибка. Подписки необходимо указывать в том же порядке, что и базы данных в соответствующем параметре. Если не указать этот параметр, подписке присваивается сгенерированное имя. Этот параметр нельзя использовать вместе с--all.-V--versionВывести версию pg_createsubscriber и завершиться.
-?--helpВывести справку об аргументах командной строки pg_createsubscriber и завершиться.
Примечания
Предварительные требования
Существуют определённые требования, которые должны выполнятся, чтобы утилита pg_createsubscriber могла преобразовать целевой сервер в логическую реплику. При их невыполнении выводится сообщение об ошибке. Для корректного использования pg_createsubscriber основные версии исходного и целевого сервера должны совпадать. У заданного целевого каталога данных должен быть такой же системный идентификатор, как у исходного. Пользователь баз данных, указанный для целевого каталога данных, должен иметь права на создание подписок и использование функции pg_replication_origin_advance().
Целевой сервер должен использоваться как резервный сервер физической репликации. На целевом сервере значение параметров конфигурации max_active_replication_origins и max_logical_replication_workers должно быть больше или равно числу указанных баз данных, а значение параметра max_worker_processes должно быть больше этого числа. Целевой сервер должен принимать локальные подключения. Если вы планируете использовать параметр --enable-two-phase, вам также необходимо соответствующим образом настроить max_prepared_transactions.
Исходный сервер должен принимать подключения от целевого сервера. Исходный сервер не должен находиться в состоянии восстановления. На исходном сервере параметр конфигурации wal_level должен иметь значение logical, значение параметра max_replication_slots должно быть больше или равно сумме указанных баз данных и существующих слотов репликации, а значение параметра max_wal_senders должно быть больше или равно сумме указанных баз данных и существующих процессов передачи WAL.
Предупреждения
При нарушении работы pg_createsubscriber после повышения целевого сервера, вероятнее всего, каталог данных нельзя будет восстановить. Если это произошло, рекомендуется создать новый резервный сервер.
При преобразовании реплик pg_createsubscriber обычно запускает целевой сервер с другими параметрами подключения, поэтому в этот момент подключиться к нему не получится.
DDL-команды не участвуют в логической репликации, поэтому при работе с pg_createsubscriber необходимо избегать выполнения команд, изменяющих схему баз данных. Если целевой сервер уже преобразован в логическую реплику, DDL-команды, вероятно, не будут реплицированы, что может вызвать ошибку.
При нарушении работы pg_createsubscriber во время обработки данных удаляются объекты (публикации, слоты репликации), созданные на исходном сервере. Если целевому серверу не удаётся подключиться к исходному серверу, удаление может завершиться ошибкой. В этом случае предупреждение покажет объекты, которые не были удалены. Запущенный целевой сервер будет остановлен.
Если для репликации используется параметр primary_slot_name, этот слот будет удалён с исходного сервера после настройки логической репликации.
Если целевой сервер является синхронной репликой, при работе pg_createsubscriber транзакции на ведущем сервере могут ожидать завершения репликации.
Если не указан параметр --enable-two-phase, утилита pg_createsubscriber настраивает логическую репликацию с отключённой двухфазной фиксацией. Это означает, что любые подготовленные транзакции будут реплицироваться во время выполнения оператора COMMIT PREPARED без предварительной подготовки. После завершения настройки можно вручную удалять и создавать подписки заново с включённым параметром two_phase.
pg_createsubscriber изменяет системный идентификатор при помощи утилиты pg_resetwal, которая позволяет избегать ситуаций, когда целевой сервер может использовать файлы WAL исходного сервера. Если у целевого сервера есть резервный сервер, репликация прервётся и нужно будет создать новый резервный сервер.
Если отсутствуют нужные файлы WAL, могут возникнуть сбои репликации. Чтобы предотвратить это, для параметра max_slot_wal_keep_size исходного сервера должно быть установлено значение -1, тогда нужные файлы WAL не будут удаляться преждевременно.
Как это работает
Основная идея состоит в том, чтобы иметь начальную точку репликации с исходного сервера и настроить начало логической репликации с этой точки:
Запустить целевой сервер с указанными параметрами командной строки. Если он уже запущен, pg_createsubscriber завершится с ошибкой.
Проверить, можно ли преобразовать целевой сервер. Также выполняется несколько проверок исходного сервера. Если какое-либо из предварительных требований не выполнено, pg_createsubscriber завершится ошибкой.
Создать публикацию и слот репликации для каждой указанной базы данных на исходном сервере. Каждая публикация создаётся с использованием параметра
FOR ALL TABLES. Если параметр--publicationне указан, имя публикации задаётся по следующему шаблону: «pg_createsubscriber_%u_%x» (параметры:oidбазы данных, случайное целое числоint). Если параметр--replication-slotне указан, имя слота репликации задаётся по следующему шаблону: «pg_createsubscriber_%u_%x» (параметры:oidбазы данных, случайное целое числоint). Эти слоты репликации будут использоваться подписками на следующем шаге. Последний LSN для слота репликации используется в качестве точки остановки в параметре recovery_target_lsn, а подписками используется в качестве начальной точки репликации. Таким образом гарантируется, что ни одна транзакция не будет потеряна.Записать параметры восстановления в целевой каталог данных и перезапустить целевой сервер. Указывает LSN (recovery_target_lsn) позиции в журнале предзаписи, до которой должно выполняться восстановление. Также указывает
promoteв качестве действия, которое должен выполнить сервер после достижения точки восстановления. Добавляются дополнительные параметры восстановления, чтобы избежать непредвиденного поведения во время процесса восстановления, например завершения восстановления при достижении согласованного состояния (WAL должен применяться до точки начала репликации) или появления множественных точек восстановления, которые могут привести к сбою. Этот шаг завершается после выхода сервера из режима резерва и начала приёма транзакций чтения-записи. При заданном параметре--recovery-timeoutутилита pg_createsubscriber завершает работу, если восстановление не заканчивается до истечения указанного количества секунд.Создать подписку для каждой указанной базы данных на целевом сервере. Если параметр
--subscriptionне указан, имя подписки задаётся по следующему шаблону: «pg_createsubscriber_%u_%x» (параметры:oidбазы данных, случайное целое числоint). Подписка не копирует существующие данные с исходного сервера и не создаёт слот репликации. Она использует слот репликации, который был создан на предыдущем этапе. Подписка создана, но ещё не активирована, потому что, прежде чем начать репликацию, её положение нужно установить на начальную точку.Удалить на целевом сервере публикации, изменения которых были реплицированы, так как они были созданы до точки начала репликации. Подписчик не сможет их использовать.
Установить положение репликации в начальную точку репликации для всех подписок. Когда целевой сервер начинает восстановление, он нагоняет начальную точку репликации. Именно этот LSN должен использоваться в качестве исходного положения репликации для всех подписок. Имя источника репликации поступает из-за создания подписки. Имя источника репликации и начальная точка репликации используются функцией
pg_replication_origin_advance(), чтобы установить исходное положение репликации.Активировать подписку для каждой указанной базы данных на целевом сервере. Подписка начинает применять транзакции с начальной точки репликации.
Если на резервном сервере был установлен параметр primary_slot_name, теперь его можно удалить за ненадобностью.
Если на резервном сервере есть слоты репликации для отработки отказа, их можно удалить из-за невозможности дальнейшей синхронизации.
Обновить системный идентификатор на целевом сервере. Для его изменения запускается утилита pg_resetwal. Целевой сервер останавливается — это обязательное условие для выполнения команды
pg_resetwal.
Примеры
Используйте следующую команду, чтобы создать логическую реплику для баз данных hr и finance из физической реплики, подключившись к публикующему серверу foo:
$pg_createsubscriber -D /usr/local/pgsql/data -P "host=foo" -d hr -d finance