sp_addmergepublication (Transact-SQL)

适用于： SQL Server Azure SQL 托管实例

创建新合并发布。 此存储过程针对发布服务器上要发布的数据库执行。

Transact-SQL 语法约定

语法

sp_addmergepublication
    [ @publication = ] N'publication'
    [ , [ @description = ] N'description' ]
    [ , [ @retention = ] retention ]
    [ , [ @sync_mode = ] N'sync_mode' ]
    [ , [ @allow_push = ] N'allow_push' ]
    [ , [ @allow_pull = ] N'allow_pull' ]
    [ , [ @allow_anonymous = ] N'allow_anonymous' ]
    [ , [ @enabled_for_internet = ] N'enabled_for_internet' ]
    [ , [ @centralized_conflicts = ] N'centralized_conflicts' ]
    [ , [ @dynamic_filters = ] N'dynamic_filters' ]
    [ , [ @snapshot_in_defaultfolder = ] N'snapshot_in_defaultfolder' ]
    [ , [ @alt_snapshot_folder = ] N'alt_snapshot_folder' ]
    [ , [ @pre_snapshot_script = ] N'pre_snapshot_script' ]
    [ , [ @post_snapshot_script = ] N'post_snapshot_script' ]
    [ , [ @compress_snapshot = ] N'compress_snapshot' ]
    [ , [ @ftp_address = ] N'ftp_address' ]
    [ , [ @ftp_port = ] ftp_port ]
    [ , [ @ftp_subdirectory = ] N'ftp_subdirectory' ]
    [ , [ @ftp_login = ] N'ftp_login' ]
    [ , [ @ftp_password = ] N'ftp_password' ]
    [ , [ @conflict_retention = ] conflict_retention ]
    [ , [ @keep_partition_changes = ] N'keep_partition_changes' ]
    [ , [ @allow_subscription_copy = ] N'allow_subscription_copy' ]
    [ , [ @allow_synctoalternate = ] N'allow_synctoalternate' ]
    [ , [ @validate_subscriber_info = ] N'validate_subscriber_info' ]
    [ , [ @add_to_active_directory = ] N'add_to_active_directory' ]
    [ , [ @max_concurrent_merge = ] max_concurrent_merge ]
    [ , [ @max_concurrent_dynamic_snapshots = ] max_concurrent_dynamic_snapshots ]
    [ , [ @use_partition_groups = ] N'use_partition_groups' ]
    [ , [ @publication_compatibility_level = ] N'publication_compatibility_level' ]
    [ , [ @replicate_ddl = ] replicate_ddl ]
    [ , [ @allow_subscriber_initiated_snapshot = ] N'allow_subscriber_initiated_snapshot' ]
    [ , [ @allow_web_synchronization = ] N'allow_web_synchronization' ]
    [ , [ @web_synchronization_url = ] N'web_synchronization_url' ]
    [ , [ @allow_partition_realignment = ] N'allow_partition_realignment' ]
    [ , [ @retention_period_unit = ] N'retention_period_unit' ]
    [ , [ @generation_leveling_threshold = ] generation_leveling_threshold ]
    [ , [ @automatic_reinitialization_policy = ] automatic_reinitialization_policy ]
    [ , [ @conflict_logging = ] N'conflict_logging' ]
[ ; ]

参数

[ @publication = ] N'publication'

要创建的合并发布的名称。 @publication为 sysname，无默认值，不得为关键字ALL。 发布的名称在数据库内必须唯一。

[ @description = ] N'description'

发布说明。 @description 为 nvarchar（255），默认值为 NULL.

[ @retention = ] 保留期

保留期（以保留期单位为单位），保存给定 @publication的更改。 @retention为 int，默认值为 14. 保留期单位由 @retention_period_unit定义。 如果订阅未在保留期内同步，并且其收到的挂起更改会通过分发服务器的清理操作删除，则订阅将过期，并且必须重新初始化。 允许的最大保持期为当前日期到 9999 年 12 月 31 日之间的天数。

注意

合并发布的保持期具有 24 小时的宽限期，以适应处于不同时区中的订阅服务器。 例如，如果将保持期设置为 1 天，则实际的保持期为 48 小时。

[ @sync_mode = ] N'sync_mode'

订阅服务器到发布的初始同步模式。 @sync_mode为 nvarchar（10），可以是以下值之一。

值	说明
native（默认值）	生成所有表的本机模式大容量复制程序输出。
character	生成所有表的字符模式大容量复制程序输出。 支持 SQL Server Compact 和非 SQL Server 订阅服务器所必需的。

