===================
CREATE SUBSCRIPTION
===================


.. container:: refentry
   :name: SQL-CREATESUBSCRIPTION

   .. container:: titlepage

   .. container:: refnamediv

      .. rubric:: CREATE SUBSCRIPTION
         :name: create-subscription

      CREATE SUBSCRIPTION — 定义一个新的订阅

   .. container:: refsynopsisdiv

      .. rubric:: 大纲
         :name: 大纲

      .. code:: synopsis

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

   .. container:: refsect1
      :name: id-1.9.3.84.5

      .. rubric:: 描述
         :name: 描述

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

      订阅表示到发布者的复制连接。因此，此命令不仅在本地目录中添加定义，
      还会在发布者上创建复制插槽。

      在运行此命令的事务提交时，将启动逻辑复制工作器以复制新订阅的数据。


   .. container:: refsect1
      :name: id-1.9.3.84.6

      .. rubric:: 参数
         :name: 参数

      .. container:: variablelist

         *``subscription_name``*
            新订阅的名称。

         ``CONNECTION 'conninfo``'
            连接发布者的字符串。

         ``PUBLICATION publication_name``
            要订阅的发布者上的发布名称。

         ``WITH ( subscription_parameter`` [= *``value``*] [, ... ] )
            该子句指定订阅的可选参数。支持的参数有：

            .. container:: variablelist

               ``copy_data`` (``boolean``)
                  指定在复制启动后是否应复制正在订阅的发布中的现有数据。
                  默认值是\ ``true``\ 。

               ``create_slot`` (``boolean``)
                  指定该命令是否要在发布者上创建复制槽。默认值是\ ``true``\ 。

               ``enabled`` (``boolean``)
                  指定订阅是否应该主动复制，或者是否应该只是设置，但尚未启动。
                  默认值是\ ``true``\ 。

               ``slot_name`` (``string``)
                  要使用的复制插槽的名称。默认行为是使用订阅名称作为插槽的名称。

                  当\ ``slot_name``\ 设置为\ ``NONE``\ 时，
                  将不会有复制槽与订阅关联。这在需要稍后手动设置复制槽的情况下会使用。
                  这样的订阅必须同时\ ``enabled``\ 并且
                  ``create_slot``\ 设置为\ ``false``\ 。

               ``synchronous_commit`` (``enum``)
                  该参数的值会覆盖\ `synchronous_commit <runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT>`__\ 设置。
                  默认值是\ ``off``\ 。

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

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

               ``connect`` (``boolean``)
                  指定\ ``CREATE SUBSCRIPTION``\ 是否应该连接到发布者。
                  将其设置为\ ``false``\ 将会改变默认值\ ``enabled``\ 、
                  ``create_slot``\ 和\ ``copy_data``\ 为\ ``false``\ 。

                  不允许将\ ``connect``\ 设置为\ ``false``\ 的同时将
                  ``enabled``\ 、\ ``create_slot``\ 或\ ``copy_data``
                  设置为\ ``true``\ 。

                  因为该选项设置为\ ``false``\ 时不会建立连接，
                  因此表没有被订阅，所以当启用订阅后，不会复制任何内容。
                  需要运行\ ``ALTER SUBSCRIPTION ... REFRESH PUBLICATION``\ 才能订阅表。

   .. container:: refsect1
      :name: id-1.9.3.84.7

      .. rubric:: 注意
         :name: 注意

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

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

   .. container:: refsect1
      :name: id-1.9.3.84.8

      .. rubric:: 示例
         :name: 示例

      创建一个到远程服务器的订阅，复制发布\ ``mypublication``\ 和
      ``insert_only``\ 中的表，并在提交时立即开始复制：

      .. code:: programlisting

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

      创建一个到远程服务器的订阅，复制\ ``insert_only``\ 发布中的表，
      并且不开始复制直到稍后启用复制。

      .. code:: programlisting

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

   .. container:: refsect1
      :name: id-1.9.3.84.9

      .. rubric:: 兼容性
         :name: 兼容性

      ``CREATE SUBSCRIPTION``\ 是一个PostgreSQL 扩展。

   .. container:: refsect1
      :name: id-1.9.3.84.10

      .. rubric:: 又见
         :name: 又见

      `ALTER SUBSCRIPTION <sql-altersubscription.html>`__, `DROP
      SUBSCRIPTION <sql-dropsubscription.html>`__, `CREATE
      PUBLICATION <sql-createpublication.html>`__, `ALTER
      PUBLICATION <sql-alterpublication.html>`__