sp_addsubscription (Transact-SQL)

将订阅添加到发布并设置订阅服务器的状态。此存储过程在发布服务器上对发布数据库执行。

主题链接图标Transact-SQL 语法约定

语法

sp_addsubscription [ @publication = ] 'publication'
    [ , [ @article = ] 'article']
    [ , [ @subscriber = ] 'subscriber' ]
    [ , [ @destination_db = ] 'destination_db' ]
        [ , [ @sync_type = ] 'sync_type' ]
    [ , [ @status = ] 'status'
        [ , [ @subscription_type = ] 'subscription_type' ]
    [ , [ @update_mode = ] 'update_mode' ]
    [ , [ @loopback_detection = ] 'loopback_detection' ]
    [ , [ @frequency_type = ] frequency_type ]
    [ , [ @frequency_interval = ] frequency_interval ]
    [ , [ @frequency_relative_interval = ] frequency_relative_interval ]
    [ , [ @frequency_recurrence_factor = ] frequency_recurrence_factor ]
    [ , [ @frequency_subday = ] frequency_subday ]
    [ , [ @frequency_subday_interval = ] frequency_subday_interval ]
    [ , [ @active_start_time_of_day = ] active_start_time_of_day ]
    [ , [ @active_end_time_of_day = ] active_end_time_of_day ]
    [ , [ @active_start_date = ] active_start_date ]
    [ , [ @active_end_date = ] active_end_date ]
    [ , [ @optional_command_line = ] 'optional_command_line' ]
    [ , [ @reserved = ] 'reserved' ]
    [ , [ @enabled_for_syncmgr= ] 'enabled_for_syncmgr' ]
    [ , [ @offloadagent= ] remote_agent_activation]
    [ , [ @offloadserver= ] 'remote_agent_server_name' ]
    [ , [ @dts_package_name= ] 'dts_package_name' ]
    [ , [ @dts_package_password= ] 'dts_package_password' ]
    [ , [ @dts_package_location= ] 'dts_package_location' ]
    [ , [ @distribution_job_name= ] 'distribution_job_name' ]
    [ , [ @publisher = ] 'publisher' ]
    [ , [ @backupdevicetype = ] 'backupdevicetype' ]
    [ , [ @backupdevicename = ] 'backupdevicename' ]
    [ , [ @mediapassword = ] 'mediapassword' ]
    [ , [ @password = ] 'password' ]
    [ , [ @fileidhint = ] fileidhint ]
    [ , [ @unload = ] unload ]
    [ , [ @subscriptionlsn = ] subscriptionlsn ]
    [ , [ @subscriptionstreams = ] subscriptionstreams ]
    [ , [ @subscriber_type = ] subscriber_type ]

参数

  • [ @publication=\] 'publication'
    发布的名称。publication 的数据类型为 sysname,无默认值。

  • [ @article=\] 'article'
    发布所订阅的项目。article 的数据类型为 sysname,默认值为 all。如果为 all,则订阅将添加到该发布的所有项目中。Oracle 发布服务器只支持 all 或 NULL 值。

  • [ @subscriber=\] 'subscriber'
    订阅服务器的名称。subscriber 的数据类型为 sysname,默认值为 NULL。

  • [ @destination\_db=\] 'destination_db'
    用于放置复制数据的目标数据库的名称。destination_db 的数据类型为 sysname,默认值为 NULL。如果为 NULL,则 destination_db 将设置为发布数据库的名称。对于 Oracle 发布服务器,必须指定 destination_db。对于非 SQL Server 订阅服务器,应指定 destination_db 的值(默认目标)。

  • [ @sync\_type=\] 'sync_type'
    订阅的同步类型。sync_type 的数据类型为 nvarchar(255),可以为以下值之一:

    说明

    none

    订阅服务器已包含发布表的架构和初始数据。

    注意注意
    已不推荐使用此选项。请改用仅支持复制。

    automatic(默认值)

    已发布表的架构和初始数据将首先传输到订阅服务器。

    replication support only

    如果需要,在项目的订阅服务器上自动生成支持更新订阅的自定义存储过程和触发器。假定订阅服务器已拥有已发布表的架构和初始数据。在配置对等事务复制拓扑时,确保该拓扑中所有节点上的数据都相同。有关详细信息,请参阅如何配置对等事务复制(复制 Transact-SQL 编程)

    不支持对非 SQL Server 发布的订阅。

    initialize with backup

    从发布数据库的备份获取发布表的架构和初始数据。假定订阅服务器对发布数据库的备份具有访问权。备份位置和备份媒体类型分别由 backupdevicename 和 backupdevicetype 指定。在使用此选项时,无需在配置期间停止对等事务复制拓扑。

    不支持对非 SQL Server 发布的订阅。

    initialize from lsn

    在向对等事务复制拓扑添加节点时使用。和 @subscriptionlsn 一起使用,以确保将所有相关事务都复制到新节点。假定订阅服务器已拥有已发布表的架构和初始数据。有关详细信息,请参阅如何配置对等事务复制(复制 Transact-SQL 编程)

    注意注意

    始终会传输系统表和数据。

  • [ @status=\] 'status'
    订阅的状态。status 的数据类型为 sysname,其默认值为 NULL。当此参数未显式设置时,复制会自动将其设置为下列值之一。

    说明

    active

    订阅已初始化并可接受更改。如果 sync_type 的值为 none、initialize with backup 或 replication support only,会设置此选项。

    subscribed

    订阅需要进行初始化。如果 sync_type 的值为 automatic,会设置此选项。

  • [ @subscription\_type=\] 'subscription_type'
    订阅的类型。subscription_type 的数据类型为 nvarchar(4),其默认值为 push。可以为 push 或 pull。推送订阅的分发代理驻留在分发服务器上,请求订阅的分发代理驻留在订阅服务器上。subscription_type 可以为 pull,以创建一个可为发布服务器识别的命名请求订阅。有关详细信息,请参阅订阅发布

    注意注意

    匿名订阅无需使用此存储过程。

  • [ @update\_mode=\] 'update_mode'
    更新的类型。update_mode 的数据类型为 nvarchar(30),可以为以下值之一。

    说明

    read only(默认值)

    该订阅是只读的。在订阅服务器上所做的更改不会发送到发布服务器。

    sync tran

    启用对即时更新订阅的支持。Oracle 发布服务器不支持。

    queued tran

    启用排队更新的订阅。可以在订阅服务器上进行数据修改,将其存储在队列中,然后传播到发布服务器。Oracle 发布服务器不支持。

    failover

    将排队更新作为故障转移的情况下启用用于即时更新的订阅。可以在订阅服务器上进行数据修改并立即传播到发布服务器。如果发布服务器与订阅服务器未连接在一起,则可以更改更新模式以便将在订阅服务器上所做的数据修改存储在队列中,直到订阅服务器与发布服务器重新连接在一起。Oracle 发布服务器不支持。

    queued failover

    将订阅启用为排队更新订阅,并允许更改为立即更新模式。在订阅服务器和发布服务器之间建立连接之前,可以在订阅服务器上修改数据,并将数据修改存储在队列中。建立起持续连接后,即可将更新模式更改为立即更新。Oracle 发布服务器不支持。

    请注意,如果要订阅的发布允许 DTS,则值不能为 sync tran 和 queued tran。

  • [ @loopback\_detection=\] 'loopback_detection'
    指定分发代理是否将从订阅服务器发起的事务发送回该订阅服务器。loopback_detection 的数据类型为 nvarchar(5),可以是以下值之一。

    说明

    True

    分发代理不将从订阅服务器上发起的事务发送回该订阅服务器。与双向事务复制一起使用。有关详细信息,请参阅双向事务复制

    False

    分发代理将在订阅服务器上发起的事务发送回订阅服务器。

    NULL(默认值)

    对于 SQL Server 订阅服务器,自动设置为 true,对于非 SQL Server 订阅服务器,则设置为 false。

  • [ @frequency\_type=\] frequency_type
    计划分发任务的频率。 frequency_type 的数据类型为 int,可以为以下值之一。

    说明

    1

    一次

    2

    按需

    4

    每天

    8

    每周

    16

    每月

    32

    “每月”选项相关

    64(默认值)

    自动启动

    128

    重复执行

  • [ @frequency\_interval=\] frequency_interval
    应用到 frequency_type 所设置频率的值。frequency_interval 的数据类型为 int,默认值为 NULL。

  • [ @frequency\_relative\_interval=\] frequency_relative_interval
    分发代理的日期。如果 frequency_type 设置为 32(与“每月”选项相关),则使用此参数。frequency_relative_interval 的数据类型为 int,可以是下列值之一。

    说明

    1

    第一个

    2

    4

    第三个

    8

    第四个

    16

    最后一个

    NULL(默认值)

     

  • [ @frequency\_recurrence\_factor=\] frequency_recurrence_factor
    是 frequency_type 使用的重复因子。frequency_recurrence_factor 的数据类型为 int,默认值为 NULL。

  • [ @frequency\_subday=\] frequency_subday
    在定义的期间内重复计划的时间间隔,单位为分钟。frequency_subday 的数据类型为 int,可以为下列值之一。

    说明

    1

    一次

    2

    第二个

    4

    分钟

    8

    小时

    NULL

     

  • [ @frequency\_subday\_interval=\] frequency_subday_interval
    是 frequency_subday 的时间间隔。frequency_subday_interval 的数据类型为 int,默认值为 NULL。

  • [ @active\_start\_time\_of\_day=\] active_start_time_of_day
    首次计划分发代理的时间,格式为 HHMMSS。active_start_time_of_day 的数据类型为 int,其默认值为 NULL。

  • [ @active\_end\_time\_of\_day=\] active_end_time_of_day
    所计划的停止分发代理的时间,格式为 HHMMSS。active_end_time_of_day 的数据类型为 int,其默认值为 NULL。

  • [ @active\_start\_date=\] active_start_date
    首次计划分发代理的日期,格式为 YYYYMMDD。active_start_date 的数据类型为 int,其默认值为 NULL。

  • [ @active\_end\_date=\] active_end_date
    所计划的停止分发代理的日期,格式为 YYYYMMDD。active_end_date 的数据类型为 int,其默认值为 NULL。

  • [ @optional\_command\_line=\] 'optional_command_line'
    要执行的可选命令提示符。optional_command_line 的数据类型为 nvarchar(4000),默认值为 NULL。

  • [ @reserved=\] 'reserved'
    标识为仅供参考。 不提供支持。 不保证以后的兼容性。

  • [ @enabled\_for\_syncmgr=\] 'enabled_for_syncmgr'
    指定是否可以通过 Microsoft Windows 同步管理器同步订阅。enabled_for_syncmgr 的数据类型为 nvarchar(5),其默认值为 FALSE。如果为 false,则表示订阅没有在 Windows 同步管理器中注册。如果为 true,则表示订阅已向 Windows 同步管理器注册,因而可以在不启动 SQL Server Management Studio 的情况下同步。Oracle 发布服务器不支持。

  • [ @offloadagent= ] 'remote_agent_activation'
    指定可以远程激活代理。remote_agent_activation 的数据类型为 bit,默认值为 0。

    注意注意

    不推荐使用此参数,保留它只是为了让脚本能够向后兼容。

  • [ @offloadserver= ] 'remote_agent_server_name'
    指定要用于远程激活的服务器的网络名称。remote_agent_server_name的数据类型为 sysname,其默认值为 NULL。

  • [ @dts\_package\_name= ] 'dts_package_name'
    指定 Data Transformation Services (DTS) 包的名称。dts_package_name 的数据类型为 sysname,默认值为 NULL。例如,若要指定 DTSPub_Package 包,则该参数将为 @dts\_package\_name = N'DTSPub_Package'。该参数可用于推送订阅。若要将 DTS 包信息添加到请求订阅,请使用 sp_addpullsubscription_agent。

  • [ @dts\_package\_password= ] 'dts_package_password'
    指定包的密码(如果有)。dts_package_password 的数据类型为 sysname,其默认值为 NULL。

    注意注意

    如果指定了 dts_package_name,则必须指定密码。

  • [ @dts\_package\_location= ] 'dts_package_location'
    指定包的位置。dts_package_location 的数据类型为 nvarchar(12),默认值为 DISTRIBUTOR。包的位置可以是 distributor 或 subscriber。

  • [ @distribution\_job\_name= ] 'distribution_job_name'
    标识为仅供参考。 不提供支持。 不保证以后的兼容性。

  • [ @publisher= ] 'publisher'
    指定非 MicrosoftSQL Server 发布服务器。publisher 的数据类型为 sysname,默认值为 NULL。

    注意注意

    不应为 SQL Server 发布服务器指定 publisher。

  • [ @backupdevicetype= ] 'backupdevicetype'
    指定从备份初始化订阅服务器时使用的备份设备的类型。backupdevicetype 的数据类型为 nvarchar(20),可以是以下值之一:

    说明

    logical(默认值)

    备份设备是逻辑设备。

    disk

    备份设备是磁盘驱动器。

    tape

    备份设备是磁带机。

    仅当 sync_method 设置为 initialize_with_backup 时,才会使用 backupdevicetype。

  • [ @backupdevicename= ] 'backupdevicename'
    指定从备份初始化订阅服务器时使用的设备的名称。backupdevicename 的数据类型为 nvarchar(1000),其默认值为 NULL。

  • [ @mediapassword= ] 'mediapassword'
    指定媒体集的密码(如果媒体在格式化时设置了密码)。mediapassword 的数据类型为 sysname,其默认值为 NULL。

    注意注意

    后续版本的 Microsoft SQL Server 将删除该功能。 请避免在新的开发工作中使用该功能,并着手修改当前还在使用该功能的应用程序。

  • [ @password= ] 'password'
    指定备份的密码(如果备份在创建时设置了密码)。password的数据类型为 sysname,其默认值为 NULL。

  • [ @fileidhint= ] fileidhint
    标识要还原的备份集的序号值。fileidhint 的数据类型为 int,其默认值为 NULL。

  • [ @unload= ] unload
    指定在从备份进行的初始化完成后是否应卸载磁带备份设备。unload 的数据类型为 bit,其默认值为 1。1 指定磁带应卸载。仅当 backupdevicetype 为 tape 时,才应使用 unload。

  • [ @subscriptionlsn= ] subscriptionlsn
    指定订阅应从其开始将更改传递给对等事务复制拓扑中的节点的日志序列号 (LSN)。与等于 initialize from lsn 的 @sync\_type 值一起使用,确保将所有相关事务都复制到新节点。有关详细信息,请参阅如何配置对等事务复制(复制 Transact-SQL 编程)

  • [ @subscriptionstreams = ] subscriptionstreams
    每个分发代理允许的连接数,用于将成批更改并行应用于订阅服务器,同时保留在使用单线程时具有的多种事务特征。subscriptionstreams 的数据类型为 tinyint,默认值为 NULL。支持使用 1 到 64 之间的值。非 SQL Server 订阅服务器、Oracle 发布服务器或对等订阅不支持此参数。

  • [ @subscriber\_type=\] subscriber_type
    订阅服务器的类型。subscriber_type 的数据类型为 tinyint,可以是下列值之一:

    说明

    0(默认值)

    SQL Server 订阅服务器

    1

    ODBC 数据源服务器

    2

    Microsoft Jet 数据库

    3

    OLE DB 访问接口

返回代码值

0(成功)或 1(失败)

注释

sp_addsubscription 用于快照复制和事务复制。

当 sysadmin 固定服务器角色的成员执行 sp_addsubscription 以创建推送订阅时,将隐式创建分发代理作业并将在 SQL Server 代理服务帐户下运行该作业。建议您执行 sp_addpushsubscription_agent,并为 @job\_login@job\_password 的指定特定于代理的其他 Windows 帐户的凭据。有关详细信息,请参阅复制代理安全性模式

sp_addsubscription 禁止 ODBC 和 OLE DB 订阅服务器访问下列发布:

  • 在对 sp_addpublication 的调用中使用本机 sync_method 创建的发布。

  • 发布包含的项目是使用 sp_addarticle 存储过程添加的,并且该存储过程的 pre_creation_cmd 参数的值设置为 3(截断)。

  • 尝试将 update_mode 设置为 sync tran 的发布。

  • 含有被配置为使用参数化语句的项目的发布。

另外,如果发布的 allow_queued_tran 选项设置为 true(这样会使得订阅服务器上更改进行排队,直到这些更改可应用到发布服务器为止),则项目内的时间戳列的脚本数据类型会编写为 timestamp,且对该列的更改会发送至订阅服务器。订阅服务器将生成并更新时间戳列值。对于 ODBC 或 OLE DB 订阅服务器,如果尝试订阅其 allow_queued_tran 选项设置为 true 且包含的项目带有时间戳列的发布,则 sp_addsubscription 将失败。

如果订阅没有使用 DTS 包,则它无法订阅设置为 allow_transformable_subscriptions 的发布。如果来自发布的表需要同时复制到 DTS 订阅和非 DTS 订阅,则必须创建两种单独的发布:每种发布分别针对一种订阅类型。

示例

-- This script uses sqlcmd scripting variables. They are in the form
-- $(MyVariable). For information about how to use scripting variables  
-- on the command line and in SQL Server Management Studio, see the 
-- "Executing Replication Scripts" section in the topic
-- "Programming Replication Using System Stored Procedures".

DECLARE @publication AS sysname;
DECLARE @subscriber AS sysname;
DECLARE @subscriptionDB AS sysname;
SET @publication = N'AdvWorksProductTran';
SET @subscriber = $(SubServer);
SET @subscriptionDB = N'AdventureWorksReplica';

--Add a push subscription to a transactional publication.
USE [AdventureWorks]
EXEC sp_addsubscription 
  @publication = @publication, 
  @subscriber = @subscriber, 
  @destination_db = @subscriptionDB, 
  @subscription_type = N'push';

--Add an agent job to synchronize the push subscription.
EXEC sp_addpushsubscription_agent 
  @publication = @publication, 
  @subscriber = @subscriber, 
  @subscriber_db = @subscriptionDB, 
  @job_login = $(Login), 
  @job_password = $(Password);
GO

权限

只有 sysadmin 固定服务器角色成员或 db_owner 固定数据库角色成员才能执行 sp_addsubscription。对于请求订阅,在发布访问列表中有登录权的用户可以执行 sp_addsubscription。