sp_addsubscription (Transact-SQL)

项目
05/08/2013

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

语法

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 指定 (default destination) 值。

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

none

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

注意
已不推荐使用此选项。请改用 replication support only。

automatic（默认值）

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

replication support only

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

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

initialize with backup

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

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

initialize from lsn

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

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

[ @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。 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'
指定非 Microsoft SQL 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 值一起使用，确保将所有相关事务都复制到新节点。有关详细信息，请参阅对等事务复制。
[ @subscriptionstreams= ] subscriptionstreams
每个分发代理允许的连接数，用于将成批更改并行应用于订阅服务器，同时保留在使用单线程时具有的多种事务特征。 subscriptionstreams 的数据类型为 tinyint，默认值为 NULL。支持使用 1 到 64 之间的值。非 SQL Server 订阅服务器、Oracle 发布服务器和对等订阅均不支持此参数。每当使用订阅流时，都会在 msreplication_subscriptions 表中添加附加行（每个流一行），且 agent_id 设置为 NULL。

注意

订阅流不适用于配置为传递 Transact-SQL 的项目。若要使用订阅流，请改将项目配置为传递存储过程调用。
[ @subscriber\_type=\] subscriber_type
订阅服务器的类型。 subscriber_type 的数据类型为 tinyint，可以为下列值之一。

值

说明

0（默认值）

SQL Server 订阅服务器

1

ODBC 数据源服务器

2

Microsoft Jet 数据库

3

OLE DB 访问接口

值	说明
1	一次
2	按需
4	每天
8	每周
16	每月
32	与“每月”选项相关
64（默认值）	自动启动
128	重复执行

值	说明
1	第一个
2	第二次
4	第三次
8	第四次
16	最后一次
NULL（默认值）

值	说明
1	一次
2	秒
4	分钟
8	小时
NULL

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

注意
如果指定了 dts_package_name，则必须指定密码。

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

值	说明
logical（默认值）	备份设备是逻辑设备。
disk	备份设备是磁盘驱动器。
tape	备份设备是磁带机。

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

注意
订阅流不适用于配置为传递 Transact-SQL 的项目。若要使用订阅流，请改将项目配置为传递存储过程调用。

值	说明
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 订阅，则必须创建两种单独的发布：每种发布分别针对一种订阅类型。

选择 sync_type 选项 replication support only、initialize with backup 或 initialize from lsn 时，日志读取器代理必须在执行 sp_addsubscription 后运行，以便将设置脚本写入分发数据库。日志读取器代理必须在作为 sysadmin 固定服务器角色成员的帐户下运行。将 sync_type 选项设置为 Automatic 时，不需要执行任何特殊日志读取器代理操作。

权限

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

示例

-- 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'AdventureWorks2012Replica';

--Add a push subscription to a transactional publication.
USE [AdventureWorks2012]
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