pg_createsubscriber

примечание

Эта страница переведена при помощи нейросети GigaChat.

pg_createsubscriber – преобразовывает физическую реплику в новую логическую реплику.

Синтаксис

pg_createsubscriber [option...] { -d | --database }dbname { -D | --pgdata }datadir { -P | --publisher-server }connstr

Описание

pg_createsubscriber создает новую логическую реплику из физического резервного сервера. Все таблицы указанной базы данных включаются в настройку логической репликации. Для каждой базы данных создается пара объектов публикации и подписки. Команда должна выполняться на целевом сервере.

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

pg_createsubscriber предназначен для больших систем баз данных, поскольку при настройке логической репликации большая часть времени тратится на первоначальное копирование данных. Кроме того, побочным эффектом длительного времени, затрачиваемого на синхронизацию данных, обычно является большое количество изменений, подлежащих применению (которые были произведены во время первоначального копирования данных), что еще больше увеличивает время доступности логической реплики. Для небольших баз данных рекомендуется настроить логическую репликацию с начальной синхронизацией данных. Подробнее смотрите в параметре CREATE SUBSCRIPTION copy_data.

Параметры

pg_createsubscriber принимает следующие аргументы командной строки:

-a
--all

Создать одну подписку для каждой базы данных на целевом сервере. Исключения составляют шаблонные базы данных и базы данных, которые не разрешают подключения. Чтобы узнать список всех баз данных, подключитесь к исходному серверу, используя имя базы данных, указанное в строке подключения --publisher-server, или, если оно не указано, будет использоваться база данных postgres, или, если она не существует, будет использоваться template1. При указании этого параметра используются автоматически сгенерированные имена для подписок, публикаций и слотов репликации. Этот параметр нельзя использовать вместе с --database, --publication, --replication-slot или --subscription.

-d dbname
--database=dbname

Имя базы данных, в которой будет создана подписка. Можно выбрать несколько баз данных, указав несколько параметров -d. Этот параметр нельзя использовать вместе с -a. Если параметр -d не указан, имя базы данных будет получено из параметра -P. Если имя базы данных не указано ни в параметре -d, ни в параметре -P, и не указан параметр -a, будет выдана ошибка.

-D directory
--pgdata=directory

Целевая директория, содержащая каталог кластера физической реплики.

-n
--dry-run

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

-p port
--subscriber-port=port

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

-P connstr
--publisher-server=connstr

Строка подключения к публикующему серверу. Подробнее смотрите раздел «Строки подключения».

-s dir
--socketdir=dir

Директория, используемая для сокетов постмастера на целевом сервере. Значением по умолчанию является текущая директория.

-t seconds
--recovery-timeout=seconds

Максимальное количество секунд ожидания окончания восстановления. Установка значения 0 отключает ожидание. Значение по умолчанию равно 0.

-T
--enable-two-phase

Включает двухфазную фиксацию для подписки. Если указано несколько баз данных, этот параметр применяется единообразно ко всем подпискам, созданным в этих базах данных. Значение по умолчанию — false.

-U username
--subscriber-username=username

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

-v
--verbose

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

--clean=objtype

Удалить все объекты указанного типа из указанных баз данных на целевом сервере.

publications: Публикации FOR ALL TABLES, созданные для этого подписчика, всегда удаляются, указание этого типа объекта приводит к удалению всех остальных публикаций, реплицируемых с исходного сервера.

Выбранные для удаления объекты регистрируются индивидуально, в том числе во время --dry-run. Нет возможности повлиять на удаление выбранных объектов или остановить его, поэтому рекомендуется создать их резервную копию с помощью pg_dump.

--config-file=filename

Используйте указанный основной файл конфигурации сервера для целевой директории данных. pg_createsubscriber внутренне использует команду pg_ctl для запуска и остановки целевого сервера. Она позволяет указать реальный конфигурационный файл postgresql.conf, если он хранится вне директории данных.

--publication=name

Имя публикации для настройки логической репликации. Можно указать несколько публикаций, используя несколько параметров --publication. Количество имен публикаций должно совпадать с количеством указанных баз данных, в противном случае будет выдана ошибка. Порядок параметров имен публикаций должен совпадать с порядком параметров баз данных. Если этот параметр не указан, имени публикации присваивается сгенерированное имя. Этот параметр нельзя использовать вместе с --all.

--replication-slot=name

