sp_addsubscription (Transact-SQL)

Aplica-se a: Banco de Dados SQL do Azure do SQL Server

Adiciona uma assinatura a uma publicação e define o status do Assinante. Esse procedimento armazenado é executado no Publicador, no banco de dados publicador.

Convenções de sintaxe de Transact-SQL

Sintaxe

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 ]
[ ; ]

Argumentos

@publication [ = ] N'publicação'

O nome da publicação. @publication é sysname, sem padrão.

@article [ = ] N'artigo'

O artigo no qual a publicação é assinada. @article é sysname, com um padrão de all. Se all, uma assinatura é adicionada a todos os artigos dessa publicação. Somente valores de all ou NULL são suportados para Publicadores Oracle.

@subscriber [ = ] N'assinante'

O nome do Assinante. @subscriber é sysname, com um padrão de NULL.

Observação

O nome do servidor pode ser especificado como <Hostname>,<PortNumber>. Especifique o número da porta para sua conexão quando o SQL Server for implantado no Linux ou Windows com uma porta personalizada e o serviço do navegador estiver desabilitado. O uso de números de porta personalizados para distribuidor remoto se aplica ao SQL Server 2019 (15.x) e versões posteriores.

@destination_db [ = ] N'destination_db'

O nome do banco de dados de destino no qual colocar os dados replicados. @destination_db é sysname, com um padrão de NULL. Quando NULL, @destination_db é definido como o nome do banco de dados de publicação. Para Publicadores Oracle, @destination_db deve ser especificado. Para um Assinante não SQL Server, especifique um valor de (destino padrão) para @destination_db.

@sync_type [ = ] N'sync_type'

O tipo de sincronização de assinatura. @sync_type é nvarchar(255) e pode ser um dos seguintes valores:

Valor	Descrição
none 1	O Assinante já tem o esquema e os dados iniciais para as tabelas publicadas.
automatic (padrão)	Esquema e dados iniciais de tabelas publicadas são transferidos ao Assinante primeiro.
replication support only 2	Fornece geração automática no Assinante de procedimentos armazenados personalizados de artigo e gatilhos que oferecem suporte a assinaturas de atualização, se apropriado. Presume que o Assinante já tem o esquema e os dados iniciais para as tabelas publicadas. Ao configurar uma topologia de replicação transacional ponto a ponto, verifique se os dados em todos os nós na topologia são idênticos. Para obter mais informações, consulte Ponto a ponto - Replicação transacional.
initialize with backup 2	Esquema e dados iniciais para tabelas publicadas são obtidos de um backup do banco de dados de publicação. Presume que o Assinante tem acesso a um backup do banco de dados de publicação. O local do backup e o tipo de mídia para o backup são especificados por @backupdevicename e @backupdevicetype. Ao usar essa opção, uma topologia de replicação transacional ponto a ponto não precisa ser desativada durante a configuração.
initialize from lsn	Usado quando você está adicionando um nó a uma topologia de replicação transacional ponto a ponto. Usado com @subscriptionlsn para garantir que todas as transações relevantes são replicadas para o novo nó. Presume que o Assinante já tem o esquema e os dados iniciais para as tabelas publicadas. Para obter mais informações, consulte Ponto a ponto - Replicação transacional.

1 Esta opção foi preterida. Use, em vez disso, suporte a replicação.

2 Não há suporte para assinaturas de publicações que não sejam do SQL Server.

Observação

Tabelas de sistema e dados sempre são transferidos.

@status [ = ] N'status'

O status da assinatura. @status é sysname, com um padrão de NULL. Quando esse parâmetro não é definido explicitamente, a replicação o define automaticamente como um desses valores.

Valor	Descrição
active	A assinatura é inicializada e está pronta para oferecer suporte a alterações. Essa opção é definida quando o valor de @sync_type é nenhum, inicializar apenas com backup ou suporte de replicação.
subscribed	A assinatura precisa ser inicializada. Essa opção é definida quando o valor de @sync_type é automático.

@subscription_type [ = ] N'subscription_type'

O tipo de assinatura. @subscription_type é nvarchar(4), com um padrão de push. Pode ser push ou pull. Os Agentes de Distribuição de assinaturas push residem no Distribuidor e os Agentes de Distribuição de assinaturas pull residem no Assinante. @subscription_type pode ser pull criar uma assinatura pull nomeada que seja conhecida pelo Publicador. Para obter mais informações, consulte Subscribe to Publications (Assinar publicações).

Observação

As assinaturas anônimas não precisam usar esse procedimento armazenado.

