Redrock Postgres 搜索 英文
版本: 10 / 11 / 12 / 13 / 14 / 15 / 16

CREATE SUBSCRIPTION

CREATE SUBSCRIPTION — 定义一个新的订阅

大纲

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

描述

CREATE SUBSCRIPTION添加一个新的逻辑复制订阅。订阅名称必须与当前数据库中任何现有订阅的名称不同。

订阅表示与发布者的复制连接。因此,除了在本地目录中添加定义外,该命令通常会在发布者上创建一个复制槽。

逻辑复制工作者将在运行此命令的事务提交时开始为新订阅复制数据,除非订阅最初被禁用。

关于订阅和逻辑复制的更多信息,请参见 第 31.2 节第 31 章

参数

subscription_name

新订阅的名称。

CONNECTION 'conninfo'

定义如何连接到发布者数据库的libpq连接字符串。详情请参见第 34.1.1 节

PUBLICATION publication_name [, ...]

要订阅的发布者上的发布名称。

WITH ( subscription_parameter [= value] [, ... ] )

本条款指定了订阅的可选参数。

以下参数控制订阅创建过程中发生的情况:

connect (boolean)

指定CREATE SUBSCRIPTION命令是否应该连接到发布者。默认值为true。 将其设置为false将强制create_slotenabledcopy_data的值为false。 (不能将connect设置为false并将create_slotenabledcopy_data设置为true。)

当此选项为false时不会建立连接,因此没有表被订阅,因此在启用订阅后将不会复制任何内容。 您需要运行ALTER SUBSCRIPTION ... REFRESH PUBLICATION来订阅表。

create_slot (boolean)

指定命令是否应在发布者上创建复制插槽。默认值为true。 如果设置为false,则您需要以其他方式创建发布者的插槽。

enabled (boolean)

指定订阅是否应该主动复制,还是仅设置但尚未启动。默认值为true

slot_name (string)

发布者的复制插槽的名称。默认情况下使用订阅名称作为插槽名称。

slot_name设置为NONE意味着订阅不会关联复制插槽。 当您稍后将手动创建复制插槽时,请使用此选项。此类订阅还必须将enabledcreate_slot都设置为false

下列参数控制订阅在创建后的复制行为:

binary (boolean)

指定订阅是否请求发布者以二进制格式发送数据(而不是文本)。 默认值为false。 即使启用此选项,只有具有二进制发送和接收功能的数据类型才会以二进制形式传输。

在进行跨版本复制时,可能出现这样的情况:发布者对某种数据类型有二进制发送功能,但订阅者缺乏该类型的二进制接收功能。 在这种情况下,数据传输将失败,且binary选项无法使用。

copy_databoolean

指定在复制开始时是否复制正在订阅的publication中的预先存在的数据。 默认值为true

如果publication包含WHERE子句,它将影响复制的数据。请参考 Notes获取详细信息。

streaming (boolean)

指定是否启用此订阅的事务流式处理。默认情况下,所有事务在发布者上完全解码,然后作为整体发送给订阅者。

synchronous_commit (enum)

此参数的值将覆盖此订阅的应用工作进程中的 synchronous_commit设置。默认值为 off

使用off对于逻辑复制是安全的: 如果订阅者由于缺少同步而丢失事务,则数据将再次从发布者发送。

在进行同步逻辑复制时,可能需要使用不同的设置。逻辑复制工作者会向发布者报告写入和刷新的位置, 在使用同步复制时,发布者将等待实际的刷新。这意味着当订阅用于同步复制时,将订阅者的 synchronous_commit设置为off可能会增加发布者上 COMMIT的延迟。在这种情况下,将synchronous_commit 设置为local或更高可能是有利的。

two_phaseboolean

指定是否为此订阅启用两阶段提交。默认值为false

当启用两阶段提交时,准备好的事务会在PREPARE TRANSACTION时发送给订阅者, 并在订阅者上也作为两阶段事务处理。否则,准备好的事务只有在提交时才会发送给 订阅者,然后由订阅者立即处理。

两阶段提交的实现要求复制已成功完成初始表同步阶段。因此,即使为订阅启用了two_phase, 内部的两阶段状态仍会暂时保持挂起,直到初始化阶段完成。 参见pg_subscriptionsubtwophasestate列, 以了解实际的两阶段状态。

disable_on_errorboolean

指定是否应在发布者进行数据复制期间,如果订阅工作者检测到任何错误,则自动禁用订阅。默认值为 false

注意

有关如何在订阅和发布实例之间配置访问控制的详细信息,请参见 第 31.9 节

创建复制槽时(默认行为), CREATE SUBSCRIPTION不能在事务块内部执行。

如果复制插槽不是作为同一命令的一部分创建的,则创建连接到相同数据库集群的订阅 (例如,在同一集群中的数据库之间进行复制或在同一个数据库中进行复制)只能成功 否则,CREATE SUBSCRIPTION调用将挂起。要做到这一点, 单独创建复制插槽(使用函数pg_create_logical_replication_slot 和插件名称pgoutput),并使用参数create_slot = false 创建订阅。这是一个实施限制,可能会在未来的版本中解除。

如果publication中的任何表具有WHERE子句,则对于expression 评估为false或null的行将不会被发布。如果订阅中有多个publication,在其中同一表已使用 不同的WHERE子句进行发布,如果任何一个表达式(指的是该发布操作)被满足,则将发布一行。 在不同WHERE子句的情况下,如果其中一个publication没有WHERE子句(指的是该 发布操作)或publication被声明为FOR ALL TABLESFOR TABLES IN SCHEMA,则无论其他表达式的定义如何,行都将被发布。 如果订阅者是PostgreSQL 15版本之前的版本,则在初始数据同步阶段将忽略任何行过滤。 对于这种情况,用户可能希望考虑删除任何最初复制的数据,这些数据与后续过滤不兼容。 因为初始数据同步在复制现有表数据时不考虑publication publish参数,可能会复制一些使用DML不会被复制的行。参见 第 31.2.2 节 以获取示例。

具有多个publication的订阅,其中同一表以不同的列列表发布,不受支持。

我们允许指定不存在的publication,以便用户稍后添加。这意味着 pg_subscription 可以有不存在的publication。

示例

创建一个到远程服务器的订阅,复制发布mypublicationinsert_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