Имя слота репликации для настройки логической репликации. Можно указать несколько слотов репликации, используя несколько параметров --replication-slot. Количество имен слотов репликации должно совпадать с количеством указанных баз данных, в противном случае будет выдана ошибка. Порядок параметров имен слотов репликации должен совпадать с порядком параметров баз данных. Если этот параметр не указан, имя слота репликации присваивается имени подписки. Этот параметр нельзя использовать вместе с --all.

--subscription=name

Имя подписки для настройки логической репликации. Можно указать несколько подписок, используя несколько параметров --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 не реплицируются логической репликацией, избегайте выполнения команд 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-файлы не будут преждевременно удалены.

Как это работает

Основная идея заключается в том, чтобы начать процесс репликации с точки начала репликации на исходном сервере и настроить логическую репликацию, начиная с этой точки:

1. Запустите целевой сервер с указанными параметрами командной строки. Если целевой сервер уже запущен, pg_createsubscriber завершится с ошибкой.
2. Проверьте возможность преобразования целевого сервера. Также выполняются несколько проверок исходного сервера. Если какие-либо предварительные условия не выполнены, pg_createsubscriber завершится с ошибкой.
3. Создайте публикацию и слот репликации для каждой указанной базы данных на исходном сервере. Каждая публикация создается с использованием FOR ALL TABLES. Если не указана опция --publication, название публикации имеет следующий шаблон: «pg_createsubscriber_%u_%x» (параметры: база данных oid, случайное число int). Если не указана опция --replication-slot, имя слота репликации имеет следующий шаблон: «pg_createsubscriber_%u_%x» (параметры: база данных oid, случайное число int). Эти слоты репликации будут использоваться подписками на следующем этапе. Последняя позиция LSN слота репликации используется в качестве контрольной точки остановки параметра recovery_target_lsn и подписками в качестве начальной точки репликации. Это гарантирует отсутствие потери транзакций.
4. Запишите параметры восстановления в каталог данных целевого сервера и перезапустите целевой сервер. Он задает позицию журнала упреждающей записи (LSN) recovery_target_lsn, до которой будет выполняться восстановление. Кроме того, задается действие promote, которое сервер должен выполнить после достижения цели восстановления. Добавляются дополнительные параметры восстановления recovery parameters, чтобы предотвратить неожиданное поведение во время процесса восстановления, например завершение восстановления сразу после достижения согласованного состояния (журнал упреждающей записи должен применяться до места начала репликации) и наличие нескольких целей восстановления, что может вызвать сбой. Этот шаг завершается, когда сервер выходит из режима ожидания и принимает операции чтения-записи. Если установлена опция --recovery-timeout, pg_createsubscriber прекращает работу, если восстановление не заканчивается в течение указанного количества секунд.
5. Создать подписку для каждой указанной базы данных на целевом сервере. Если не указана опция --subscription, подписка имеет следующее имя шаблона: «pg_createsubscriber_%u_%x» (параметры: база данных oid, случайное число int). Она не копирует существующие данные с исходного сервера. Она также не создает слот репликации. Вместо этого она использует слот репликации, созданный на предыдущем шаге. Подписка создана, но пока еще не включена. Причина в том, что перед началом репликации необходимо установить прогресс репликации на точку начала репликации.
6. Удалить публикации на целевом сервере, которые были реплицированы, так как они были созданы до местоположения начала репликации. Они бесполезны на подписчике.
7. Установить прогресс репликации на начальную точку репликации для каждой подписки. Когда целевой сервер начинает процесс восстановления, он догоняет до точки начала репликации. Именно эта позиция LSN должна использоваться в качестве начальной позиции репликации для каждой подписки. Имя источника репликации получено, поскольку подписка была создана. Имя источника репликации и точка начала репликации используются в команде pg_replication_origin_advance() для установки начальной позиции репликации.
8. Включить подписку для каждой указанной базы данных на целевом сервере. Подписка начинает применять транзакции с момента начала репликации.
9. Если резервный сервер использовал primary_slot_name, теперь оно больше не нужно, поэтому его можно удалить.
10. Если на резервном сервере имеются слоты репликации переключения, их нельзя синхронизировать дальше, поэтому их следует удалить.
11. Обновляет системный идентификатор на целевом сервере. Команда pg_resetwal выполняется для изменения системного идентификатора. Целевой сервер останавливается согласно требованию pg_resetwal.

Примеры

Чтобы создать логического репликанта для баз данных hr и finance из физического репликанта на foo:

$ pg_createsubscriber -D /usr/local/pgsql/data -P "host=foo" -d hr -d finance

Подробнее смотрите также

pg_basebackup