[ @allow_push = ] N'allow_push'

指定是否可为给定发布创建推入订阅。 @allow_push 为 nvarchar（5），默认值 true为允许发布上的推送订阅。

[ @allow_pull = ] N'allow_pull'

指定是否可为给定发布创建拉出订阅。 @allow_pull 为 nvarchar（5），默认值 true为允许对发布请求订阅。 必须指定 true 才能支持 SQL Server Compact 订阅服务器。

[ @allow_anonymous = ] N'allow_anonymous'

指定是否可为给定发布创建匿名订阅。 @allow_anonymous为 nvarchar（5），默认值true为允许发布上的匿名订阅。 若要支持 SQL Server Compact 订阅服务器，必须指定 true。

[ @enabled_for_internet = ] N'enabled_for_internet'

指定是否为 Internet 启用此发布，并确定是否可以使用文件传输协议 (FTP) 将快照文件传输到订阅服务器。 @enabled_for_internet为 nvarchar（5），默认值为 false. 如果 true为发布，则发布同步文件将 C:\Program Files\Microsoft SQL Server\MSSQL\MSSQL.x\Repldata\Ftp 放入目录中。 用户必须创建 Ftp 目录。 如果 false为发布启用了 Internet 访问，则不会启用发布。

[ @centralized_conflicts = ] N'centralized_conflicts'

此参数已弃用，并维护脚本的向后兼容性。 使用 @conflict_logging 指定存储冲突记录的位置。

[ @dynamic_filters = ] N'dynamic_filters'

允许合并发布使用参数化行筛选器。 @dynamic_filters为 nvarchar（5），默认值为 false.

注意

不应指定此参数，而是允许 SQL Server 自动确定是否正在使用参数化行筛选器。 如果为@dynamic_filters指定值true，则必须为项目定义参数化行筛选器。 有关详细信息，请参阅 定义和修改合并项目的参数化行筛选器。

[ @snapshot_in_defaultfolder = ] N'snapshot_in_defaultfolder'

指定快照文件是否存储在默认文件夹中。 @snapshot_in_defaultfolder为 nvarchar（5），默认值为 true. 如果 true，可以在默认文件夹中找到快照文件。 如果false快照文件存储在由@alternate_snapshot_folder指定的备用位置。 备用位置可以位于另一台服务器、网络驱动器或可移动媒体（如可移动磁盘）上。 也可以将快照文件保存到文件传输协议 (FTP) 站点以供订阅方以后检索。 此参数可能为 true，但仍具有由@alt_snapshot_folder指定的位置。 此组合指定快照文件存储在默认位置和备用位置。

[ @alt_snapshot_folder = ] N'alt_snapshot_folder'

指定快照的备用文件夹的位置。 @alt_snapshot_folder为 nvarchar（255），默认值为 NULL.

[ @pre_snapshot_script = ] N'pre_snapshot_script'

指定指向文件位置的 .sql 指针。 @pre_snapshot_script 为 nvarchar（255），默认值为 NULL. 合并代理在订阅服务器上应用快照时，在复制的任何对象脚本之前运行预快照脚本。 该脚本将在合并代理连接到订阅数据库时使用的安全上下文中执行。 预快照脚本不会在 SQL Server Compact 订阅服务器上运行。

[ @post_snapshot_script = ] N'post_snapshot_script'

指定指向文件位置的 .sql 指针。 @post_snapshot_script为 nvarchar（255），默认值为 NULL. 当所有其他复制的对象脚本和数据均已在初始同步过程中应用之后，合并代理将运行快照后脚本。 该脚本将在合并代理连接到订阅数据库时使用的安全上下文中执行。 快照后脚本不会在 SQL Server Compact 订阅服务器上运行。

[ @compress_snapshot = ] N'compress_snapshot'

指定写入 @alt_snapshot_folder 位置的快照将压缩为 Microsoft CAB 格式。 @compress_snapshot为 nvarchar（5），默认值为 false.

• false 指定不压缩快照。

• true 指定将压缩快照。

无法压缩大于 2 GB 的快照文件。 压缩的快照文件被解压缩到合并代理所在的位置；一般对压缩的快照使用请求订阅，以便在订阅服务器上解压缩文件。 无法压缩默认文件夹中的快照。 若要支持 SQL Server Compact 订阅服务器，必须指定 false。

[ @ftp_address = ] N'ftp_address'

