sp_addarticle (Transact-SQL)
Creates an article and adds it to a publication. This stored procedure is executed at the Publisher on the publication database.
sp_addarticle [ @publication = ] 'publication'
, [ @article = ] 'article'
[ , [ @source_table = ] 'source_table' ]
[ , [ @destination_table = ] 'destination_table' ]
[ , [ @vertical_partition = ] 'vertical_partition' ]
[ , [ @type = ] 'type' ]
[ , [ @filter = ] 'filter' ]
[ , [ @sync_object= ] 'sync_object' ]
[ , [ @ins_cmd = ] 'ins_cmd' ]
[ , [ @del_cmd = ] 'del_cmd' ]
[ , [ @upd_cmd = ] 'upd_cmd' ]
[ , [ @creation_script = ] 'creation_script' ]
[ , [ @description = ] 'description' ]
[ , [ @pre_creation_cmd = ] 'pre_creation_cmd' ]
[ , [ @filter_clause = ] 'filter_clause' ]
[ , [ @schema_option = ] schema_option ]
[ , [ @destination_owner = ] 'destination_owner' ]
[ , [ @status = ] status ]
[ , [ @source_owner = ] 'source_owner' ]
[ , [ @sync_object_owner = ] 'sync_object_owner' ]
[ , [ @filter_owner = ] 'filter_owner' ]
[ , [ @source_object = ] 'source_object' ]
[ , [ @artid = ] article_ID OUTPUT ]
[ , [ @auto_identity_range = ] 'auto_identity_range' ]
[ , [ @pub_identity_range = ] pub_identity_range ]
[ , [ @identity_range = ] identity_range ]
[ , [ @threshold = ] threshold ]
[ , [ @force_invalidate_snapshot = ] force_invalidate_snapshot ]
[ , [ @use_default_datatypes = ] use_default_datatypes
[ , [ @identityrangemanagementoption = ] identityrangemanagementoption ]
[ , [ @publisher = ] 'publisher' ]
[ , [ @fire_triggers_on_snapshot = ] 'fire_triggers_on_snapshot' ]
sp_addarticle is used in snapshot replication or transactional replication.
By default, replication does not publish any columns in the source table when the column data type is not supported by replication. If you need to publish such a column, you must execute sp_articlecolumn to add the column.
When adding an article to a publication that supports peer-to-peer transactional replication, the following restrictions apply:
-
Parameterized statements must be specified for all logbased articles. You must include 16 in the status value.
-
Name and owner of the destination table must match the source table.
-
The article cannot be filtered horizontally or vertically.
-
Automatic identity range management is not supported. You must specify a value of manual for identityrangemanagementoption.
-
If a timestamp column exists in the table, you must include 0x08 in schema_option to replicate the column as timestamp.
-
A value of SQL cannot be specified for ins_cmd, upd_cmd, and del_cmd.
For more information, see Peer-to-Peer Transactional Replication.
When you publish objects, their definitions are copied to Subscribers. If you are publishing a database object that depends on one or more other objects, you must publish all referenced objects. For example, if you publish a view that depends on a table, you must publish the table also.
If vertical_partition is set to true, sp_addarticle defers the creation of the view until sp_articleview is called (after the last sp_articlecolumn is added).
If the publication allows updating subscriptions and the published table does not have a uniqueidentifier column, sp_addarticle adds a uniqueidentifier column to the table automatically.
When replicating to a subscriber that is not an instance of SQL Server (heterogeneous replication), only Transact-SQL statements are supported for INSERT, UPDATE, and DELETE commands.
When the log reader agent is running, adding an article to a peer-to-peer publication can cause a deadlock between the log reader agent and the process that adds the article. To avoid this issue, before adding an article to a peer-to-peer publication use the Replication Monitor to stop the log reader agent on the node where you are adding the article. Restart the log reader agent after adding the article.
When setting @del_cmd = 'NONE' or @ins_cmd = 'NONE', the propagation of UPDATE commands might also be affected by not sending those commands when a bounded update occurs. (A bounded update is type of UPDATE statement from the publisher that replicates as a DELETE/INSERT pair on the subscriber.)
Default Schema Options
This table describes the default value set by replication if schema_options is not specified by the user, where this value depends on the replication type (shown across the top) and the article type (shown down the first column).
|
Article type |
Replication type |
|
|---|---|---|
|
|
Transactional |
Snapshot |
|
aggregate schema only |
0x01 |
0x01 |
|
func schema only |
0x01 |
0x01 |
|
indexed view schema only |
0x01 |
0x01 |
|
indexed view logbased |
0x30F3 |
0x3071 |
|
indexed view logbase manualboth |
0x30F3 |
0x3071 |
|
indexed view logbased manualfilter |
0x30F3 |
0x3071 |
|
indexed view logbased manualview |
0x30F3 |
0x3071 |
|
logbased |
0x30F3 |
0x3071 |
|
logbased manualfilter |
0x30F3 |
0x3071 |
|
logbased manualview |
0x30F3 |
0x3071 |
|
proc exec |
0x01 |
0x01 |
|
proc schema only |
0x01 |
0x01 |
|
serializable proc exec |
0x01 |
0x01 |
|
view schema only |
0x01 |
0x01 |
Note
|
|---|
|
If a publication is enabled for queued updating, a schema_option value of 0x80 is added to the default value shown in the table. The default schema_option for a non-SQL Server publication is 0x050D3. |
Valid Schema Options
This table describes the allowable values of schema_option based upon the replication type (shown across the top) and the article type (shown down the first column).
|
Article type |
Replication type |
|
|---|---|---|
|
|
Transactional |
Snapshot |
|
logbased |
All options |
All options but 0x02 |
|
logbased manualfilter |
All options |
All options but 0x02 |
|
logbased manualview |
All options |
All options but 0x02 |
|
indexed view logbased |
All options |
All options but 0x02 |
|
indexed view logbased manualfilter |
All options |
All options but 0x02 |
|
indexed view logbased manualview |
All options |
All options but 0x02 |
|
indexed view logbase manualboth |
All options |
All options but 0x02 |
|
proc exec |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
|
serializable proc exec |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
|
proc schema only |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
|
view schema only |
0x01, 0x010, 0x020, 0x040, 0x0100, 0x2000, 0x40000, 0x100000, 0x200000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x40000000, and 0x80000000 |
0x01, 0x010, 0x020, 0x040, 0x0100, 0x2000, 0x40000, 0x100000, 0x200000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x40000000, and 0x80000000 |
|
func schema only |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
0x01, 0x20, 0x2000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x10000000, 0x20000000, 0x40000000, and 0x80000000 |
|
indexed view schema only |
0x01, 0x010, 0x020, 0x040, 0x0100, 0x2000, 0x40000, 0x100000, 0x200000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x40000000, and 0x80000000 |
0x01, 0x010, 0x020, 0x040, 0x0100, 0x2000, 0x40000, 0x100000, 0x200000, 0x400000, 0x800000, 0x2000000, 0x8000000, 0x40000000, and 0x80000000 |
Note
|
|---|
|
For queued updating publications, the schema_option values of 0x8000 and 0x80 must be enabled. The supported schema_option values for non-SQL Server publications are: 0x01, 0x02, 0x10, 0x40, 0x80, 0x1000, 0x4000 and 0X8000. |
DECLARE @publication AS sysname; DECLARE @table AS sysname; DECLARE @filterclause AS nvarchar(500); DECLARE @filtername AS nvarchar(386); DECLARE @schemaowner AS sysname; SET @publication = N'AdvWorksProductTran'; SET @table = N'Product'; SET @filterclause = N'[DiscontinuedDate] IS NULL'; SET @filtername = N'filter_out_discontinued'; SET @schemaowner = N'Production'; -- Add a horizontally and vertically filtered article for the Product table. -- Manually set @schema_option to ensure that the Production schema -- is generated at the Subscriber (0x8000000). EXEC sp_addarticle @publication = @publication, @article = @table, @source_object = @table, @source_owner = @schemaowner, @schema_option = 0x80030F3, @vertical_partition = N'true', @type = N'logbased', @filter_clause = @filterclause; -- (Optional) Manually call the stored procedure to create the -- horizontal filtering stored procedure. Since the type is -- 'logbased', this stored procedures is executed automatically. EXEC sp_articlefilter @publication = @publication, @article = @table, @filter_clause = @filterclause, @filter_name = @filtername; -- Add all columns to the article. EXEC sp_articlecolumn @publication = @publication, @article = @table; -- Remove the DaysToManufacture column from the article EXEC sp_articlecolumn @publication = @publication, @article = @table, @column = N'DaysToManufacture', @operation = N'drop'; -- (Optional) Manually call the stored procedure to create the -- vertical filtering view. Since the type is 'logbased', -- this stored procedures is executed automatically. EXEC sp_articleview @publication = @publication, @article = @table, @filter_clause = @filterclause; GO
