Перейти к основному содержимому

CREATE SUBSCRIPTION

примечание

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

CREATE SUBSCRIPTION - создание новой подписки.

Синтасис​

CREATE SUBSCRIPTION subscription_name
    CONNECTION 'conninfo'
    PUBLICATION publication_name [, ...]
    [ WITH ( subscription_parameter [= value] [, ... ] ) ]

Описание​

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

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

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

Чтобы иметь возможность создать подписку, нужно обладать привилегиями роли pg_create_subscription, а также CREATE привилегиями на текущую базу данных.

Дополнительные сведения о подписках и логической репликации можно найти в разделе «Подписка» и разделе «Логическая репликация» официальной документации.

Параметры​

subscription_name
Задает имя новой подписки, которая должна быть создана.
CONNECTION conninfo
Задает строку подключения формата libpq, определяющая, как подключаться к базе данных публикации.
PUBLICATION publication_name [, ...]
Задает список публикаций, на которые оформляется подписка.
WITH ( subscription_parameter [= value] [, ... ] )
Определяет опциональные параметры для подписки.

Следующие параметры определяют поведение при создании подписки:

connect (boolean) : Указывает, должна ли команда CREATE SUBSCRIPTION подключаться к публикующему серверу. По умолчанию имеет значение true. При установке значения false параметры create_slot, enabled и copy_data также принудительно устанавливаются в значении false. Нельзя одновременно указать connect = false и установить значения true для create_slot, enabled или copy_data.

Поскольку подключение не устанавливается, когда этот параметр установлен в false, никакие таблицы не подписываются. Чтобы инициировать репликацию, необходимо вручную создать слот репликации, включить отказоустойчивость при необходимости, активировать подписку и обновить ее. См. примеры в разделе «Подписка».

create_slot (boolean)
Указывает, должна ли команда создать слот репликации на стороне публикующего сервера. По умолчанию имеет значение

Если установлено значение false, придется каким-то другим способом создать слот издателя.

enabled (boolean)
Указывает, должна ли подписка сразу начинать репликацию, или она только настраивается без запуска. По умолчанию имеет значение

slot_name (string) : Задает имя слота репликации на стороне публикующего сервера. По умолчанию используется имя подписки.

Установка slot_name в NONE означает отсутствие связанного со слотом подписки слота репликации. Такие подписки также должны иметь оба параметра enabled и create_slot равными false. Используйте это, если планируете позже вручную создать слот репликации. См. примеры в разделе «Подписка»

При установке slot_name в допустимое имя и create_slot в false значение свойства failover указанного слота может отличаться от соответствующего параметра failover, заданного в подписке. Всегда убедитесь, что свойство слота failover соответствует аналогичному параметру подписки и наоборот. В противном случае слот на сервере-издателе может вести себя иначе, чем указано этими параметрами подписки: например, слот на сервере-издателе мог бы синхронизироваться с резервными серверами даже тогда, когда опция подписки failover отключена, либо он мог бы быть отключен для синхронизации, несмотря на включение опции подписки failover.

Следующие параметры определяют поведение репликации после создания подписки:

binary (boolean)
Определяет, будет ли подписка запрашивать у издателя отправку данных в двоичном формате (в отличие от текстового). Значение по умолчанию — false. Любая начальная копия синхронизации таблицы (см. copy_data) также использует тот же формат. Двоичный формат может быть быстрее текстового формата, но он менее переносим между архитектурами машин и версиями PostgreSQL. Двоичный формат очень специфичен для типов данных; например, он не позволит копировать данные из столбца типа smallint в столбец типа integer, хотя это прекрасно сработает в текстовом формате. Даже когда эта опция включена, только типы данных, имеющие функции отправки и приема бинарных данных, будут передаваться в двоичной форме. Обратите внимание, что начальная синхронизация требует наличия функций отправки и приема бинарных данных для всех типов данных, иначе синхронизация завершится неудачей (см. раздел CREATE TYPE для получения дополнительной информации о функциях отправки/приема).

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

Если издатель является версией PostgreSQL до версии 16, тогда любая первоначальная синхронизация таблиц будет выполняться в текстовом формате даже при условии binary = true.

copy_data (boolean)
Указывает, нужно ли копировать существующие данные из публикаций при запуске репликации. По умолчанию имеет значение

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

См. раздел «Примечания» для деталей того, как copy_data = true может взаимодействовать с параметром origin.

streaming (enum)
Определяет, нужно ли включить потоковую передачу незавершенных транзакций для данной подписки. Значением по умолчанию является

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

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

synchronous_commit (enum)
Значение этого параметра переопределяет настройку

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

Другое значение может быть уместно при синхронной логической репликации. Рабочие процессы логической репликации сообщают публикующему серверу позиции записи и сброса, и при синхронной репликации публикующий сервер будет ждать фактического сброса. Это означает, что установка synchronous_commit = off у подписчика при синхронной репликации может увеличить задержку при выполнении COMMIT на стороне публикующего сервера. В такой ситуации может быть полезно установить synchronous_commit в значение local или выше.

two_phase (boolean)
Указывает, включена ли двухфазная фиксация для этой подписки. По умолчанию имеет значение

При включении двухфазной фиксации подготовленные транзакции передаются подписчику в момент выполнения PREPARE TRANSACTION и обрабатываются как двухфазные транзакции. В противном случае подготовленные транзакции передаются подписчику только после их фиксации и применяются сразу.

