sp_addsubscription (Transact-SQL)

适用于:yesSQL Server(所有受支持的版本)YesAzure SQL 数据库

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

Topic link iconTransact-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 ]  
    [ , [ @memory_optimized = ] memory_optimized ]  

参数

[ @publication=] 'publication'
发布的名称。 发布sysname,没有默认值。

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

[ @subscriber=] “订阅者
订阅服务器的名称。 订阅服务器sysname,默认值为 NULL。

注意

服务器名称可以指定为 <Hostname>,<PortNumber>. 使用自定义端口在 Linux 或 Windows 上部署 SQL Server 时,可能需要为连接指定端口号,并禁用浏览器服务。 远程分发服务器的自定义端口号仅适用于 SQL Server 2019。

[ @destination_db=] “destination_db
用于放置复制数据的目标数据库的名称。 destination_dbsysname,默认值为 NULL。 如果为 NULL, destination_db 设置为发布数据库的名称。 对于 Oracle 发布服务器,必须指定 destination_db 。 对于非 SQL Server 订阅服务器,请为 destination_db指定 (默认目标) 的值。

[ @sync_type=] “sync_type
订阅同步类型。 sync_typenvarchar (255) ,可以是以下值之一:

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

注意:此选项已弃用。 请改用仅支持复制。
automatic(默认值) 已发布表的架构和初始数据将首先传输到订阅服务器。
replication support only 如果需要,在项目的订阅服务器上自动生成支持更新订阅的自定义存储过程和触发器。 假定订阅服务器已拥有已发布表的架构和初始数据。 在配置对等事务复制拓扑时,确保该拓扑中所有节点上的数据都相同。 有关详细信息,请参阅 Peer-to-Peer Transactional Replication

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

不支持对非 SQL Server 发布的订阅。
initialize from lsn 在向对等事务复制拓扑添加节点时使用。 和 @subscriptionlsn 一起使用,以确保将所有相关事务都复制到新节点。 假定订阅服务器已拥有已发布表的架构和初始数据。 有关详细信息,请参阅 Peer-to-Peer Transactional Replication

注意

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

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

说明
活动 订阅已初始化并可接受更改。 当 sync_type 的值为 none、使用备份初始化或仅支持复制时,将设置此选项。
subscribed 订阅需要进行初始化。 当 自动sync_type 的值时,将设置此选项。

[ @subscription_type=] “subscription_type
订阅的类型。 subscription_typenvarchar (4) ,默认为推送。 可以为 push 或 pull。 push 订阅的分发代理位于分发服务器上,pull 订阅的分发代理位于订阅服务器上。 subscription_type 可以拉取,以创建发布服务器已知的命名拉取订阅。 有关详细信息,请参阅订阅发布

注意

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

[ @update_mode=] “update_mode
更新的类型。update_modenvarchar (30) ,可以是其中一个值。

说明
read only(默认值) 该订阅是只读的。 在订阅服务器上所做的更改不会发送到发布服务器。
sync tran 支持立即更新订阅。 Oracle 发布服务器不支持。
queued tran 支持订阅进行排队更新。 可以在订阅服务器上进行数据修改,将其存储在队列中,然后传播到发布服务器。 Oracle 发布服务器不支持。
故障转移 将排队更新作为故障转移的情况下启用用于即时更新的订阅。 可以在订阅服务器上进行数据修改并立即传播到发布服务器。 如果发布服务器与订阅服务器未连接在一起,则可以更改更新模式以便将在订阅服务器上所做的数据修改存储在队列中,直到订阅服务器与发布服务器重新连接在一起。 Oracle 发布服务器不支持。
queued failover 支持将订阅作为排队更新订阅,并允许更改为立即更新模式。 在订阅服务器和发布服务器之间建立连接之前,可以在订阅服务器上修改数据,并将数据修改存储在队列中。 建立起持续连接后,即可将更新模式更改为立即更新。 Oracle 发布服务器不支持。

请注意,如果订阅了允许 DTS 的发布,则不允许值 synctran 和 queued tran。

[ @loopback_detection=] “loopback_detection
指定分发代理是否将从订阅服务器发起的事务发送回该订阅服务器。 loopback_detectionnvarchar (5) ,可以是其中一个值。

说明
分发代理不将从订阅服务器上发起的事务发送回该订阅服务器。 与双向事务复制一起使用。 有关详细信息,请参阅 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 First
2 Second
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 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=] “optional_command_line
要执行的可选命令提示符。 optional_command_linenvarchar (4000) ,默认值为 NULL。

[ @reserved=] 'reserved'