@update_mode [ = ] N'update_mode'

O tipo de atualização. @update_mode é nvarchar(30) e pode ser um desses valores.

Valor	Descrição
read only (padrão)	A assinatura é somente leitura. As alterações no Assinante não são enviadas ao Publicador.
sync tran	Habilita suporte para assinaturas de atualização imediata. Sem suporte para Publicadores Oracle.
queued tran	Habilita a assinatura de atualização enfileirada. As modificações de dados podem ser feitas no Assinante, armazenadas em uma fila e, depois, propagadas ao Publicador. Sem suporte para Publicadores Oracle.
failover	Habilita a assinatura para atualização imediata com atualização enfileirada como um failover. Modificações de dados podem ser feitas no Assinante e propagadas ao Publicador imediatamente. Se o Publicador e o Assinante não estiverem conectados, o modo de atualização poderá ser alterado para que as modificações de dados feitas no Assinante sejam armazenadas em uma fila até que o Assinante e o Publicador sejam reconectados. Sem suporte para Publicadores Oracle.
queued failover	Habilita a assinatura como uma assinatura de atualização enfileirada com a capacidade de alterar para o modo de atualização imediata. Modificações de dados podem ser feitas no Assinante e armazenadas em uma fila até que a conexão seja estabelecida entre o Assinante e o Publicador. Quando uma conexão contínua é estabelecida, o modo de atualização pode ser alterado para atualização imediata. Sem suporte para Publicadores Oracle.

Os valores sync tran e queued tran não serão permitidos se a publicação que está sendo assinada permitir DTS.

@loopback_detection [ = ] N'loopback_detection'

Especifica se o Agente de Distribuição envia transações originadas no Assinante de volta ao Assinante. @loopback_detection é nvarchar(5) e pode ser um desses valores.

Valor	Descrição
true	O Distribution Agent não envia transações originadas no Assinante de volta para o Assinante. Usado com replicação transacional bidirecional. Para obter mais informações, consulte Bidirectional Transactional Replication.
false	O Distribution Agent envia transações originadas no Assinante de volta ao Assinante.
NULL (padrão)	Definido automaticamente como true para um Assinante do SQL Server e false para um Assinante que não seja do SQL Server.

@frequency_type [ = ] frequency_type

A frequência com que agendar a tarefa de distribuição. @frequency_type é int e pode ser um desses valores.

Valor	Descrição
1	Uma vez
2	Sob demanda
4	Diário
8	Semanal
16	Mensal
32	Relativo ao mês
64 (padrão)	Iniciar automaticamente
128	Recorrente

@frequency_interval [ = ] frequency_interval

O valor a ser aplicado à frequência definida por @frequency_type. @frequency_interval é int, com um padrão de NULL.

@frequency_relative_interval [ = ] frequency_relative_interval

A data do Agente de Distribuição. Esse parâmetro é usado quando @frequency_type é definido como 32 (relativo mensal). @frequency_relative_interval é int e pode ser um desses valores.

Valor	Descrição
1	First
2	Segundo
4	Terceiro
8	Quarto
16	Last
NULL (padrão)

@frequency_recurrence_factor [ = ] frequency_recurrence_factor

O fator de recorrência usado por @frequency_type. @frequency_recurrence_factor é int, com um padrão de NULL.

@frequency_subday [ = ] frequency_subday

Com que frequência, em minutos, reagendar durante o período definido. @frequency_subday é int e pode ser um desses valores.

Valor	Descrição
1	Uma vez
2	Second
4	Minuto
8	Hora
NULL

@frequency_subday_interval [ = ] frequency_subday_interval

O intervalo para @frequency_subday. @frequency_subday_interval é int, com um padrão de NULL.

@active_start_time_of_day [ = ] active_start_time_of_day

A hora do dia em que o Distribution Agent é agendado pela primeira vez, formatado como HHmmss. @active_start_time_of_day é int, com um padrão de NULL.

@active_end_time_of_day [ = ] active_end_time_of_day

A hora do dia em que o Distribution Agent deixa de ser agendado, formatado como HHmmss. @active_end_time_of_day é int, com um padrão de NULL.

@active_start_date [ = ] active_start_date

A data em que o Distribution Agent é agendado pela primeira vez, formatado como yyyyMMdd. @active_start_date é int, com um padrão de NULL.

@active_end_date [ = ] active_end_date

A data em que o Distribution Agent deixa de ser agendado, formatado como yyyyMMdd. @active_end_date é int, com um padrão de NULL.

@optional_command_line [ = ] N'optional_command_line'

