ALTER SUBSCRIPTION
ALTER SUBSCRIPTION — 修改订阅的定义
大纲
ALTER SUBSCRIPTIONnameSERVERserver_nameALTER SUBSCRIPTIONnameCONNECTION 'conninfo' ALTER SUBSCRIPTIONnameSET PUBLICATIONpublication_name[, ...] [ WITH (publication_option[=value] [, ... ] ) ] ALTER SUBSCRIPTIONnameADD PUBLICATIONpublication_name[, ...] [ WITH (publication_option[=value] [, ... ] ) ] ALTER SUBSCRIPTIONnameDROP PUBLICATIONpublication_name[, ...] [ WITH (publication_option[=value] [, ... ] ) ] ALTER SUBSCRIPTIONnameREFRESH PUBLICATION [ WITH (refresh_option[=value] [, ... ] ) ] ALTER SUBSCRIPTIONnameREFRESH SEQUENCES ALTER SUBSCRIPTIONnameENABLE ALTER SUBSCRIPTIONnameDISABLE ALTER SUBSCRIPTIONnameSET (subscription_parameter[=value] [, ... ] ) ALTER SUBSCRIPTIONnameSKIP (skip_option=value) ALTER SUBSCRIPTIONnameOWNER TO {new_owner| CURRENT_ROLE | CURRENT_USER | SESSION_USER } ALTER SUBSCRIPTIONnameRENAME TOnew_name
描述
ALTER SUBSCRIPTION 可以更改大多数可在 CREATE SUBSCRIPTION 中指定的订阅属性。
要使用 ALTER SUBSCRIPTION,你必须拥有该订阅。要重命名订阅或更改其所有者,你必须在数据库上具有
CREATE 权限。此外,要更改所有者,你必须能够对新的拥有角色执行
SET ROLE。如果该订阅具有
password_required=false,则只有超级用户可以修改它。
刷新发布时,会移除不再属于该发布的关系;如果存在表同步槽,也会一并删除。必须删除这些槽,才能释放远端主机上为该订阅分配的资源。如果由于网络故障或其他错误,PostgreSQL 无法删除这些槽,则会报告错误。在这种情况下,如需继续,用户要么重试该操作,要么按 DROP SUBSCRIPTION 中的说明将该槽与订阅解除关联并删除该订阅。
命令 ALTER SUBSCRIPTION ... REFRESH PUBLICATION、带有 refresh = true 选项的
ALTER SUBSCRIPTION ... {SET|ADD|DROP} PUBLICATION ...、ALTER SUBSCRIPTION ... SET (failover = true|false) 以及
ALTER SUBSCRIPTION ... SET (two_phase = false)
不能在事务块内执行。
命令 ALTER SUBSCRIPTION ... REFRESH PUBLICATION 以及带有 refresh = true 选项的
ALTER SUBSCRIPTION ... {SET|ADD|DROP} PUBLICATION ...,在订阅启用了
two_phase
参数时也不能执行,除非
copy_data
为 false。要了解实际的两阶段状态,可参见
pg_subscription
的 subtwophasestate 列。
参数
name#要更改其属性的订阅名称。
SERVER#server_name该子句将最初由 CREATE SUBSCRIPTION 设置的外部服务器或连接字符串替换为外部服务器
server_name。CONNECTION '#conninfo'该子句将最初由 CREATE SUBSCRIPTION 设置的外部服务器或连接字符串替换为连接字符串
conninfo。SET PUBLICATIONpublication_nameADD PUBLICATIONpublication_nameDROP PUBLICATION#publication_name这些形式会更改已订阅发布的列表。
SET用新列表替换整个发布列表,ADD向发布列表中添加额外的发布,而DROP从发布列表中移除发布。在ADD和SET变体中,允许指定不存在的发布,以便用户稍后再创建这些发布。详情请参见 CREATE SUBSCRIPTION。默认情况下,此命令还会执行与REFRESH PUBLICATION类似的操作。publication_option指定此操作的附加选项。支持的选项有:refresh(boolean)为
false时,该命令不会尝试刷新表和序列信息。此时应单独执行REFRESH PUBLICATION。默认值为true。
此外,还可以指定
REFRESH PUBLICATION下描述的选项,以控制隐式执行的刷新操作。REFRESH PUBLICATION#从发布者获取缺失的表和序列信息。这将开始复制自
CREATE SUBSCRIPTION或上次执行REFRESH PUBLICATION以来添加到已订阅发布中的表。系统目录 pg_subscription_rel 会更新,以记录订阅已知且仍属于该发布的所有表和序列。
refresh_option指定刷新操作的附加选项。支持的选项有:copy_data(boolean)指定在复制开始时,是否复制所订阅发布中各表预先存在的数据并同步其中的序列。默认值为
true。以前已订阅的表不会再次复制,即使某个表的行过滤器
WHERE子句此后已被修改。以前已订阅的序列不会重新同步。若要这样做,请使用
ALTER SUBSCRIPTION ... REFRESH SEQUENCES。设置
copy_data = true时,可能出现关于发布者与订阅者之间序列定义差异的警告。处理这些警告的建议见第 29.7.1 节。关于
copy_data = true如何与origin参数相互作用的细节,请参见注意。关于以二进制格式复制预先存在的数据的细节,请参见
CREATE SUBSCRIPTION的binary参数。
REFRESH SEQUENCES#重新同步与发布者的序列数据。与
ALTER SUBSCRIPTION ... REFRESH PUBLICATION不同,后者会使订阅的序列集合与发布同步(添加新序列并移除已删除的序列),REFRESH SEQUENCES会重新同步当前所有已订阅序列的序列数据,但不会改变订阅了哪些序列。如果发布中的序列集合发生了变化,请先运行REFRESH PUBLICATION。注意
序列复制要求发布者运行 PostgreSQL 19 或更高版本。
有关处理发布者与订阅者之间序列定义差异的任何警告的建议,请参见第 29.7.1 节。
有关识别和处理不同步序列的建议,请参见第 29.7.2 节。
ENABLE#启用先前已禁用的订阅,并在事务结束时启动逻辑复制工作进程。
DISABLE#禁用正在运行的订阅,并在事务结束时停止逻辑复制工作进程。
SET (#subscription_parameter[=value] [, ... ] )该子句修改最初由 CREATE SUBSCRIPTION 设置的参数。详情请参见该命令。可更改的参数有
slot_name、synchronous_commit、binary、streaming、disable_on_error、password_required、run_as_owner、origin、failover、two_phase、retain_dead_tuples、max_retention_duration、wal_receiver_timeout,以及conflict_log_destination。只有超级用户才能设置password_required = false。更改
slot_name时,所指定槽的failover和two_phase属性值,可能与订阅中相应的failover和two_phase参数不同。创建该槽时,应确保槽的failover和two_phase属性与订阅中对应的参数一致。否则,发布者上的该槽的行为可能与这些订阅选项所表明的不同:例如,即使订阅的failover选项已禁用,发布者上的该槽仍可能被同步到备库;或者即使订阅的failover选项已启用,该槽也可能不会被同步到备库。只有在订阅被禁用时,才能更改
failover、two_phase,以及retain_dead_tuples参数。当将
two_phase从true改为false时,如果发现逻辑复制工作进程在two_phase参数仍为true时执行的任何预备事务,后端进程会报告错误。你可以在发布者节点上处理这些预备事务,或者在订阅者上手工回滚它们,然后再次尝试。与特定订阅对应、由逻辑复制工作进程预备的事务具有如下模式:“pg_gid_%u_%u”(参数:订阅oid,远端事务 IDxid)。要手工处理这类事务,需要回滚名称中包含相应订阅 ID 的所有预备事务。应用可以检查pg_prepared_xacts来找出所需的预备事务。在two_phase选项从true改为false之后,这些事务在提交时会由发布者再次复制。如果将
retain_dead_tuples选项改为false,且没有其他订阅启用该选项,则会删除名为“pg_conflict_detection”的复制槽;该槽用于保留死元组以进行冲突检测。当
conflict_log_destination参数设置为table或all时,系统自动创建冲突日志表。反之,如果目标改为log,则自动删除冲突日志表。SKIP (#skip_option=value)跳过应用远端事务的所有更改。如果传入数据违反任何约束,逻辑复制会停止,直到问题解决。通过使用
ALTER SUBSCRIPTION ... SKIP命令,逻辑复制工作进程会跳过该事务中的所有数据修改操作。此选项对因在订阅者上启用two_phase而已经预备的事务没有作用。逻辑复制工作进程成功跳过该事务或完成一个事务后,LSN(存储在pg_subscription.subskiplsn中)会被清除。有关逻辑复制冲突的详细信息,请参见第 29.8 节。skip_option指定此操作的选项。支持的选项有:lsn(pg_lsn)指定逻辑复制工作进程要跳过其更改的远端事务的完成 LSN。完成 LSN 是该事务提交或预备时所在的 LSN。不支持跳过单个子事务。设置
NONE会重置该 LSN。
new_owner#订阅新所有者的用户名。
new_name#订阅的新名称。
当指定 boolean 类型的参数时,可以省略
= value
部分,这等价于指定 TRUE。
示例
将订阅所订阅的发布更改为 insert_only:
ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only;
禁用(停止)该订阅:
ALTER SUBSCRIPTION mysub DISABLE;
兼容性
ALTER SUBSCRIPTION 是 PostgreSQL
的一个扩展。