分发服务器的 FTP 服务的网络地址。 @ftp_address为 sysname，默认值为 NULL. 指定订阅服务器合并代理要选取的发布快照文件的位置。 由于此属性为每个发布存储，因此每个发布可以具有不同的 @ftp_address。 该发布必须支持使用 FTP 来传播快照。

[ @ftp_port = ] ftp_port

分发服务器的 FTP 服务的端口号。 @ftp_port为 int，默认值为 21. 指定发布快照文件所在的位置以供订阅服务器的合并代理挑选。 由于此属性为每个发布存储，因此每个发布可以有自己的 @ftp_port。

[ @ftp_subdirectory = ] N'ftp_subdirectory'

指定如果发布支持使用 FTP 传播快照，则订阅服务器的合并代理可以使用快照文件的位置进行选取。 @ftp_subdirectory为 nvarchar（255），默认值为 ftp. 由于此属性为每个发布存储，因此每个发布可以有自己的 @ftp_subdirctory 或选择没有子目录（用值 NULL 指示）。

在使用参数化筛选器为发布预先生成快照时，需要将每个订阅服务器分区的数据快照置于自己的文件夹中。 使用 FTP 的预先生成快照的目录结构必须为以下结构：

<alternate_snapshot_folder>\ftp\<publisher_publicationDB_publication>\<partitionID>。

注意

上一个示例（尖括号）中的值取决于发布和订阅服务器分区的具体信息。

[ @ftp_login = ] N'ftp_login'

用于连接到 FTP 服务的用户名。 @ftp_login为 sysname，默认值为 anonymous.

[ @ftp_password = ] N'ftp_password'

用于连接到 FTP 服务的用户密码。 @ftp_password为 sysname，默认值为 NULL.

重要

不要使用空白密码。 使用强密码。

[ @conflict_retention = ] conflict_retention

指定保留冲突的保持期（天）。 @conflict_retention为 int，冲突行从冲突表中清除前的默认值14为天。

[ @keep_partition_changes = ] N'keep_partition_changes'

指定在使用预计算分区时是否启用分区更改优化。 @keep_partition_changes为 nvarchar（5），默认值为 true.

• false 表示分区更改未优化，在使用预计算分区时，发送到所有订阅服务器的分区将在分区中的数据更改时进行验证。

• true 表示已优化分区更改，并且仅影响在更改分区中具有行的订阅服务器。

使用预计算分区时，将@use_partition_groups设置为true@keep_partition_changes 。false 有关详细信息，请参阅 参数化筛选器 - 针对预计算分区进行优化。

注意

如果为@keep_partition_changes指定值true，请指定快照代理参数-MaxNetworkOptimization的值1。 有关此参数的详细信息，请参阅复制快照代理。 有关如何指定代理参数的信息，请参阅 复制代理管理。

使用 SQL Server Compact 订阅服务器时， 必须设置@keep_partition_changes 以确保 true 正确传播删除。 设置为 false“设置为”时，订阅服务器可能具有的行数可能超出预期。

[ @allow_subscription_copy = ] N'allow_subscription_copy'

启用或禁用对订阅此发布的订阅数据库的复制功能。 @allow_subscription_copy 为 nvarchar（5），默认值为 false. 要复制的订阅数据库的大小必须小于 2 GB。

[ @allow_synctoalternate = ] N'allow_synctoalternate'

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

[ @validate_subscriber_info = ] N'validate_subscriber_info'

列出在使用参数化行筛选器时用于定义已发布数据的订阅服务器分区的函数。 @validate_subscriber_info为 nvarchar（500），默认值为 NULL. 合并代理利用该信息来验证订阅服务器分区。 例如，如果在 参数化行筛选器中使用SUSER_SNAME ，则参数应为 @validate_subscriber_info=N'SUSER_SNAME()。

注意

不应指定此参数，而是允许 SQL Server 自动确定筛选条件。

[ @add_to_active_directory = ] N'add_to_active_directory'

此参数已弃用，并维护脚本的向后兼容性。 不能再将发布信息添加到 Microsoft Active Directory。

[ @max_concurrent_merge = ] max_concurrent_merge

并发合并进程的最大数目。 @max_concurrent_merge为 int，默认值为 0. 其值 0 表示，在任何给定时间运行的并发合并进程数没有限制。

该属性对可以同时在合并发布上运行的并发合并进程数设置限制。 如果同时计划的合并进程数多于允许运行的值，则会将多余的作业放入队列中，并等待当前正在运行的合并进程完成。