O prompt de comando opcional a ser executado. @optional_command_line é nvarchar(4000), com um padrão de NULL.

@reserved [ = ] N'reservado'

Identificado apenas para fins informativos. Não há suporte. A compatibilidade futura não está garantida.

@enabled_for_syncmgr [ = ] N'enabled_for_syncmgr'

Se a assinatura pode ser sincronizada por meio do Gerenciador de Sincronização do Windows. @enabled_for_syncmgr é nvarchar(5), com um padrão de NULL, que é o mesmo falseque . Se false, a assinatura não está registrada no Gerenciador de Sincronização do Windows. Se true, a assinatura estiver registrada no Gerenciador de Sincronização do Windows e poderá ser sincronizada sem iniciar o SQL Server Management Studio. Sem suporte para Publicadores Oracle.

@offloadagent [ = ] agente de descarregamento

Especifica que o agente pode ser ativado remotamente. @offloadagent é bit, com um padrão de 0.

Observação

Esse parâmetro foi preterido e só é mantido para compatibilidade com versões anteriores.

@offloadserver [ = ] N'offloadserver'

Especifica o nome da rede de servidor a ser usada para ativação remota. @offloadserver é sysname, com um padrão de NULL.

@dts_package_name [ = ] N'dts_package_name'

Especifica o nome do pacote DTS (Data Transformation Services). @dts_package_name é sysname, com um padrão de NULL. Por exemplo, para especificar um nome de pacote DTSPub_Package, o parâmetro seria @dts_package_name = N'DTSPub_Package'. Esse parâmetro está disponível para assinaturas push. Para adicionar informações do pacote DTS a uma assinatura pull, use sp_addpullsubscription_agent.

@dts_package_password [ = ] N'dts_package_password'

Especifica a senha no pacote, se houver. @dts_package_password é sysname, com um padrão de NULL.

Observação

Você deve especificar uma senha se @dts_package_name for especificado.

@dts_package_location [ = ] N'dts_package_location'

Especifica o local do pacote. @dts_package_location é nvarchar(12), com um padrão de NULL, que é o mesmo distributorque . A localização do pacote pode ser distributor ou subscriber.

@distribution_job_name [ = ] N'distribution_job_name'

Identificado apenas para fins informativos. Não há suporte. A compatibilidade futura não está garantida.

@publisher [ = ] N'editor'

Especifica um Publicador não-SQL Server. @publisher é sysname, com um padrão de NULL.

Observação

@publisher não deve ser especificado para um Publicador do SQL Server.

@backupdevicetype [ = ] N'tipo de dispositivo de backup'

Especifica o tipo do dispositivo de backup a ser usado ao inicializar um Assinante de um backup. @backupdevicetype é nvarchar(20) e pode ser um destes valores:

Valor	Descrição
logical (padrão)	O dispositivo de backup é um dispositivo lógico
disk	O dispositivo de backup é uma unidade de disco
tape	O dispositivo de backup é uma unidade de fita.

@backupdevicetype só é usado quando @sync_method está definido como initialize_with_backup.

@backupdevicename [ = ] N'backupdevicename'

Especifica o nome do dispositivo usado ao inicializar um Assinante em um backup. @backupdevicename é nvarchar(1000), com um padrão de NULL.

@mediapassword [ = ] N'mediapassword'

Especifica uma senha para o conjunto de mídias se uma senha já tiver sido definida quando a mídia foi formatada. @mediapassword é sysname, com um padrão de NULL.

Observação

Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.

@password [ = ] N'senha'

Especifica uma senha para o backup se uma senha já tiver sido definida quando o backup foi criado. @password é sysname, com um padrão de NULL.

@fileidhint [ = ] fileidhint

Identifica um valor ordinal do conjunto de backup a ser restaurado. @fileidhint é int, com um padrão de NULL.

@unload [ = ] descarregar

Especifica se um dispositivo de backup em fita deve ser descarregado quando a inicialização do backup for concluída. @unload é bit, com um padrão de 1, que especifica que a fita deve ser descarregada. @unload só é usado quando @backupdevicetype é tape.

@subscriptionlsn [ = ] subscriptionlsn

Especifica o LSN (número de sequência de log) no qual uma assinatura deve começar a entrega de alterações para um nó, em uma topologia de replicação transacional ponto a ponto. @subscriptionlsn é binary(10), com um padrão de NULL. Usado com um valor @sync_type de initialize from lsn para garantir que todas as transações relevantes sejam replicadas para um novo nó. Para obter mais informações, consulte Ponto a ponto - Replicação transacional.

