CREATE SUBSCRIPTION

CREATE SUBSCRIPTION — 定义新订阅

概要

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

说明

CREATE SUBSCRIPTION添加一个新的逻辑复制订阅。创建订阅的用户将成为该订阅的所有者。订阅名称必须与当前数据库中任何现有订阅的名称不同。

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

除非最初禁用订阅，否则将在运行此命令的事务提交时启动一个逻辑复制工作进程来复制新订阅的数据。

要能够创建订阅，您必须具有pg_create_subscription角色的权限，以及对当前数据库的CREATE权限。

有关订阅和逻辑复制整体的更多信息，请参阅第 31.2 节和第 31 章。

参数

订阅名称 #

新订阅的名称。

CONNECTION '连接信息' #

定义如何连接到发布者数据库的 libpq 连接字符串。有关详细信息，请参阅第 34.1.1 节。

PUBLICATION publication_name [, ...] #

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

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

此子句指定订阅的可选参数。

以下参数控制订阅创建期间发生的情况

connect (boolean) #

指定 CREATE SUBSCRIPTION 命令是否应连接到发布者。默认值为 true。将其设置为 false 将强制 create_slot、enabled 和 copy_data 的值为 false。（你不能将 connect 设置为 false 与将 create_slot、enabled 或 copy_data 设置为 true 结合使用。）

由于在该选项为 false 时未建立连接，因此不订阅任何表。若要启动复制，你必须手动创建复制槽、启用订阅并刷新订阅。有关示例，请参阅第 31.2.3 节。

create_slot (boolean) #

指定命令是否应在发布者上创建复制槽。默认值为 true。

如果设置为 false，则你负责以其他方式创建发布者的槽。有关示例，请参阅第 31.2.3 节。

enabled (boolean) #

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

slot_name (string) #

要使用的发布者复制槽的名称。默认情况下，对槽名称使用订阅名称。

将 slot_name 设置为 NONE 意味着订阅不会与复制槽关联。此类订阅还必须将 enabled 和 create_slot 都设置为 false。稍后将手动创建复制槽时使用此选项。有关示例，请参见第 31.2.3 节。

以下参数控制订阅创建后的复制行为

binary (boolean) #

指定订阅是否将请求发布者以二进制格式（而非文本格式）发送数据。默认值为 false。任何初始表同步副本（请参见 copy_data）也使用相同的格式。二进制格式可能比文本格式更快，但它在机器架构和 PostgreSQL 版本之间的可移植性较差。二进制格式非常特定于数据类型；例如，它不允许从 smallint 列复制到 integer 列，即使在文本格式中可以正常工作。即使启用此选项，也只有具有二进制发送和接收函数的数据类型才会以二进制形式传输。请注意，初始同步要求所有数据类型都具有二进制发送和接收函数，否则同步将失败（有关发送/接收函数的更多信息，请参见 CREATE TYPE）。

在进行跨版本复制时，发布者可能对某些数据类型具有二进制发送函数，但订阅者缺少该类型的二进制接收函数。在这种情况下，数据传输将失败，并且无法使用 binary 选项。

如果发布者是低于 16 的 PostgreSQL 版本，则即使 binary = true，任何初始表同步都将使用文本格式。

copy_data (布尔值) #

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

如果发布包含 WHERE 子句，它将影响复制的数据。有关详细信息，请参阅注释。

有关 copy_data = true 如何与 origin 参数交互的详细信息，请参阅注释。

streaming (枚举) #

指定是否为该订阅启用正在进行的事务的流式传输。默认值为 off，这意味着所有事务都在发布者上完全解码，然后才作为整体发送给订阅者。

如果设置为 on，则传入的更改将写入临时文件，然后仅在事务在发布者上提交并由订阅者接收后才应用。

