Postgres Pro Enterprise
1817
Postgres Pro Standard
1817
PostgreSQL
1817
RUENRU EN
pg_createsubscriber
Пред. НаверхСерверные приложения Postgres ProНачало След.

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 принимает следующие аргументы командной строки:

-d имя_бд
--database=имя_бд

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

-D каталог
--pgdata=каталог

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

-n
--dry-run

Делать всё, кроме внесения изменений в целевой каталог.

-p порт
--subscriber-port=порт

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

-P строка_подключения
--publisher-server=строка_подключения

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

-s каталог
--socketdir=каталог

Каталог, в котором процесс postmaster будет создавать сокеты на целевом сервере. По умолчанию — текущий каталог.

-t секунды
--recovery-timeout=секунды

Максимальное время ожидания завершения восстановления (в секундах). Значение 0 (по умолчанию) отключает этот тайм-аут.

-U имя_пользователя
--subscriber-username=имя_пользователя

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

-v
--verbose

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

--config-file=имя_файла

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

--publication=имя

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

--replication-slot=имя

Имя слота репликации для настройки логической репликации. Используйте несколько параметров --replication-slot, чтобы указать несколько слотов репликации. Число слотов должно совпадать с числом указанных баз данных, в противном случае выводится ошибка. Слоты репликации необходимо указывать в том же порядке, что и базы данных в соответствующем параметре. Если не указать этот параметр, слоту репликации присваивается имя подписки.

--subscription=имя

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

-V
--version

Вывести версию pg_createsubscriber и завершиться.

-?
--help

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

Примечания

Предварительные требования

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

Целевой сервер должен использоваться как резервный сервер физической репликации. На целевом сервере значение параметров конфигурации max_replication_slots и max_logical_replication_workers должно быть больше или равно числу указанных баз данных, а значение параметра max_worker_processes должно быть больше этого числа. Целевой сервер должен принимать локальные подключения.

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

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

pg_createsubscriber изменяет системный идентификатор при помощи утилиты pg_resetwal, которая позволяет избегать ситуаций, когда целевой сервер может использовать файлы 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 в качестве действия, которое должен выполнить сервер после достижения точки восстановления. Добавляются дополнительные параметры восстановления, чтобы избежать непредвиденного поведения во время процесса восстановления, например завершения восстановления при достижении согласованного состояния (WAL должен применяться до точки начала репликации) или появления множественных точек восстановления, которые могут привести к сбою.

    Примечание

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

    Этот шаг завершается после выхода сервера из режима резерва и начала приёма транзакций чтения-записи. Если задан параметр --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
Пред. Наверх След.
pg_controldata Начало pg_ctl
pg_createsubscriber
Prev UpPostgres Pro Server ApplicationsHome Next

pg_createsubscriber

pg_createsubscriber — convert a physical replica into a new logical replica

Synopsis

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

Description

pg_createsubscriber creates a new logical replica from a physical standby server. All tables in the specified database are included in the logical replication setup. A pair of publication and subscription objects are created for each database. It must be run at the target server.

After a successful run, the state of the target server is analogous to a fresh logical replication setup. The main difference between the logical replication setup and pg_createsubscriber is how the data synchronization is done. pg_createsubscriber does not copy the initial table data. It does only the synchronization phase, which ensures each table is brought up to a synchronized state.

pg_createsubscriber targets large database systems because in logical replication setup, most of the time is spent doing the initial data copy. Furthermore, a side effect of this long time spent synchronizing data is usually a large amount of changes to be applied (that were produced during the initial data copy), which increases even more the time when the logical replica will be available. For smaller databases, it is recommended to set up logical replication with initial data synchronization. For details, see the CREATE SUBSCRIPTION copy_data option.

Options

pg_createsubscriber accepts the following command-line arguments:

-d dbname
--database=dbname

The name of the database in which to create a subscription. Multiple databases can be selected by writing multiple -d switches.

-D directory
--pgdata=directory

The target directory that contains a cluster directory from a physical replica.

-n
--dry-run

Do everything except actually modifying the target directory.

-p port
--subscriber-port=port

The port number on which the target server is listening for connections. Defaults to running the target server on port 50432 to avoid unintended client connections.

-P connstr
--publisher-server=connstr

The connection string to the publisher. For details see Section 33.1.1.

-s dir
--socketdir=dir

The directory to use for postmaster sockets on target server. The default is current directory.

-t seconds
--recovery-timeout=seconds

The maximum number of seconds to wait for recovery to end. Setting to 0 disables. The default is 0.

-U username
--subscriber-username=username

The user name to connect as on target server. Defaults to the current operating system user name.

-v
--verbose

Enables verbose mode. This will cause pg_createsubscriber to output progress messages and detailed information about each step to standard error. Repeating the option causes additional debug-level messages to appear on standard error.

--config-file=filename

Use the specified main server configuration file for the target data directory. pg_createsubscriber internally uses the pg_ctl command to start and stop the target server. It allows you to specify the actual postgresql.conf configuration file if it is stored outside the data directory.

--publication=name

The publication name to set up the logical replication. Multiple publications can be specified by writing multiple --publication switches. The number of publication names must match the number of specified databases, otherwise an error is reported. The order of the multiple publication name switches must match the order of database switches. If this option is not specified, a generated name is assigned to the publication name.

--replication-slot=name

The replication slot name to set up the logical replication. Multiple replication slots can be specified by writing multiple --replication-slot switches. The number of replication slot names must match the number of specified databases, otherwise an error is reported. The order of the multiple replication slot name switches must match the order of database switches. If this option is not specified, the subscription name is assigned to the replication slot name.

--subscription=name

