sp_addsubscription （Transact-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），可以是下列其中一個值：
| 值 | Description |
|---|---|
none1 |
訂閱者已經有已發行數據表的架構和初始數據。 |
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。 如果未明確設定此參數，複寫會自動將其設定為下列其中一個值。
| 值 | Description |
|---|---|
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），而且可以是下列其中一個值。
| 值 | Description |
|---|---|
read only (預設值) |
訂閱是唯讀的。 訂閱者端的變更不會傳送至發行者。 |
sync tran |
啟用立即更新訂閱的支援。 Oracle 發行者不支援。 |
queued tran |
啟用佇列更新的訂用帳戶。 您可以在訂閱者端進行數據修改、儲存在佇列中，然後傳播至發行者。 Oracle 發行者不支援。 |
failover |
啟用訂閱，以佇列更新作為故障轉移進行立即更新。 您可以在訂閱者端進行數據修改，並立即傳播至發行者。 如果發行者和訂閱者未連線，可以變更更新模式，以便在訂閱者端進行的數據修改會儲存在佇列中，直到訂閱者和發行者重新連線為止。 Oracle 發行者不支援。 |
queued failover |
讓訂用帳戶成為佇列更新訂閱，並能夠變更為立即更新模式。 您可以在訂閱者端進行數據修改，並儲存在佇列中，直到訂閱者與發行者之間建立連接為止。 建立連續連線時，更新模式可以變更為立即更新。 Oracle 發行者不支援。 |
如果訂閱的發行集允許 DTS，則不允許和 sync tran queued tran 值。
[ @loopback_detection = ] N'loopback_detection'
指定 散發代理程式 是否將源自訂閱者的交易傳送回訂閱者。 @loopback_detection為 nvarchar（5），而且可以是下列其中一個值。
| 值 | Description |
|---|---|
true |
散發代理程式 不會將源自訂閱者的交易傳送回訂閱者。 與雙向事務複製搭配使用。 如需詳細資訊，請參閱 Bidirectional Transactional Replication。 |
false |
散發代理程式 將源自訂閱者的交易傳送回訂閱者。 |
NULL (預設值) |
針對 SQL Server 訂閱者自動設定為 true，非 SQL Server 訂閱者會自動設定為 false。 |
[ @frequency_type = ] frequency_type
排程散發工作的頻率。 @frequency_type為 int，而且可以是下列其中一個值。
| 值 | Description |
|---|---|
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，而且可以是下列其中一個值。
| 值 | Description |
|---|---|
1 |
第一個 |
2 |
Second |
4 |
Third |
8 |
第四個 |
16 |
最後一個 |
NULL (預設值) |
[ @frequency_recurrence_factor = ] frequency_recurrence_factor
@frequency_type所使用的週期因數。 @frequency_recurrence_factor為 int，預設值為 NULL。
[ @frequency_subday = ] frequency_subday
在定義的期間重新排程的頻率，以分鐘為單位。 @frequency_subday為 int，而且可以是下列其中一個值。
| 值 | Description |
|---|---|
1 |
一次 |
2 |
第二個 |
4 |
Minute |
8 |
Hour |
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 Synchronization Manager 同步處理訂閱。 @enabled_for_syncmgr是 nvarchar（5），預設值NULL為 ，其與 false相同。 如果 false為 ，則不會向 Windows Synchronization Manager 註冊訂用帳戶。 如果 true為 ，則訂閱會向 Windows Synchronization Manager 註冊，而且可以在不啟動 SQL Server Management Studio 的情況下進行同步處理。 Oracle 發行者不支援。
[ @offloadagent = ] offloadagent
指定可以從遠端啟動代理程式。 @offloadagent為 bit，預設值為 0。
注意
此參數已被取代，而且只會維護腳本的回溯相容性。
[ @offloadserver = ] N'offloadserver'
指定要用於遠端啟用的伺服器網路名稱。 @offloadserver為 sysname，預設值為 NULL。
[ @dts_package_name = ] N'dts_package_name'
指定資料轉換服務 （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為 ，其與 distributor相同。 封裝的位置可以是 distributor 或 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），而且可以是下列其中一個值：
| 值 | Description |
|---|---|
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為 bit，預設值1為 ，指定應該卸載磁帶。 只有在 @backupdevicetype 為 tape時，才會使用@unload。
[ @subscriptionlsn = ] subscriptionlsn
指定訂閱應該開始將變更傳遞至點對點事務複製拓撲中節點的記錄序號 （LSN）。 @subscriptionlsn為 binary（10），預設值為 NULL。 搭配 @sync_type 值 initialize from lsn 使用，以確保所有相關交易都會複寫到新的節點。 如需詳細資訊，請參閱 點對點 - 事務複製。
[ @subscriptionstreams = ] subscriptionstreams
每個 散發代理程式 允許的連線數目，以平行方式將變更批次套用至訂閱者，同時維護使用單個線程時存在的許多交易特性。 @subscriptionstreams為 tinyint，預設值為 NULL。 支援從 1 到 64 的值範圍。 非 SQL Server 訂閱者、Oracle 發行者或點對點訂閱不支援此參數。 每當 使用@subscriptionstreams 時，數據表中 msreplication_subscriptions 就會新增其他數據列（每個數據流一個數據列），並將 agent_id 設定為 NULL。
注意
訂用帳戶數據流不適用於設定為傳遞 Transact-SQL 的文章。 若要使用訂閱數據流，請設定發行項來改為傳遞預存過程調用。
[ @subscriber_type = ] subscriber_type
訂閱者的類型。 @subscriber_type為 tinyint，而且可以是下列其中一個值。
| 值 | Description |
|---|---|
0 (預設值) |
SQL Server 訂閱者 |
1 |
ODBC 資料源伺服器 |
2 |
Microsoft Jet 資料庫 |
3 |
OLE DB 提供者 |
[ @memory_optimized = ] memory_optimized
表示訂用帳戶支援記憶體優化數據表。 @memory_optimized為 bit，預設值0為 （false）。 1 （true） 表示訂閱支援記憶體優化數據表。
傳回碼值
0 (成功) 或 1 (失敗)。
備註
sp_addsubscription 用於快照式複寫和事務複製。
當sp_addsubscription由系統管理員固定伺服器角色的成員執行以建立發送訂閱時，會隱含建立 散發代理程式 作業，並在 SQL Server Agent 服務帳戶下執行。 建議您執行 sp_addpushsubscription_agent，並針對 和 @job_password指定不同代理程式特定 Windows 帳戶@job_login的認證。 如需詳細資訊，請參閱 複寫代理程式安全性模型。
sp_addsubscription 防止 ODBC 和 OLE DB 訂閱者存取發行集：
已在呼叫 sp_addpublication 中使用原生@sync_method建立。
包含已新增至發行集的發行項，其中包含具有 @pre_creation_cmd 參數值為 3 的預存程式sp_addarticle預存程式（截斷）。
試著將 @update_mode 設定為
sync tran。將發行項設定為使用參數化語句。
此外，如果發行集的 [@allow_queued_tran ] 選項設定為 true（這會啟用訂閱者端的變更佇列，直到可以在發行者端套用變更為止），發行項中的時間戳數據行就會編寫成 時間戳，而該數據行的變更會傳送至訂閱者。 訂閱者會產生並更新時間戳數據行值。 若為 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) 固定伺服器角色成員的 Windows 帳戶底下執行。 當 [@sync_type] 選項設定為 Automatic時，不需要任何特殊的記錄讀取器代理程序動作。
權限
只有系統管理員固定伺服器角色或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