Реализация двухфазной фиксации требует успешного завершения начальной фазы синхронизации таблиц. Поэтому даже при включенном параметре two_phase, внутреннее состояние подписки временно остается в статусе «ожидает» до завершения инициализации. Актуальное состояние можно проверить в столбце subtwophasestate таблицы pg_subscription.

disable_on_error (boolean)
Указывает, должна ли подписка автоматически отключаться, если рабочие процессы подписки обнаруживают ошибки при передаче данных от публикующего сервера. По умолчанию имеет значение

password_required (boolean) : Если задано значение true, соединения с издателем, созданные в результате этой подписки, должны использовать аутентификацию паролем, причем пароль должен быть указан в строке подключения. Этот параметр игнорируется, если владельцем подписки является суперпользователь. Значение по умолчанию — true. Только суперпользователи могут задать этому значению false.

run_as_owner (boolean) : Если указано значение true, все действия репликации выполняются от имени владельца подписки. При указании значения false рабочие процессы репликации выполняют действия над каждой таблицей от имени владельца этой таблицы. Последняя конфигурация обычно гораздо безопаснее. По умолчанию используется значение false.

origin (string) : Определяет, будет ли подписка запрашивать у издателя отправку изменений, не имеющих происхождения, или отправлять изменения независимо от их происхождения. Установка параметра origin в значение none означает, что подписка запросит у издателя отправку только тех изменений, которые не имеют происхождения. Установка параметра origin в значение any означает, что издатель отправляет изменения вне зависимости от их происхождения. Значение по умолчанию — any.

См. раздел Примечания для детализированного описания взаимодействия параметров copy_data = true и origin.

Примечания​

Смотрите раздел «Безопасность» для получения информации о настройке контроля доступа между экземплярами подписки и публикации.

Если при создании создается слот репликации (что является поведением по умолчанию), команда CREATE SUBSCRIPTION не может выполняться внутри блока транзакции.

Создание подписки, которая подключается к тому же кластеру базы данных (например, для репликации между базами в одном кластере или в рамках одной базы), возможно только если слот репликации не создается в той же команде. В противном случае выполнение CREATE SUBSCRIPTION будет зависать. Чтобы это обойти, следует создать слот репликации отдельно (с помощью функции pg_create_logical_replication_slot с указанием плагина pgoutput), а затем создать подписку с параметром create_slot = false. Это ограничение реализации, которое может быть снято в будущих версиях.

Если какая-либо таблица в публикации имеет условие WHERE, строки, для которых выражение возвращает false или null, не будут публиковаться. Если подписка включает несколько публикаций, в которых одна и та же таблица публикуется с разными условиями WHERE, строка будет публиковаться, если удовлетворяет хотя бы одному из этих выражений. В случае, если одна из публикаций не содержит условия WHERE (или задана как FOR ALL TABLES либо FOR TABLES IN SCHEMA), строки публикуются всегда, независимо от условий в других публикациях.

Если подписчик использует версию PostgreSQL ниже 15, фильтрация строк игнорируется во время начальной синхронизации данных. В этом случае рекомендуется удалить данные, которые были скопированы, но не соответствуют условиям фильтрации. Поскольку начальная синхронизация не учитывает параметр publish публикации, некоторые строки могут быть скопированы, несмотря на то, что они не подлежат репликации в обычном режиме. Смотрите раздел «Примеры» главы «Логическая репликация» для примеров.

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

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

При использовании комбинации параметров подписки copy_data = true и origin = NONE данные таблицы начальной синхронизации копируются непосредственно с издателя, что делает невозможным знание истинного происхождения этих данных. Если издатель также имеет подписки, то скопированные данные таблицы могут исходить из более удаленных источников. Эта ситуация обнаруживается, и пользователю выдается предупреждение, однако оно лишь указывает на потенциальную проблему; ответственность за выполнение необходимых проверок для обеспечения того, чтобы происхождение скопированных данных действительно соответствовало желаемому или нет, лежит на пользователе.

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

# substitute <pub-names> below with your publication name(s) to be queried
SELECT DISTINCT PT.schemaname, PT.tablename
FROM pg_publication_tables PT
JOIN pg_class C ON (C.relname = PT.tablename)
JOIN pg_namespace N ON (N.nspname = PT.schemaname),
pg_subscription_rel PS
WHERE C.relnamespace = N.oid AND
(PS.srrelid = C.oid OR
C.oid IN (SELECT relid FROM pg_partition_ancestors(PS.srrelid) UNION
SELECT relid FROM pg_partition_tree(PS.srrelid))) AND
PT.pubname IN (<pub-names>);

Примеры​

Создание подписки на удаленный сервер, который реплицирует в публикациях таблицы mypublication и insert_only и начинает репликацию немедленно после фиксации:

CREATE SUBSCRIPTION mysub
         CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
        PUBLICATION mypublication, insert_only;

Создание подписки на удаленный сервер, который реплицирует в публикации таблицы insert_only и не начинает репликацию до тех пор, пока она не будет включена позже.

CREATE SUBSCRIPTION mysub
         CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
        PUBLICATION insert_only
               WITH (enabled = false);

Совместимость​

CREATE SUBSCRIPTION является расширением PostgreSQL.

Смотрите также​

ALTER SUBSCRIPTION, DROP SUBSCRIPTION, CREATE PUBLICATION, ALTER PUBLICATION