[ @max_concurrent_dynamic_snapshots = ] max_concurrent_dynamic_snapshots

为生成订阅服务器分区的筛选数据快照而可以并发运行的最大快照代理会话数目。 @max_concurrent_dynamic_snapshots为 int，默认值为 0. 如果 0为数字快照会话，则没有限制。 如果计划的快照进程与允许运行的值相同，则会将多余的作业放入队列中，并等待当前正在运行的快照进程完成。

[ @use_partition_groups = ] N'use_partition_groups'

指定应使用预计算分区来优化同步进程。 @use_partition_groups为 nvarchar（5），可以是以下值之一：

值	说明
true	发布使用预计算分区。
false	发布不使用预计算分区。
NULL（默认值）	由系统确定分区策略。

默认情况下，使用预计算分区。 若要避免使用预计算分区， 必须将@use_partition_groups 设置为 false。 当 NULL系统决定是否可以使用预计算分区时。 如果无法使用预计算分区，则此值实际上不会 false 生成任何错误。 在这种情况下， 可以将@keep_partition_changes 设置为 true 提供一些优化。 有关详细信息，请参阅 参数化筛选器 - 参数化行筛选器 和 参数化筛选器 - 针对预计算分区进行优化。

[ @publication_compatibility_level = ] N'publication_compatibility_level'

指示发布的向后兼容性。 @publication_compatibility_level 为 nvarchar（6），可以是以下值之一：

值	版本
90RTM	SQL Server 2005 (9.x)
100RTM	SQL Server 2008 (10.0.x)

[ @replicate_ddl = ] replicate_ddl

指示发布是否支持架构复制。 @replicate_ddl为 int，默认值为 NULL. 1 指示复制在发布服务器上执行的数据定义语言（DDL）语句，并 0 指示不会复制 DDL 语句。 有关详细信息，请参阅对发布数据库进行架构更改。

当 DDL 语句添加列时，将遵循 @replicate_ddl 参数。 当 DDL 语句因以下原因更改或删除列时，将忽略@replicate_ddl 参数。

• 删除列时， sysarticlecolumns 必须更新该列以防止新的 DML 语句包括导致分发代理失败的已删除列。 忽略 @replicate_ddl 参数，因为复制必须始终复制架构更改。

• 更改列时，源数据类型或可为 null 性可能已更改，导致 DML 语句包含可能与订阅服务器上的表不兼容的值。 这种 DML 语句可能导致分发代理失败。 忽略 @replicate_ddl 参数，因为复制必须始终复制架构更改。

• 当 DDL 语句添加新列时， sysarticlecolumns 不包括新列。 DML 语句不会尝试复制新列的数据。 采用该参数，因为复制或不复制 DDL 均可接受。

[ @allow_subscriber_initiated_snapshot = ] N'allow_subscriber_initiated_snapshot'

指示此发布的订阅服务器是否可以启动快照进程来为它们的数据分区生成筛选快照。 @allow_subscriber_initiated_snapshot 为 nvarchar（5），默认值为 false. true 指示订阅服务器可以启动快照过程。

[ @allow_web_synchronization = ] N'allow_web_synchronization'

指定是否为 Web 同步启用此发布。 @allow_web_synchronization为 nvarchar（5），默认值为 false. true 指定可以通过 HTTPS 同步对此发布的订阅。 有关详细信息，请参阅 Web Synchronization for Merge Replication。 若要支持 SQL Server Compact 订阅服务器，必须指定 true。

[ @web_synchronization_url = ] N'web_synchronization_url'

指定用于 Web 同步的 Internet URL 的默认值。 @web_synchronization_url为 nvarchar（500），默认值为 NULL. 如果在执行sp_addmergepullsubscription_agent时未显式设置 Internet URL，则定义默认的 Internet URL。

[ @allow_partition_realignment = ] N'allow_partition_realignment'

确定在发布服务器上对行所做的修改导致该行更改其分区时是否要将删除内容发送到订阅服务器。 @allow_partition_realignment 为 nvarchar（5），默认值为 true.

• true 通过删除不再属于订阅服务器的分区的数据，向订阅服务器发送删除以反映分区更改的结果。

• false 保留订阅服务器上的旧分区中的数据，其中对发布服务器上的此数据所做的更改不会复制到此订阅服务器，但对订阅服务器所做的更改会复制到发布服务器。

设置@allow_partition_realignmentfalse用于在需要出于历史目的访问数据时保留旧分区中的订阅中的数据。

