Skip to content

create-a-pull-subscription.md

Latest commit

 

History

History
269 lines (151 loc) · 26.1 KB

create-a-pull-subscription.md

File metadata and controls

269 lines (151 loc) · 26.1 KB
title Create a Pull Subscription | Microsoft Docs
ms.custom
ms.date 05/24/2017
ms.prod sql-server-2014
ms.reviewer
ms.technology replication
ms.topic conceptual
helpviewer_keywords
pull subscriptions [SQL Server replication], creating
merge replication subscribing [SQL Server replication], pull subscriptions
subscriptions [SQL Server replication], pull
snapshot replication [SQL Server], subscribing
transactional replication, subscribing
ms.assetid 41d1886d-59c9-41fc-9bd6-a59b40e0af6e
author MashaMSFT
ms.author mathoma
manager craigg

Create a Pull Subscription

This topic describes how create a pull subscription in [!INCLUDEssCurrent] by using [!INCLUDEssManStudioFull], [!INCLUDEtsql], or Replication Management Objects (RMO).

Setting up a pull subscription for P2P replication is possible by script, but is not available through the wizard.

Using SQL Server Management Studio

Create a pull subscription at the Publisher or the Subscriber using the New Subscription Wizard. Follow the pages in the wizard to:

  • Specify the Publisher and publication.

  • Select where replication agents will run. For a pull subscription, select Run each agent at its Subscriber (pull subscriptions) on the Distribution Agent Location page or Merge Agent Location page, depending on the type of publication.

  • Specify Subscribers and subscription databases.

  • Specify the logins and passwords used for connections made by replication agents:

    • For subscriptions to snapshot and transactional publications, specify credentials on the Distribution Agent Security page.

    • For subscriptions to merge publications, specify credentials on the Merge Agent Security page.

    For information about the permissions required by each agent, see Replication Agent Security Model.

  • Specify a synchronization schedule and when the Subscriber should be initialized.

  • Specify additional options for merge publications: subscription type; values for parameterized filtering; and information for synchronization through HTTPS if the publication is enabled for Web synchronization.

  • Specify additional options for transactional publications that allow updating subscriptions: whether Subscribers should commit changes at the Publisher immediately or write them to a queue; credentials used to connect from the Subscriber to the Publisher.

  • Optionally script the subscription.

To create a pull subscription from the Publisher

  1. Connect to the Publisher in [!INCLUDEmsCoName] [!INCLUDEssManStudioFull], and then expand the server node.

  2. Expand the Replication folder, and then expand the Local Publications folder.

  3. Right-click the publication for which you want to create one or more subscriptions, and then click New Subscriptions.

  4. Complete the pages in the New Subscription Wizard.

To create a pull subscription from the Subscriber

  1. Connect to the Subscriber in [!INCLUDEssManStudioFull], and then expand the server node.

  2. Expand the Replication folder.

  3. Right-click the Local Subscriptions folder, and then click New Subscriptions.

  4. On the Publication page of the New Subscription Wizard, select <Find SQL Server Publisher> or <Find Oracle Publisher> from the Publisher drop-down list.

  5. Connect to the Publisher in the Connect to Server dialog box.

  6. Select a publication on the Publication page.

  7. Complete the pages in the New Subscription Wizard.

Using Transact-SQL

Pull subscriptions can be created programmatically using replication stored procedures. The stored procedures used will depend on the type of publication to which the subscription belongs.