标识为仅供参考。 不支持。 不保证以后的兼容性。

[ @enabled_for_syncmgr=] “enabled_for_syncmgr
是否可以通过 Microsoft Windows 同步管理器同步订阅。 enabled_for_syncmgrnvarchar (5) ,默认值为 FALSE。 如果为 false,则表示订阅没有在 Windows 同步管理器中注册。 如果为 true,则订阅已注册到 Windows 同步管理器,无需启动 SQL Server Management Studio 即可进行同步。 Oracle 发布服务器不支持。

[ @offloadagent= ] “remote_agent_activation
指定可远程激活代理。 remote_agent_activation ,默认值为 0。

注意

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

[ @offloadserver= ] “remote_agent_server_name
指定用于远程激活的服务器的网络名称。 remote_agent_server_namesysname,默认值为 NULL。

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

[ @dts_package_password= ] “dts_package_password
指定用于包的密码(如果有)。 dts_package_passwordsysname ,默认值为 NULL。

注意

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

[ @dts_package_location= ] “dts_package_location
指定包位置。 dts_package_locationnvarchar (12) ,默认为分发服务器。 包的位置可以是 distributor 或 subscriber。

[ @distribution_job_name= ] “distribution_job_name

标识为仅供参考。 不支持。 不保证以后的兼容性。

[ @publisher= ] 'publisher'
指定非 Microsoft SQL Server 发布服务器。 publishersysname,默认值为 NULL。

注意

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

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

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

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

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

[ @mediapassword= ] 'mediapassword'
指定介质集的密码(如果在格式化介质时设置了密码)。 mediapasswordsysname,默认值为 NULL。

注意

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

[ ] @password= 'password'
指定备份的密码(如果在创建备份时设置了密码)。 passwordsysname,默认值为 NULL。

[ @fileidhint= ] fileidhint
标识要还原的备份集的序号值。 fileidhintint,默认值为 NULL。

[ @unload= ] 卸载
指定在从备份进行的初始化完成后是否应取出磁带备份设备。 unload,默认值为 1。 1 指定应取出磁带。 backupdevicetype 为磁带时,才使用 unload。

[ @subscriptionlsn= ] subscriptionlsn
指定订阅应从其开始将更改传递给对等事务复制拓扑中的节点的日志序列号 (LSN)。 与 lsn 中的初始化值一 @sync_type 起使用,以确保所有相关事务都复制到新节点。 有关详细信息,请参阅 Peer-to-Peer Transactional Replication

[ @subscriptionstreams= ] subscriptionstreams
每个分发代理允许的连接数,用于将成批更改并行应用于订阅服务器,同时保留在使用单线程时具有的多种事务特征。 subscriptionstreamstinyint,默认值为 NULL。 支持使用 1 到 64 之间的值。 非 SQL Server 订阅服务器、Oracle 发布服务器或对等订阅不支持此参数。 每当使用订阅流时,都会在 msreplication_subscriptions 表中添加附加行(每个流一行),且 agent_id 设置为 NULL。

注意

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

[ ] @subscriber_type=subscriber_type
订阅服务器的类型。 subscriber_typetinyint,可以是其中一个值。

说明
0(默认值) SQL Server 订阅服务器
1 ODBC 数据源服务器
2 Microsoft Jet 数据库
3 OLE DB 访问接口

[ @memory_optimized=] memory_optimized
指示订阅支持内存优化表。 memory_optimized,其中 1 等于 true (订阅支持内存优化表) 。

返回代码值

0(成功)或 1(失败)

备注

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

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

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

  • 是在调用sp_addpublication时使用本机sync_method创建的。

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

  • 尝试将 update_mode 设置为同步 tran。

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

此外,如果发布具有 allow_queued_tran 选项设置为 true (,这将在订阅服务器上对更改进行排队,直到可以在发布服务器) 应用更改,则文章中的时间戳列将脚本化为 时间戳,并将该列的更改发送到订阅服务器。 订阅服务器将生成并更新时间戳列值。 对于 ODBC 或 OLE DB 订阅服务器,如果尝试 订阅allow_queued_tran设置为 true 且包含时间戳列的项目,则sp_addsubscription失败。

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

选择 sync_type 选项 replication support onlyinitialize with backupinitialize 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

另请参阅

创建推送订阅
为非 SQL Server 订阅服务器创建订阅
订阅发布
sp_addpushsubscription_agent (Transact-SQL)
sp_changesubstatus (Transact-SQL)
sp_dropsubscription (Transact-SQL)
sp_helpsubscription (Transact-SQL)
系统存储过程 (Transact-SQL)