sp_addsubscription (Transact-SQL)
适用于： 
SQL Server Azure SQL 数据库
将订阅添加到发布并设置订阅服务器的状态。 此存储过程在发布服务器上对发布数据库执行。
语法
sp_addsubscription
[ @publication = ] N'publication'
[ , [ @article = ] N'article' ]
[ , [ @subscriber = ] N'subscriber' ]
[ , [ @destination_db = ] N'destination_db' ]
[ , [ @sync_type = ] N'sync_type' ]
[ , [ @status = ] N'status' ]
[ , [ @subscription_type = ] N'subscription_type' ]
[ , [ @update_mode = ] N'update_mode' ]
[ , [ @loopback_detection = ] N'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 = ] N'optional_command_line' ]
[ , [ @reserved = ] N'reserved' ]
[ , [ @enabled_for_syncmgr = ] N'enabled_for_syncmgr' ]
[ , [ @offloadagent = ] offloadagent ]
[ , [ @offloadserver = ] N'offloadserver' ]
[ , [ @dts_package_name = ] N'dts_package_name' ]
[ , [ @dts_package_password = ] N'dts_package_password' ]
[ , [ @dts_package_location = ] N'dts_package_location' ]
[ , [ @distribution_job_name = ] N'distribution_job_name' ]
[ , [ @publisher = ] N'publisher' ]
[ , [ @backupdevicetype = ] N'backupdevicetype' ]
[ , [ @backupdevicename = ] N'backupdevicename' ]
[ , [ @mediapassword = ] N'mediapassword' ]
[ , [ @password = ] N'password' ]
[ , [ @fileidhint = ] fileidhint ]
[ , [ @unload = ] unload ]
[ , [ @subscriptionlsn = ] subscriptionlsn ]
[ , [ @subscriptionstreams = ] subscriptionstreams ]
[ , [ @subscriber_type = ] subscriber_type ]
[ , [ @memory_optimized = ] memory_optimized ]
[ ; ]
参数
[ @publication = ] N'publication'
发布的名称。 @publication 为 sysname，无默认值。
[ @article = ] N'article'
发布订阅的项目。 @article为 sysname，默认值为 all. 如果 all为该发布中的所有项目添加了订阅。 Oracle 发布服务器仅支持或NULL仅支持值all。
[ @subscriber = ] N'subscriber'
订阅服务器的名称。 @subscriber为 sysname，默认值为 NULL.
注意
可以将服务器名称指定为 <Hostname>,<PortNumber> 默认实例或 <Hostname>\<InstanceName>,<PortNumber> 命名实例。 使用自定义端口在 Linux 或 Windows 上部署 SQL Server 时指定连接的端口号，并禁用浏览器服务。 远程分发服务器的自定义端口号的使用适用于 SQL Server 2019 （15.x） 及更高版本。
[ @destination_db = ] N'destination_db'
要在其中放置复制数据的目标数据库的名称。 @destination_db为 sysname，默认值为 NULL. 当 NULL， @destination_db 设置为发布数据库的名称。 对于 Oracle 发布服务器， 必须指定@destination_db 。 对于非 SQL Server 订阅服务器，请为 @destination_db指定值（默认目标）。
[ @sync_type = ] N'sync_type'
订阅同步类型。 @sync_type 为 nvarchar（255），可以是以下值之一：
| 值 | 说明 |
|---|---|
none 1 |
订阅服务器已包含发布表的架构和初始数据。 |
automatic（默认值） |
已发布表的架构和初始数据将首先传输到订阅服务器。 |
replication support only 2 |
如果需要，在项目的订阅服务器上自动生成支持更新订阅的自定义存储过程和触发器。 假定订阅服务器已拥有已发布表的架构和初始数据。 在配置对等事务复制拓扑时，确保该拓扑中所有节点上的数据都相同。 有关详细信息，请参阅 对等 - 事务复制。 |
initialize with backup 2 |
从发布数据库的备份获取已发布表的架构和初始数据。 假定订阅服务器对发布数据库的备份具有访问权。 备份的备份和媒体类型的位置由 @backupdevicename 和 @backupdevicetype指定。 在使用此选项时，无需在配置期间停止对等事务复制拓扑。 |
initialize from lsn |
将节点添加到对等事务复制拓扑时使用。 和 @subscriptionlsn 一起使用，以确保将所有相关事务都复制到新节点。 假定订阅服务器已拥有已发布表的架构和初始数据。 有关详细信息，请参阅 对等 - 事务复制。 |
1 此选项已弃用。 请改用仅支持复制。
2 不支持订阅非 SQL Server 发布。
注意
始终会传输系统表和数据。
[ @status = ] N'status'
订阅状态。 @status为 sysname，默认值为 NULL. 如果未显式设置此参数，复制会自动将其设置为以下值之一。
| 值 | 说明 |
|---|---|
active |
订阅已初始化并可接受更改。 当@sync_type值为 none、使用备份进行初始化或仅支持复制时，将设置此选项。 |
subscribed |
订阅需要进行初始化。 当@sync_type值自动时，将设置此选项。 |
[ @subscription_type = ] N'subscription_type'
订阅的类型。 @subscription_type为 nvarchar（4），默认值为 push. 可以是 push 或 pull。 推送订阅分发代理驻留在分发服务器上，请求订阅分发代理驻留在订阅服务器上。 @subscription_type可以pull创建发布服务器已知的命名请求订阅。 有关详细信息，请参阅订阅发布。
注意
匿名订阅不需要使用此存储过程。
[ @update_mode = ] N'update_mode'
更新的类型。 @update_mode 为 nvarchar（30），可以是这些值之一。
| 值 | 说明 |
|---|---|
read only（默认值） |
该订阅是只读的。 订阅服务器上的更改不会发送到发布服务器。 |
sync tran |
支持立即更新订阅。 Oracle 发布服务器不支持。 |
queued tran |
支持订阅进行排队更新。 可以在订阅服务器上进行数据修改，将其存储在队列中，然后传播到发布服务器。 Oracle 发布服务器不支持。 |
failover |
将排队更新作为故障转移的情况下启用用于即时更新的订阅。 可以在订阅服务器上进行数据修改并立即传播到发布服务器。 如果发布服务器和订阅服务器未连接，则可以更改更新模式，以便订阅服务器上所做的数据修改存储在队列中，直到订阅服务器和发布服务器重新连接。 Oracle 发布服务器不支持。 |
queued failover |
支持将订阅作为排队更新订阅，并允许更改为立即更新模式。 在订阅服务器和发布服务器之间建立连接之前，可以在订阅服务器上修改数据，并将数据修改存储在队列中。 建立起持续连接后，即可将更新模式更改为立即更新。 Oracle 发布服务器不支持。 |
如果订阅的发布允许 DTS，则queued tran不允许这些值sync tran。
[ @loopback_detection = ] N'loopback_detection'
指定分发代理是否将从订阅服务器发起的事务发送回该订阅服务器。 @loopback_detection为 nvarchar（5），可以是这些值之一。
| 值 | 说明 |
|---|---|
true |
分发代理不会将源自订阅服务器的事务发送回订阅服务器。 与双向事务复制一起使用。 有关详细信息，请参阅 Bidirectional Transactional Replication。 |
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 |
Last |
NULL（默认值） |
[ @frequency_recurrence_factor = ] frequency_recurrence_factor
@frequency_type使用的重复因子。 @frequency_recurrence_factor为 int，默认值为 NULL.
[ @frequency_subday = ] frequency_subday
在定义的时间段内重新安排的频率（以分钟为单位）。 @frequency_subday 为 int，可以是以下值之一。
| 值 | 说明 |
|---|---|
1 |
一次 |
2 |
Second |
4 |
Minute |
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 = ] N'optional_command_line'
要执行的可选命令提示符。 @optional_command_line 为 nvarchar（4000），默认值为 NULL.
[ @reserved = ] N'reserved'
标识为仅供参考。 不支持。 不保证以后的兼容性。
[ @enabled_for_syncmgr = ] N'enabled_for_syncmgr'
是否可以通过 Windows 同步管理器同步订阅。 @enabled_for_syncmgr为 nvarchar（5），默认值NULL与 falsefalse订阅未注册到 Windows 同步管理器。 如果 true订阅已注册到 Windows 同步管理器，并且可以在不启动 SQL Server Management Studio 的情况下进行同步。 Oracle 发布服务器不支持。
[ @offloadagent = ] offloadagent
指定可远程激活代理。 @offloadagent为位，默认值为 0.
注意
不推荐使用此参数，保留它只是为了让脚本能够向后兼容。
[ @offloadserver = ] N'offloadserver'
指定用于远程激活的服务器的网络名称。 @offloadserver为 sysname，默认值为 NULL.
[ @dts_package_name = ] N'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 = ] N'dts_package_password'
指定包的密码（如果有）。 @dts_package_password为 sysname，默认值为 NULL.
注意
如果 指定了@dts_package_name ，则必须指定密码。
[ @dts_package_location = ] N'dts_package_location'
指定包位置。 @dts_package_location为 nvarchar（12），默认值NULL与 distributordistributor 或 subscriber。
[ @distribution_job_name = ] N'distribution_job_name'
标识为仅供参考。 不支持。 不保证以后的兼容性。
[ @publisher = ] N'publisher'
指定非 SQL Server 发布服务器。 @publisher为 sysname，默认值为 NULL.
注意
不应为 SQL Server 发布服务器指定@publisher 。
[ @backupdevicetype = ] N'backupdevicetype'
指定从备份初始化订阅服务器时使用的备份设备的类型。 @backupdevicetype 为 nvarchar（20），可以是以下值之一：
| 值 | 说明 |
|---|---|
logical（默认值） |
备份设备是逻辑设备 |
disk |
备份设备是磁盘驱动器 |
tape |
备份设备是磁带机。 |
url |
备份设备是 URL |
仅当@sync_method设置为initialize_with_backup时，才使用@backupdevicetype。
[ @backupdevicename = ] N'backupdevicename'
指定从备份初始化订阅服务器时使用的设备的名称。 @backupdevicename为 nvarchar（1000），默认值为 NULL.
[ @mediapassword = ] N'mediapassword'
指定介质集的密码（如果在格式化介质时设置了密码）。 @mediapassword为 sysname，默认值为 NULL.
注意
在 SQL Server的未来版本中将删除此功能。 请避免在新的开发工作中使用该功能，并着手修改当前还在使用该功能的应用程序。
[ @password = ] N'password'
指定备份的密码（如果在创建备份时设置了密码）。 @password为 sysname，默认值为 NULL.
[ @fileidhint = ] fileidhint
标识要还原的备份集的序号值。 @fileidhint为 int，默认值为 NULL.
[ @unload = ] unload
指定在从备份进行的初始化完成后是否应取出磁带备份设备。 @unload 为 位，默认值 1指定应卸载磁带。 @unload仅在@backupdevicetype为tape时使用。
[ @subscriptionlsn = ] subscriptionlsn
指定订阅应从其开始将更改传递给对等事务复制拓扑中的节点的日志序列号 (LSN)。 @subscriptionlsn 为 binary（10），默认值为 NULL. 与@sync_type值initialize from lsn一起使用，以确保所有相关事务都复制到新节点。 有关详细信息，请参阅 对等 - 事务复制。
[ @subscriptionstreams = ] subscriptionstreams
每个分发代理允许的连接数并行应用于订阅服务器，同时维护使用单个线程时存在的许多事务特征。 @subscriptionstreams为 tinyint，默认值为 NULL. 支持一164系列值。 非 SQL Server 订阅服务器、Oracle 发布服务器或对等订阅不支持此参数。 每当 使用@subscriptionstreams 时，表中会添加 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 访问接口 |
[ @memory_optimized = ] memory_optimized
指示订阅支持内存优化表。 @memory_optimized 为 位，默认值为 0 false。 1 （true） 表示订阅支持内存优化表。
返回代码值
0（成功）或 1（失败）。
注解
sp_addsubscription 用于快照复制和事务复制。
当由 sysadmin 固定服务器角色的成员执行以创建推送订阅时sp_addsubscription，将隐式创建分发代理作业，并在SQL Server 代理服务帐户下运行。 我们建议你执行 sp_addpushsubscription_agent ，并为和指定其他特定于代理的 Windows 帐户 @job_login 的 @job_password凭据。 有关详细信息，请参阅 复制代理安全模式。
sp_addsubscription 阻止 ODBC 和 OLE DB 订阅服务器访问下列发布的发布：
是在调用sp_addpublication时使用本机@sync_method创建的。
包含已添加到发布中的项目，其中包含具有@pre_creation_cmd参数值为 3（截断）的sp_addarticle存储过程。
尝试将@update_mode设置为
sync tran.含有被配置为使用参数化语句的项目的发布。
此外，如果发布具有 设置为 true @allow_queued_tran 选项（这允许在订阅服务器上应用更改之前在订阅服务器上排队），则文章中的时间戳列将脚本化为 时间戳，并且该列的更改将发送到订阅服务器。 订阅服务器将生成并更新时间戳列值。 对于 ODBC 或 OLE DB 订阅服务器， sp_addsubscription 如果尝试订阅已 @allow_queued_tran 设置为 true 的发布，并且其中包含时间戳列的项目，则失败。
如果订阅不使用 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'AdventureWorks2022Replica';
--Add a push subscription to a transactional publication.
USE [AdventureWorks2022]
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