To create a pull subscription to a snapshot or transactional publication

  1. At the Publisher, verify that the publication supports pull subscriptions by executing sp_helppublication (Transact-SQL).

    • If the value of allow_pull in the result set is 1, then the publication supports pull subscriptions.

    • If the value of allow_pull is 0, execute sp_changepublication (Transact-SQL), specifying allow_pull for @property and true for @value.

  2. At the Subscriber, execute sp_addpullsubscription (Transact-SQL). Specify @publisher and @publication. For information about updating subscriptions, see Create an Updatable Subscription to a Transactional Publication.

  3. At the Subscriber, execute sp_addpullsubscription_agent (Transact-SQL). Specify the following:

    • The @publisher, @publisher_db, and @publication parameters.

    • The [!INCLUDEmsCoName] Windows credentials under which the Distribution Agent at the Subscriber runs for @job_login and @job_password.

      [!NOTE]
      Connections made using Windows Integrated Authentication always use the Windows credentials specified by @job_login and @job_password. The Distribution Agent always makes the local connection to the Subscriber using Windows Integrated Authentication. By default, the agent will connect to the Distributor using Windows Integrated Authentication.

    • (Optional) A value of 0 for @distributor_security_mode and the [!INCLUDEmsCoName] [!INCLUDEssNoVersion] login information for @distributor_login and @distributor_password, if you need to use [!INCLUDEssNoVersion] Authentication when connecting to the Distributor.

    • A schedule for the Distribution Agent job for this subscription. For more information, see Specify Synchronization Schedules.

  4. At the Publisher, execute sp_addsubscription (Transact-SQL) to register the pull subscription. Specify @publication, @subscriber, and @destination_db. Specify a value of pull for @subscription_type.

To create a pull subscription to a merge publication

  1. At the Publisher, verify that the publication supports pull subscriptions by executing sp_helpmergepublication (Transact-SQL).

    • If the value of allow_pull in the result set is 1, then the publication supports pull subscriptions.

    • If the value of allow_pull is 0, execute sp_changemergepublication (Transact-SQL), specifying allow_pull for @property and true for @value.

  2. At the Subscriber, execute sp_addmergepullsubscription (Transact-SQL). Specify @publisher, @publisher_db, @publication, and the following parameters:

    • @subscriber_type - specify local for a client subscription and global for a server subscription.

    • @subscription_priority - Specify a priority for the subscription (0.00 to 99.99). This is only required for a server subscription.

      For more information, see Advanced Merge Replication Conflict Detection and Resolution.

  3. At the Subscriber, execute sp_addmergepullsubscription_agent (Transact-SQL). Specify the following parameters:

    • @publisher, @publisher_db, and @publication.

    • The Windows credentials under which the Merge Agent at the Subscriber runs for @job_login and @job_password.

      [!NOTE]
      Connections made using Windows Integrated Authentication always use the Windows credentials specified by @job_login and @job_password. The Merge Agent always makes the local connection to the Subscriber using Windows Integrated Authentication. By default, the agent will connect to the Distributor and Publisher using Windows Integrated Authentication.

    • (Optional) A value of 0 for @distributor_security_mode and the [!INCLUDEssNoVersion] login information for @distributor_login and @distributor_password, if you need to use [!INCLUDEssNoVersion] Authentication when connecting to the Distributor.

    • (Optional) A value of 0 for @publisher_security_mode and the [!INCLUDEssNoVersion] login information for @publisher_login and @publisher_password, if you need to use [!INCLUDEssNoVersion] Authentication when connecting to the Publisher.

    • A schedule for the Merge Agent job for this subscription. For more information, see Create an Updatable Subscription to a Transactional Publication.

  4. At the Publisher, execute sp_addmergesubscription (Transact-SQL). Specify @publication, @subscriber, @subscriber_db, and a value of pull for @subscription_type. This registers the pull subscription.

Examples (Transact-SQL)

The following example creates a pull subscription to a transactional publication. The first batch is executed at the Subscriber, and the second batch is executed at the Publisher. Login and password values are supplied at runtime using sqlcmd scripting variables.