@subscriptionstreams [ = ] subscriptionstreams

O número de conexões permitidas por Distribution Agent para aplicar lotes de alterações em paralelo a um Assinante, mantendo muitas das características transacionais presentes ao usar um único thread. @subscriptionstreams é tinyint, com um padrão de NULL. Há suporte para um intervalo de valores de 1 até 64 . Não há suporte para esse parâmetro para Assinantes não SQL Server, Publicadores Oracle ou assinaturas ponto a ponto. Sempre que @subscriptionstreams é usado, linhas adicionais são adicionadas à msreplication_subscriptions tabela (uma linha por fluxo) com um agent_id conjunto como NULL.

Observação

Os fluxos de assinatura não funcionam para artigos configurados para fornecer Transact-SQL. Para usar fluxos de assinatura, configure artigos para entregar chamadas de procedimento armazenado.

@subscriber_type [ = ] subscriber_type

O tipo de Assinante. @subscriber_type é tinyint e pode ser um desses valores.

Valor	Descrição
0 (padrão)	Assinante do SQL Server
1	Servidor de fontes de dados ODBC
2	Banco de dados Microsoft Jet
3	Provedor OLE DB

@memory_optimized [ = ] memory_optimized

Indica que a assinatura dá suporte a tabelas com otimização de memória. @memory_optimized é bit, com um padrão de 0 (false). 1 (true) significa que a assinatura dá suporte a tabelas com otimização de memória.

Valores do código de retorno

0 (sucesso) ou 1 (falha).

Comentários

sp_addsubscription é usado na replicação de instantâneo e na replicação transacional.

Quando sp_addsubscription é executado por um membro da função de servidor fixa sysadmin para criar uma assinatura push, o trabalho do Distribution Agent é criado implicitamente e executado na conta de serviço do SQL Server Agent. Recomendamos que você execute sp_addpushsubscription_agent e especifique as credenciais de uma conta diferente do Windows específica do agente para @job_login e @job_password. Para obter mais informações, consulte Replication Agent Security Model.

sp_addsubscription impede o acesso de assinantes ODBC e OLE DB a publicações que:

• Foram criados com o @sync_method nativo na chamada para sp_addpublication.

• Contêm artigos que foram adicionados à publicação com o procedimento armazenado sp_addarticle que tinha um valor de parâmetro @pre_creation_cmd de 3 (truncado).

• Tente definir @update_mode como sync tran.

• Têm um artigo configurado para usar instruções com parâmetros.

Além disso, se uma publicação tiver a opção @allow_queued_tran definida como true (o que permite o enfileiramento de alterações no Assinante até que elas possam ser aplicadas no Publicador), a coluna de carimbo de data/hora em um artigo será roteirizada como carimbo de data/hora e as alterações nessa coluna serão enviadas ao Assinante. O Assinante gera e atualiza o valor da coluna de carimbo de hora. Para um Assinante ODBC ou OLE DB, sp_addsubscription falhará se for feita uma tentativa de assinar uma publicação que @allow_queued_tran definida como true e artigos com colunas de carimbo de data/hora.

Se uma assinatura não usar um pacote DTS, ela não poderá assinar uma publicação definida como @allow_transformable_subscriptions. Se a tabela da publicação precisar ser replicada para uma assinatura DTS e uma assinatura não DTS, deverão ser criadas duas publicações separadas, uma para cada tipo de assinatura.

Ao selecionar as opções replication support onlysync_type , initialize with backup, ou initialize from lsn, o agente leitor de log deve ser executado após a execução sp_addsubscriptiondo , para que os scripts de configuração sejam gravados no banco de dados de distribuição. O Agente de Leitor de Log deve ser executado sob uma conta que seja membro da função de servidor fixa sysadmin . Quando a opção @sync_type é definida como Automatic, nenhuma ação especial do agente do leitor de log é necessária.

Permissões

Somente membros da função de servidor fixa sysadmin ou db_owner função de banco de dados fixa podem executar sp_addsubscription. Para assinaturas pull, os usuários com logons na lista de acesso à publicação podem executar sp_addsubscriptiono .

Exemplos

-- 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

Conteúdo relacionado

• Criar uma assinatura push
• Criar uma assinatura para um assinante não SQL Server
• Subscribe to Publications
• sp_addpushsubscription_agent (Transact-SQL)
• sp_changesubstatus (Transact-SQL)
• sp_dropsubscription (Transact-SQL)
• sp_helpsubscription (Transact-SQL)
• Procedimentos armazenados do sistema (Transact-SQL)