如果设置为 parallel，则传入的更改将直接通过一个并行应用工作进程（如果可用）应用。如果没有并行应用工作进程可以处理流式传输事务，则更改将写入临时文件并在事务提交后应用。请注意，如果并行应用工作进程中发生错误，则远程事务的完成 LSN 可能不会在服务器日志中报告。

synchronous_commit (枚举) #

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

将 off 用于逻辑复制是安全的：如果订阅者因缺少同步而丢失事务，则数据将从发布者重新发送。

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

two_phase (boolean) #

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

启用两阶段提交时，准备好的事务在 PREPARE TRANSACTION 时发送到订阅者，并在订阅者上作为两阶段事务进行处理。否则，准备好的事务仅在提交时发送到订阅者，然后由订阅者立即处理。

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

disable_on_error (boolean) #

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

password_required (boolean) #

如果设置为 true，则由于此订阅而建立的与发布者的连接必须使用密码验证，并且必须将密码指定为连接字符串的一部分。当订阅归超级用户所有时，将忽略此设置。默认值为 true。只有超级用户可以将此值设置为 false。

run_as_owner (boolean) #

如果为 true，则所有复制操作都将作为订阅所有者执行。如果为 false，则复制工作进程将以该表的拥有者的身份对每个表执行操作。后一种配置通常更安全；有关详细信息，请参阅第 31.9 节。默认值为 false。

origin (string) #

指定订阅是否请求发布者仅发送没有原点或无论原点如何而发送的更改。将 origin 设置为 none 意味着订阅将请求发布者仅发送没有原点的更改。将 origin 设置为 any 意味着发布者无论其原点如何都发送更改。默认值为 any。

有关 copy_data = true 如何与 origin 参数交互的详细信息，请参阅注释。

在指定类型为boolean的参数时，可以省略=*value*部分，这等同于指定TRUE。

注释

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

在创建复制槽（默认行为）时，不能在事务块内执行CREATE SUBSCRIPTION。

如果复制槽不是作为同一命令的一部分创建的，则创建连接到同一数据库集群的订阅（例如，在同一集群中的数据库之间复制或在同一数据库内复制）只会成功。否则，CREATE SUBSCRIPTION调用将挂起。要使其正常工作，请分别创建复制槽（使用函数pg_create_logical_replication_slot和插件名称pgoutput），并使用参数create_slot = false创建订阅。有关示例，请参见第 31.2.3 节。这是一个实现限制，可能会在未来版本中解除。

如果发布中的任何表都有WHERE子句，则*expression*求值为 false 或 null 的行不会发布。如果订阅有几个发布，其中同一张表已使用不同的WHERE子句发布，则如果满足任何表达式（引用该发布操作），则会发布该行。对于不同的WHERE子句，如果其中一个发布没有WHERE子句（引用该发布操作）或发布被声明为FOR ALL TABLES或FOR TABLES IN SCHEMA，则无论其他表达式的定义如何，始终发布行。如果订阅者是 15 版之前的PostgreSQL版本，则在初始数据同步阶段会忽略任何行筛选。对于这种情况，用户可能希望考虑删除任何最初复制的数据，这些数据与后续筛选不兼容。由于初始数据同步在复制现有表数据时不考虑发布publish参数，因此可能会复制一些行，而这些行不会使用 DML 复制。有关示例，请参见第 31.2.2 节。

不支持在其中同一张表已使用不同的列列表发布的多个发布的订阅。

我们允许指定不存在的发布，以便用户稍后添加这些发布。这意味着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,
     pg_subscription_rel PS
     JOIN pg_class C ON (C.oid = PS.srrelid)
     JOIN pg_namespace N ON (N.oid = C.relnamespace)
WHERE N.nspname = PT.schemaname AND
      C.relname = PT.tablename 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

CREATE SUBSCRIPTION ​

概要 ​

说明 ​

参数 ​

注释 ​

示例 ​

兼容性 ​

另请参见 ​

CREATE SUBSCRIPTION

概要

说明

参数

注释

示例

兼容性

另请参见