[!code-sqlHowTo#sp_addtranpullsubscriptionagent]

[!code-sqlHowTo#sp_addtranpullsubscription]

The following example creates a pull subscription to a merge publication. The first batch is executed at the Subscriber, and the second batch is executed at the Publisher. Login and password values are supplied at runtime using sqlcmd scripting variables.

[!code-sqlHowTo#sp_addmergepullsubscriptionagent]

[!code-sqlHowTo#sp_addmergepullsubscription]

Using Replication Management Objects (RMO)

The RMO classes used to create a pull subscription depend on the type of publication to which the subscription belongs.

To create a pull subscription to a snapshot or transactional publication

  1. Create connections to both the Subscriber and Publisher by using the xref:Microsoft.SqlServer.Management.Common.ServerConnection Class.

  2. Create an instance of the xref:Microsoft.SqlServer.Replication.TransPublication class by using the Publisher connection from step 1. Specify xref:Microsoft.SqlServer.Replication.Publication.Name%2A, xref:Microsoft.SqlServer.Replication.Publication.DatabaseName%2A and xref:Microsoft.SqlServer.Replication.ReplicationObject.ConnectionContext%2A.

  3. Call the xref:Microsoft.SqlServer.Replication.ReplicationObject.LoadProperties%2A method. If this method returns false, either the properties specified in step 2 are incorrect or the publication does not exist on the server.

  4. Perform a bitwise logical AND (& in Visual C# and And in Visual Basic) between the xref:Microsoft.SqlServer.Replication.Publication.Attributes%2A property and xref:Microsoft.SqlServer.Replication.PublicationAttributes.AllowPull. If the result is xref:Microsoft.SqlServer.Replication.PublicationAttributes.None, set xref:Microsoft.SqlServer.Replication.Publication.Attributes%2A to the result of a bitwise logical OR (| in Visual C# and Or in Visual Basic) between xref:Microsoft.SqlServer.Replication.Publication.Attributes%2A and xref:Microsoft.SqlServer.Replication.PublicationAttributes.AllowPull. Then, call xref:Microsoft.SqlServer.Replication.ReplicationObject.CommitPropertyChanges%2A to enable pull subscriptions.

  5. If the subscription database does not exist, create it by using the xref:Microsoft.SqlServer.Management.Smo.Database class. For more information, see Creating, Altering, and Removing Databases.

  6. Create an instance of the xref:Microsoft.SqlServer.Replication.TransPullSubscription class.

  7. Set the following subscription properties:

    • The xref:Microsoft.SqlServer.Management.Common.ServerConnection to the Subscriber created in step 1 for xref:Microsoft.SqlServer.Replication.ReplicationObject.ConnectionContext%2A.

    • Name of the subscription database for xref:Microsoft.SqlServer.Replication.PullSubscription.DatabaseName%2A.

    • Name of the Publisher for xref:Microsoft.SqlServer.Replication.PullSubscription.PublisherName%2A.

    • Name of the publication database for xref:Microsoft.SqlServer.Replication.PullSubscription.PublicationDBName%2A.

    • Name of the publication for xref:Microsoft.SqlServer.Replication.PullSubscription.PublicationName%2A.

    • The xref:Microsoft.SqlServer.Replication.IProcessSecurityContext.Login%2A and xref:Microsoft.SqlServer.Replication.IProcessSecurityContext.Password%2A or xref:Microsoft.SqlServer.Replication.IProcessSecurityContext.SecurePassword%2A fields of xref:Microsoft.SqlServer.Replication.PullSubscription.SynchronizationAgentProcessSecurity%2A to provide the credentials for the [!INCLUDEmsCoName] Windows account under which the Distribution Agent runs at the Subscriber. This account is used to make local connections to the Subscriber and to make remote connections using Windows Authentication.

      [!NOTE]
      Setting xref:Microsoft.SqlServer.Replication.PullSubscription.SynchronizationAgentProcessSecurity%2A is not required when the subscription is created by a member of the sysadmin fixed server role, however it is recommended. In this case, the agent will impersonate the SQL Server Agent account. For more information, see Replication Agent Security Model.

    • (Optional) A value of true for xref:Microsoft.SqlServer.Replication.PullSubscription.CreateSyncAgentByDefault%2A to create an agent job that is used to synchronize the subscription. If you specify false (the default), the subscription can only be synchronized programmatically and you must specify additional properties of xref:Microsoft.SqlServer.Replication.TransSynchronizationAgent when you access this object from the xref:Microsoft.SqlServer.Replication.TransPullSubscription.SynchronizationAgent%2A property. For more information, see Synchronize a Pull Subscription.

      [!NOTE]
      SQL Server Agent is not available in every edition of [!INCLUDEmsCoName][!INCLUDEssNoVersion]. For a list of features that are supported by the editions of [!INCLUDEssNoVersion], see Features Supported by the Editions of SQL Server 2014. When you specify a value of true for Express Subscribers, the agent job is not created. However, important subscription-related metadata is stored at the Subscriber.

    • (Optional) Set the xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SqlStandardLogin%2A and xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SqlStandardPassword%2A or xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SecureSqlStandardPassword%2A fields of xref:Microsoft.SqlServer.Replication.PullSubscription.DistributorSecurity%2A when using SQL Server Authentication to connect to the Distributor.

  8. Call the xref:Microsoft.SqlServer.Replication.PullSubscription.Create%2A method.

  9. Using the instance of the xref:Microsoft.SqlServer.Replication.TransPublication class from step 2, call the xref:Microsoft.SqlServer.Replication.TransPublication.MakePullSubscriptionWellKnown%2A method to register the pull subscription with the Publisher. If this registration already exists, an exception occurs.

To create a pull subscription to a merge publication

  1. Create connections to both the Subscriber and Publisher by using the xref:Microsoft.SqlServer.Management.Common.ServerConnection class.

  2. Create an instance of the xref:Microsoft.SqlServer.Replication.MergePublication class by using the Publisher connection from step 1. Specify xref:Microsoft.SqlServer.Replication.Publication.Name%2A, xref:Microsoft.SqlServer.Replication.Publication.DatabaseName%2A, and xref:Microsoft.SqlServer.Replication.ReplicationObject.ConnectionContext%2A.

  3. Call the xref:Microsoft.SqlServer.Replication.ReplicationObject.LoadProperties%2A method. If this method returns false, either the properties specified in step 2 are incorrect or the publication does not exist on the server.

  4. Perform a bitwise logical AND (& in Visual C# and And in Visual Basic) between the xref:Microsoft.SqlServer.Replication.Publication.Attributes%2A property and xref:Microsoft.SqlServer.Replication.PublicationAttributes.AllowPull. If the result is xref:Microsoft.SqlServer.Replication.PublicationAttributes.None, set xref:Microsoft.SqlServer.Replication.Publication.Attributes%2A to the result of a bitwise logical OR (| in Visual C# and Or in Visual Basic) between xref:Microsoft.SqlServer.Replication.Publication.Attributes%2A and xref:Microsoft.SqlServer.Replication.PublicationAttributes.AllowPull. Then, call xref:Microsoft.SqlServer.Replication.ReplicationObject.CommitPropertyChanges%2A to enable pull subscriptions.

  5. If the subscription database does not exist, create it by using the xref:Microsoft.SqlServer.Management.Smo.Database class. For more information, see Creating, Altering, and Removing Databases.

  6. Create an instance of the xref:Microsoft.SqlServer.Replication.MergePullSubscription class.

  7. Set the following subscription properties:

    • The xref:Microsoft.SqlServer.Management.Common.ServerConnection to the Subscriber created in step 1 for xref:Microsoft.SqlServer.Replication.ReplicationObject.ConnectionContext%2A.

    • Name of the subscription database for xref:Microsoft.SqlServer.Replication.PullSubscription.DatabaseName%2A.

    • Name of the Publisher for xref:Microsoft.SqlServer.Replication.PullSubscription.PublisherName%2A.

    • Name of the publication database for xref:Microsoft.SqlServer.Replication.PullSubscription.PublicationDBName%2A.

    • Name of the publication for xref:Microsoft.SqlServer.Replication.PullSubscription.PublicationName%2A.

    • The xref:Microsoft.SqlServer.Replication.IProcessSecurityContext.Login%2A and xref:Microsoft.SqlServer.Replication.IProcessSecurityContext.Password%2A or xref:Microsoft.SqlServer.Replication.IProcessSecurityContext.SecurePassword%2A fields of xref:Microsoft.SqlServer.Replication.PullSubscription.SynchronizationAgentProcessSecurity%2A to provide the credentials for the [!INCLUDEmsCoName] Windows account under which the Merge Agent runs at the Subscriber. This account is used to make local connections to the Subscriber and to make remote connections using Windows Authentication.

      [!NOTE]
      Setting xref:Microsoft.SqlServer.Replication.PullSubscription.SynchronizationAgentProcessSecurity%2A is not required when the subscription is created by a member of the sysadmin fixed server role, however it is recommended. In this case, the agent will impersonate the SQL Server Agent account. For more information, see Replication Agent Security Model.

    • (Optional) A value of true for xref:Microsoft.SqlServer.Replication.PullSubscription.CreateSyncAgentByDefault%2A to create an agent job that is used to synchronize the subscription. If you specify false (the default), the subscription can only be synchronized programmatically and you must specify additional properties of xref:Microsoft.SqlServer.Replication.MergeSynchronizationAgent when you access this object from the xref:Microsoft.SqlServer.Replication.MergePullSubscription.SynchronizationAgent%2A property. For more information, see Synchronize a Pull Subscription.

    • (Optional) Set the xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SqlStandardLogin%2A and xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SqlStandardPassword%2A or xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SecureSqlStandardPassword%2A fields of xref:Microsoft.SqlServer.Replication.PullSubscription.DistributorSecurity%2A when using SQL Server Authentication to connect to the Distributor.

    • (Optional) Set the xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SqlStandardLogin%2A and xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SqlStandardPassword%2A or xref:Microsoft.SqlServer.Replication.ConnectionSecurityContext.SecureSqlStandardPassword%2A fields of xref:Microsoft.SqlServer.Replication.PullSubscription.PublisherSecurity%2A when using SQL Server Authentication to connect to the Publisher.

  8. Call the xref:Microsoft.SqlServer.Replication.PullSubscription.Create%2A method.

  9. Using the instance of the xref:Microsoft.SqlServer.Replication.MergePublication class from step 2, call the xref:Microsoft.SqlServer.Replication.MergePublication.MakePullSubscriptionWellKnown%2A method to register the pull subscription with the Publisher. If this registration already exists, an exception occurs.

Example (RMO)

This example creates a pull subscription to a transactional publication. The [!INCLUDEmsCoName] Windows account credentials used to create the Distribution Agent job are passed at runtime.

[!code-csharpHowTo#rmo_CreateTranPullSub]

[!code-vbHowTo#rmo_vb_CreateTranPullSub]

This example creates a pull subscription to a merge publication. The Windows account credentials used to create the Merge Agent job are passed at runtime.

[!code-csharpHowTo#rmo_CreateMergePullSub]

[!code-vbHowTo#rmo_vb_CreateMergePullSub]

This example creates a pull subscription to a merge publication without creating an associated agent job and subscription metadata in MSsubscription_properties. The Windows account credentials used to create the Merge Agent job are passed at runtime.

[!code-csharpHowTo#rmo_CreateMergePullSub_NoJob]

[!code-vbHowTo#rmo_vb_CreateMergePullSub_NoJob]

This example creates a pull subscription to a merge publication that can be synchronized over the Internet using Web synchronization. The Windows account credentials used to create the Merge Agent job are passed at runtime. For more information, see Configure Web Synchronization.

[!code-csharpHowTo#rmo_CreateMergePullSub_WebSync]

[!code-vbHowTo#rmo_vb_CreateMergePullSub_WebSync]

See Also

Replication Management Objects Concepts
View and Modify Pull Subscription Properties
Configure Web Synchronization
Subscribe to Publications
Replication Security Best Practices