注意

由于将@allow_partition_realignmentfalse设置为只读而保留在订阅服务器上的数据应被视为只读;但是，复制系统不会强制执行此操作。

[ @retention_period_unit = ] N'retention_period_unit'

指定由 @retention设置的保留期单位。 @retention_period_unit 为 nvarchar（10），可以是以下值之一。

值	版本
day（默认值）	按天指定保持期。
week	按周指定保持期。
month	按月指定保持期。
year	按年指定保持期。

[ @generation_leveling_threshold = ] generation_leveling_threshold

指定一代中包含的更改数。 生成是传递到发布服务器或订阅服务器的更改的集合。 @generation_leveling_threshold为 int，默认值为 1000.

[ @automatic_reinitialization_policy = ] automatic_reinitialization_policy

指定在更改发布所需的自动重新初始化之前是否从订阅服务器上传更改，其中为@force_reinit_subscription指定了值1。 @automatic_reinitialization_policy为位，默认值为 0.

1 表示在自动重新初始化之前，将从订阅服务器上传更改。

重要

如果添加、删除或更改参数化筛选器，则无法在重新初始化期间将订阅服务器上的挂起更改上传到发布服务器。 若要上载挂起的更改，请在更改筛选器前同步所有订阅。

[ @conflict_logging = ] N'conflict_logging'

指定存储冲突记录的位置。 @conflict_logging 为 nvarchar（15），可以是以下值之一：

值	说明
publisher	在发布服务器上存储冲突记录。
subscriber	在导致冲突的订阅服务器上存储冲突记录。 SQL Server Compact 订阅服务器不支持。
both	在发布服务器和订阅服务器上都存储冲突记录。
NULL（默认值）	复制会自动将@conflict_logging设置为both值@publication_compatibility_level90RTM和publisher所有其他情况下的值。

返回代码值

0（成功）或 1（失败）。

注解

sp_addmergepublication 用于合并复制。

若要使用 @add_to_active_directory 参数将发布对象列出到 Active Directory，必须在 Active Directory 中创建 SQL Server 对象。

如果存在多个发布发布相同的数据库对象，则只有具有复制、、、和 ALTER TRIGGER ALTER FUNCTIONDDL 语句@replicate_ddl值的1发布。 ALTER PROCEDUREALTER VIEWALTER TABLE 但是， ALTER TABLE DROP COLUMN 发布已删除列的所有发布都将复制 DDL 语句。

对于 SQL Server Compact 订阅服务器，仅当@snapshot_in_default_folder的值为时，才会使用@alternate_snapshot_folderfalse的值。

如果为发布启用了 DDL 复制（@replicate_ddl = 1），若要对发布进行非复制 DDL 更改，必须先执行sp_changemergepublication才能将@replicate_ddl设置为 0。 发出非复制 DDL 语句后， sp_changemergepublication 可以再次运行以重新打开 DDL 复制。

示例

-- To avoid storing the login and password in the script file, the value 
-- is passed into SQLCMD as a scripting variable. 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".

--Declarations for adding a merge publication
DECLARE @publicationDB AS sysname;
DECLARE @publication AS sysname;
DECLARE @login AS sysname;
DECLARE @password AS sysname;
SET @publicationDB = N'AdventureWorks2022'; 
SET @publication = N'AdvWorksSalesOrdersMerge'; 
SET @login = $(Login);
SET @password = $(Password);

-- Enable merge replication on the publication database, using defaults.
USE master
EXEC sp_replicationdboption 
  @dbname=@publicationDB, 
  @optname=N'merge publish',
  @value = N'true' 

-- Create a new merge publication, explicitly setting the defaults. 
USE [AdventureWorks2022]
EXEC sp_addmergepublication 
-- These parameters are optional.
  @publication = @publication,
  -- optional parameters 
  @description = N'Merge publication of AdventureWorks2022.',
  @publication_compatibility_level  = N'120RTM';

-- Create a new snapshot job for the publication.
EXEC sp_addpublication_snapshot 
  @publication = @publication, 
  @job_login = @login, 
  @job_password = @password;
GO

权限

只有 sysadmin 固定服务器角色的成员或db_owner固定数据库角色的成员才能执行sp_addmergepublication。

相关内容

• 创建发布
• 发布数据和数据库对象
• sp_changemergepublication (Transact-SQL)
• sp_dropmergepublication （Transact-SQL）
• sp_helpmergepublication (Transact-SQL)
• 复制存储过程 (Transact-SQL)