The subscription name to set up the logical replication. Multiple subscriptions can be specified by writing multiple --subscription switches. The number of subscription names must match the number of specified databases, otherwise an error is reported. The order of the multiple subscription name switches must match the order of database switches. If this option is not specified, a generated name is assigned to the subscription name.

-V
--version

Print the pg_createsubscriber version and exit.

-?
--help

Show help about pg_createsubscriber command line arguments, and exit.

Notes

Prerequisites

There are some prerequisites for pg_createsubscriber to convert the target server into a logical replica. If these are not met, an error will be reported. The source and target servers must have the same major version as the pg_createsubscriber. The given target data directory must have the same system identifier as the source data directory. The given database user for the target data directory must have privileges for creating subscriptions and using pg_replication_origin_advance().

The target server must be used as a physical standby. The target server must have max_replication_slots and max_logical_replication_workers configured to a value greater than or equal to the number of specified databases. The target server must have max_worker_processes configured to a value greater than the number of specified databases. The target server must accept local connections.

The source server must accept connections from the target server. The source server must not be in recovery. The source server must have wal_level as logical. The source server must have max_replication_slots configured to a value greater than or equal to the number of specified databases plus existing replication slots. The source server must have max_wal_senders configured to a value greater than or equal to the number of specified databases and existing WAL sender processes.

Warnings

If pg_createsubscriber fails after the target server was promoted, then the data directory is likely not in a state that can be recovered. In such case, creating a new standby server is recommended.

pg_createsubscriber usually starts the target server with different connection settings during transformation. Hence, connections to the target server should fail.

Since DDL commands are not replicated by logical replication, avoid executing DDL commands that change the database schema while running pg_createsubscriber. If the target server has already been converted to logical replica, the DDL commands might not be replicated, which might cause an error.

If pg_createsubscriber fails while processing, objects (publications, replication slots) created on the source server are removed. The removal might fail if the target server cannot connect to the source server. In such a case, a warning message will inform the objects left. If the target server is running, it will be stopped.

If the replication is using primary_slot_name, it will be removed from the source server after the logical replication setup.

If the target server is a synchronous replica, transaction commits on the primary might wait for replication while running pg_createsubscriber.

pg_createsubscriber sets up logical replication with two-phase commit disabled. This means that any prepared transactions will be replicated at the time of COMMIT PREPARED, without advance preparation. Once setup is complete, you can manually drop and re-create the subscription(s) with the two_phase option enabled.

pg_createsubscriber changes the system identifier using pg_resetwal. It would avoid situations in which the target server might use WAL files from the source server. If the target server has a standby, replication will break and a fresh standby should be created.

How It Works

The basic idea is to have a replication start point from the source server and set up a logical replication to start from this point:

  1. Start the target server with the specified command-line options. If the target server is already running, pg_createsubscriber will terminate with an error.

  2. Check if the target server can be converted. There are also a few checks on the source server. If any of the prerequisites are not met, pg_createsubscriber will terminate with an error.

  3. Create a publication and replication slot for each specified database on the source server. Each publication is created using FOR ALL TABLES. If the --publication option is not specified, the publication has the following name pattern: “pg_createsubscriber_%u_%x” (parameter: database oid, random int). If the --replication-slot option is not specified, the replication slot has the following name pattern: “pg_createsubscriber_%u_%x” (parameters: database oid, random int). These replication slots will be used by the subscriptions in a future step. The last replication slot LSN is used as a stopping point in the recovery_target_lsn parameter and by the subscriptions as a replication start point. It guarantees that no transaction will be lost.

  4. Write recovery parameters into the target data directory and restart the target server. It specifies an LSN (recovery_target_lsn) of the write-ahead log location up to which recovery will proceed. It also specifies promote as the action that the server should take once the recovery target is reached. Additional recovery parameters are added to avoid unexpected behavior during the recovery process such as end of the recovery as soon as a consistent state is reached (WAL should be applied until the replication start location) and multiple recovery targets that can cause a failure.

    Note

    If an error occurs during this step, recovery parameters might remain in the target server's configuration. You may need to manually delete these parameters before attempting to run pg_createsubscriber again.

    This step completes once the server exits the standby mode and starts accepting read-write transactions. If the --recovery-timeout option is set and recovery takes longer than the specified number of seconds, pg_createsubscriber terminates.

  5. Create a subscription for each specified database on the target server. If the --subscription option is not specified, the subscription has the following name pattern: “pg_createsubscriber_%u_%x” (parameters: database oid, random int). It does not copy existing data from the source server. It does not create a replication slot. Instead, it uses the replication slot that was created in a previous step. The subscription is created but it is not enabled yet. The reason is the replication progress must be set to the replication start point before starting the replication.

  6. Drop publications on the target server that were replicated because they were created before the replication start location. It has no use on the subscriber.

  7. Set the replication progress to the replication start point for each subscription. When the target server starts the recovery process, it catches up to the replication start point. This is the exact LSN to be used as a initial replication location for each subscription. The replication origin name is obtained since the subscription was created. The replication origin name and the replication start point are used in pg_replication_origin_advance() to set up the initial replication location.

  8. Enable the subscription for each specified database on the target server. The subscription starts applying transactions from the replication start point.

  9. If the standby server was using primary_slot_name, it has no use from now on so drop it.

  10. If the standby server contains failover replication slots, they cannot be synchronized anymore, so drop them.

  11. Update the system identifier on the target server. The pg_resetwal is run to modify the system identifier. The target server is stopped as a pg_resetwal requirement.

Examples

To create a logical replica for databases hr and finance from a physical replica at foo: 

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

Prev Up Next
pg_controldata Home pg_ctl
FAQ