Configurar a transmissão de eventos de alteração (versão prévia) para o Hubs de Eventos do Azure

Aplica-se a: SQL Server 2025 (17.x) Banco de Dados SQL do AzureInstância Gerenciada de SQL do Azurebanco de dados SQL no Microsoft Fabric

Este artigo descreve como configurar o recurso de streaming de eventos de mudança (CES) no SQL Server 2025 (17.x), Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric para transmitir para Hubs de Eventos do Azure.

Para configurar o CES no Fabric Eventstream, confira Transmissão para Eventstream do Fabric.

Procedimento para transmissão de eventos de mudança

1. Use um namespace existente ou crie um novo namespace dos Hubs de Eventos do Azure e uma nova instância de Hubs de Eventos. A instância dos Hubs de Eventos recebe eventos.
2. Habilite o streaming de eventos de alteração para um banco de dados do usuário.
3. Crie um grupo de streaming. Com esse grupo, configure o destino, as credenciais, os limites de tamanho da mensagem e o esquema de particionamento.
4. Adicione uma ou mais tabelas ao grupo de fluxo.

Cada etapa é descrita em detalhes nas seções a seguir deste artigo.

Pré-requisitos

Para configurar o streaming de eventos de alteração, você precisa dos seguintes recursos, permissões e configuração:

• Namespace dos Hubs de Eventos do Azure
• Instância dos Hubs de Eventos do Azure
• Nome do host dos Hubs de Eventos do Azure
• Um logon na função db_owner ou que tenha permissão CONTROL DATABASE para o banco de dados no qual você pretende habilitar o CES.
• Para o SQL Server 2025 (17.x), habilite a configuração com escopo do banco de dados em versão prévia do recurso. O Banco de Dados SQL do Azure não requer essa configuração.
• Para o Banco de Dados SQL do Azure configurado para usar regras de firewall de saída e para a configuração de rede virtual da Instância Gerenciada de SQL do Azure: portas de firewall a serem abertas
• Para o Banco de Dados SQL do Azure configurado para usar um Perímetro de Segurança de Rede, permita o acesso aos Hubs de Eventos do Azure de destino:
  • Portas de firewall a serem abertas
  • Perímetro de segurança de rede para Hubs de Eventos do Azure.

Ao usar o streaming de eventos de alteração com a Instância Gerenciada de SQL do Azure, a instância deve ser configurada com a política de atualização do SQL Server 2025 ou Always-up-to-date.

Configurar Hubs de Eventos do Azure

Para saber como criar Hubs de Eventos do Azure, examine Criar um hub de eventos usando o portal do Azure.

Controle de acesso dos Hubs de Eventos do Azure

Configure o controle de acesso para o recurso SQL para os Hubs de Eventos do Azure. A autenticação do Microsoft Entra é o método mais seguro. O CES suporta autenticação Microsoft Entra no Banco de Dados SQL do Azure e no Instância Gerenciada de SQL do Azure. Para o SQL Server 2025, a autenticação Microsoft Entra é suportada a partir da Cumulative Update 3 (CU3) para instâncias habilitadas pelo Azure Arc ou rodando em uma VM Azure. Embora haja suporte para políticas de acesso compartilhado, use-as somente quando Microsoft Entra autenticação não for uma opção.

Habilitar e configurar o streaming de eventos de alteração

Para habilitar e configurar o streaming de eventos de alteração, altere o contexto do banco de dados para o banco de dados do usuário e siga estas etapas:

1. Se ainda não estiver configurado, defina o banco de dados como o modelo de recuperação completo.
2. Crie uma chave mestra e uma credencial com escopo de banco de dados.
3. Habilitar o streaming de eventos.
4. Crie o grupo de fluxo.
5. Adicione uma ou mais tabelas ao grupo de fluxo.

Os exemplos a seguir demonstram como habilitar o CES por plataforma:

• Transmitir dados para o Hubs de Eventos do Azure do Banco de Dados SQL do Azure
• Transmita para Hubs de Eventos do Azure a partir do SQL do Azure MI ou SQL Server 2025

A tabela a seguir lista valores de parâmetros de exemplo para os exemplos desta seção:

Os exemplos também usam os seguintes valores:

• [opcional, se políticas de acesso compartilhado via chave de serviço forem usadas] Valor primário ou secundário retirado da política de acesso compartilhado: Secret = 'BVFnT3baC/K6I8xNZzio4AeoFt6nHeK0i+ZErNGsxiw='
• EXEC sys.sp_add_object_to_event_stream_group N'myStreamGroup', N'dbo.myTable'

Exemplo: Transmitir para Hubs de Eventos do Azure a partir do Banco de Dados SQL do Azure

Os exemplos a seguir mostram como transmitir eventos de alteração para o Hubs de Eventos do Azure a partir do Banco de Dados SQL do Azure, usando AzureEventHubs como o destination_type. Este valor é o único valor aceito para o Banco de Dados SQL do Azure e para o banco de dados SQL no Microsoft Fabric.

USE <database name>;

-- Create the Master Key with a password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>';

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = 'Managed Identity'

EXEC sys.sp_enable_event_stream

EXEC sys.sp_create_event_stream_group
    @stream_group_name =      N'<EventStreamGroupName>',
    @destination_type =       N'AzureEventHubs',
    @destination_location =   N'<AzureEventHubsHostName>:9093/<EventHubsInstance>',
    @destination_credential = <CredentialName>,
    @max_message_size_kb =    <MaxMessageSize>,
    @partition_key_scheme =   N'<PartitionKeyScheme>'

EXEC sys.sp_add_object_to_event_stream_group
    N'<EventStreamGroupName>',
    N'<SchemaName>.<TableName>'

USE <database name>

-- Create the Master Key with a password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>'

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = '<Azure Event Hubs SAS Policy name>',
    SECRET = '<Primary or Secondary key value>'

EXEC sys.sp_enable_event_stream

EXEC sys.sp_create_event_stream_group
    @stream_group_name =      N'<EventStreamGroupName>',
    @destination_type =       N'AzureEventHubs',
    @destination_location =   N'<AzureEventHubsHostName>:9093/<EventHubsInstance>',
    @destination_credential = <CredentialName>,
    @max_message_size_kb =    <MaxMessageSize>,
    @partition_key_scheme =   N'<PartitionKeyScheme>'

EXEC sys.sp_add_object_to_event_stream_group
    N'<EventStreamGroupName>',
    N'<SchemaName>.<TableName>'

Exemplo: Transmita para Hubs de Eventos do Azure a partir do SQL do Azure MI ou SQL Server 2025

Os exemplos a seguir mostram como transmitir eventos de alteração para o Hubs de Eventos do Azure a partir do Instância Gerenciada de SQL do Azure ou SQL Server 2025, usando AzureEventHubsApacheKafka como o destination_type.

USE <database name>

-- Create the Master Key with a password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>'

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = 'Managed Identity'

EXEC sys.sp_enable_event_stream

EXEC sys.sp_create_event_stream_group
    @stream_group_name =      N'<EventStreamGroupName>',
    @destination_type =       N'AzureEventHubsApacheKafka',
    @destination_location =   N'<AzureEventHubsHostName>:<port>/<EventHubsInstance>', -- myEventHubsNamespace.servicebus.windows.net:9093/myEventHubsInstance
    @destination_credential = <CredentialName>,
    @max_message_size_kb =    <MaxMessageSize>,
    @partition_key_scheme =   N'<PartitionKeyScheme>'

EXEC sys.sp_add_object_to_event_stream_group
    N'<EventStreamGroupName>',
    N'<SchemaName>.<TableName>'

USE <database name>

-- Create the Master Key with a password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>'

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = '<Azure Event Hubs SAS Policy name>',
    SECRET = '<Primary or Secondary key value>' -- BVFnT3baC/K6I8xNZzio4AeoFt6nHeK0i+ZErNGsxiw=

EXEC sys.sp_enable_event_stream

EXEC sys.sp_create_event_stream_group
    @stream_group_name =      N'<EventStreamGroupName>',  -- myStreamGroup
    @destination_type =       N'AzureEventHubsApacheKafka',
    @destination_location =   N'<AzureEventHubsHostName>:<port>/<EventHubsInstance>', -- myEventHubsNamespace.servicebus.windows.net:9093/myEventHubsInstance
    @destination_credential = <CredentialName>,
    @max_message_size_kb =    <MaxMessageSize>,       -- 1024
    @partition_key_scheme =   N'<PartitionKeyScheme>'  -- N'None'

EXEC sys.sp_add_object_to_event_stream_group
    N'<EventStreamGroupName>',
    N'<SchemaName>.<TableName>' -- dbo.myTable

Para confirmar que o streaming está habilitado e visualizar as tabelas configuradas para um grupo de stream, veja Visualizar configuração e função CES.

Tamanho da mensagem e truncamento de colunas

Hubs de Eventos do Azure e Fabric Eventstream limitam o tamanho máximo de cada mensagem que recebem. O CES usa essa @max_message_size_kb configuração para dividir um grande evento de saída em múltiplos blocos de mensagem que se encaixam no destino configurado. Defina esse valor para alinhar com os limites do seu destino. Para os atributos JSON que identificam fragmentos de mensagem, veja formato de mensagem JSON - alterar fluxo de eventos.

Se um ou mais valores de coluna transmitida forem maiores que 1 MB, o CES trunca cada valor de coluna afetado para 1 MB antes que forme o evento de saída. O limite de 1 MB se aplica a cada valor de coluna separadamente. Esse truncamento é distinto da divisão de mensagens. Após truncar os valores excessivamente grandes das colunas, o CES forma o evento de saída, divide-o em partes conforme necessário, de acordo com @max_message_size_kb, e envia cada parte ao destino.

Defina a opção de configuração do servidor max text repl size para permitir a gravação de mais de 65.536 bytes em colunas LOB quando o CES estiver habilitado.

Por exemplo, se uma linha contiver cinco colunas e os valores das três primeiras colunas tiverem mais de 1 MB cada, CES:

1. Trunca o valor da primeira coluna para 1 MB.
2. Trunca o valor da segunda coluna para 1 MB.
3. Trunca o valor da terceira coluna para 1 MB.
4. Prepara o evento de saída, divide em um número necessário de blocos de acordo com @max_message_size_kb, e envia cada pedaço para o destino.

Exibir a configuração e a função do CES

Em sys.databases, is_event_stream_enabled = 1 indica que o streaming de eventos de alteração está habilitado para o banco de dados.

A consulta a seguir retorna todos os bancos de dados com streaming de eventos de alteração habilitado:

SELECT *
FROM sys.databases
WHERE is_event_stream_enabled = 1;

Em sys.tables, is_replicated = 1 indica que uma tabela é transmitida e sp_help_change_feed_table fornece informações sobre o grupo de tabelas e metadados de tabela para o streaming de eventos de alteração.

A consulta a seguir retorna todas as tabelas com o streaming de evento de alteração habilitado e fornece informações de metadados:

SELECT name,
       is_replicated
FROM sys.tables;

EXECUTE sp_help_change_feed_table
    @source_schema = '<schema name>',
    @source_name = '<table name>';

Procedimentos armazenados de CES, funções do sistema e DMVs

A tabela a seguir lista os procedimentos armazenados, as funções do sistema e as DMVs que você pode usar para configurar, desabilitar e monitorar o streaming de eventos de alteração:

Crescimento do log de transações

Como a entrega de mensagens é garantida, o log de transações de um banco de dados que tem o CES habilitado pode continuar a crescer. O truncamento do log é evitado enquanto houver alterações de CES para serem transmitidas do log. Depois que o tamanho do log de transações atingir o limite máximo definido, as gravações no banco de dados falharão.

Para evitar isso no Banco de Dados SQL do Azure e na Instância Gerenciada de SQL do Azure, quando o tamanho do log de transações se aproxima do limite máximo definido, a Microsoft pode desabilitar o CES ou encerrar transações de execução longa. Para instâncias não gerenciadas do SQL Server, como local ou no SQL Server em VMs do Azure, você é responsável por monitorar o tamanho do log de transações e garantir que ele não atinja o limite máximo definido e desabilitar manualmente o CES ou matar transações de execução longa, se necessário.

Depois que o CES é desabilitado ou uma transação longa é interrompida, o log de transações é truncado para liberar espaço. Você deve habilitar manualmente o CES novamente após ele ter sido desativado ou repetir quaisquer transações de longa duração que tenham sido interrompidas. As alterações de dados feitas enquanto o CES estava desabilitado não são capturadas. Somente as alterações feitas após a reinicialização do CES são transmitidas.

Veja a seguir uma lista de cenários típicos que podem levar ao crescimento do log de transações com o CES habilitado:

• Erros persistentes. O CES tenta enviar uma mensagem que é rejeitada repetidamente e o CES não pode continuar. Os motivos para erros persistentes que podem levar a mensagens rejeitadas incluem:
  • Problemas de rede ou configuração incorreta.
  • Configuração incorreta de credencial.
  • Tamanho máximo de mensagem configurado incorretamente que o destino rejeita.
• O destino limita os eventos de entrada. Por exemplo, os Hubs de Eventos do Azure aplicam limitação de taxa de acordo com sua SKU.
• Transações de execução prolongada que geram muitos registros de log e impedem o truncamento de log.

Para garantir operações suaves, monitore o tamanho do log de transações e os erros de entrega do CES regularmente.

Desempenho

No SQL Server, na Instância Gerenciada de SQL do Azure e nos pools elásticos do Banco de Dados SQL do Azure, você pode habilitar o CES em vários bancos de dados. Cada banco de dados habilitado para CES consome recursos de servidor e compete com outra carga de trabalho do servidor. Verifique se o servidor tem recursos adequados para a carga de trabalho esperada e monitore regularmente o desempenho do servidor e dos bancos de dados.

Limitações

O streaming de eventos de alteração (CES) tem as seguintes limitações:

• Limitações específicas da plataforma
• Limitações gerais e no nível do servidor
• Limitações no nível do banco de dados
• Limitações no nível da tabela
• Limitações no nível da coluna
• Permissões no banco de dados de origem
• Rede e conectividade

Limitações específicas da plataforma

Em produtos SQL configurados com um fuso horário não UTC, o campo committime em uma mensagem de streaming de eventos de alteração inclui incorretamente o sufixo Z, embora esse campo mostre a hora local do banco de dados de publicação. Quando o banco de dados usa UTC, o valor e o sufixo concordam. Esse problema é conhecido, e uma correção está pendente em uma futura versão do recurso.

As seguintes limitações se aplicam a plataformas específicas para a CES:

Limitações gerais e no nível do servidor

A lista a seguir descreve limitações gerais e em nível de servidor:

• O CES não tem suporte no SQL Server 2025 (17.x) no Linux.
• O CES emite eventos somente para alterações de dados nas instruções INSERT, UPDATE e DELETE DML.
• O CES não lida com alterações de esquema (operações DDL), o que significa que ele não emite eventos para operações DDL. No entanto, as operações DDL não são bloqueadas, portanto, se você executá-las, o esquema de eventos DML subsequentes reflete a estrutura de tabela atualizada. Espera-se que você lide normalmente com os eventos com o esquema atualizado.
• Atualmente, o CES não transmite dados que existem em uma tabela antes de o CES ser habilitado. Os dados existentes não são inicializados ou enviados como um instantâneo quando o CES está ativado.
• Se uma mensagem exceder o limite de tamanho da mensagem dos Hubs de Eventos do Azure, a falha só poderá ser observada por meio de Eventos Estendidos no momento. Atualmente, os ces xEvents estão disponíveis apenas no SQL Server 2025 e não no Banco de Dados SQL do Azure.
• Não há suporte para renomeação de tabelas e colunas configuradas para CES. Falha ao renomear uma tabela ou coluna. Renomeações de banco de dados são permitidas.
• O CES não está disponível para a Instância Gerenciada de SQL do Azure configurada com a política de atualização do SQL Server 2022. Ele só está disponível para instâncias configuradas com a política de atualização do SQL Server 2025 ou Always-up-to-date.
• Ao usar o protocolo Kafka, a CES não suporta autenticação de token SAS. Os únicos métodos de autenticação disponíveis são o Microsoft Entra e o valor da chave da política de Acesso Compartilhado.

Limitações no nível do banco de dados

A lista a seguir descreve limitações em nível de banco de dados:

• O CES só dá suporte a bancos de dados configurados com o modelo de recuperação completo.
• O CES não dá suporte a bancos de dados configurados com Bancos de Dados Espelhados do Fabric para SQL Server, replicação transacional, captura de dados de alteração ou Link do Azure Synapse. Há suporte para controle de alterações em bancos de dados configurados com CES.
• O CES só pode transmitir de bancos de dados primários graváveis. Bancos de dados secundários que fazem parte de grupos de disponibilidade Always On ou que usam o link da Instância Gerenciada não podem ser configurados como fontes de streaming.
• Você não pode habilitar o CES em exibições ou exibições indexadas.
• Você pode configurar até 4.096 grupos de fluxo. Cada grupo de fluxos pode incluir até 40.000 tabelas.

Limitações no nível da tabela

A lista a seguir descreve limitações em nível de tabela:

• Uma tabela pode pertencer a apenas um grupo de streaming. Você não pode transmitir a mesma tabela para vários destinos.
• Você só pode configurar tabelas de usuário para CES. O CES não dá suporte a tabelas do sistema de streaming.
• Embora o CES esteja habilitado em uma tabela, você não pode adicionar ou descartar uma restrição de chave primária nessa tabela.
• Nomes de tabelas que contêm um ponto (.) atualmente não são suportados.
• ALTER TABLE SWITCH PARTITION não é compatível nas tabelas configuradas para CES.
• TRUNCATE TABLE não é suportado em tabelas habilitadas para CES.
• O CES não dá suporte a tabelas que usam nenhum dos seguintes recursos:
  • Índice columnstore clusterizado
  • Tabelas de histórico temporal ou tabelas de histórico do razão
  • Sempre Criptografado
  • OLTP na memória (tabelas com otimização de memória)
  • Tabelas de grafos
  • Tabelas externas

Limitações no nível da coluna

A lista a seguir descreve limitações em nível de coluna:

• O CES não dá suporte aos seguintes tipos de dados. O streaming ignora colunas desses tipos:
  • geography
  • geometry
  • image
  • json
  • rowversion / carimbo de data/hora
  • sql_variant
  • Texto / ntext
  • vector
  • xml
  • Tipos definidos pelo usuário (UDT)
• Se um ou mais valores de coluna transmitida forem maiores que 1 MB, o CES trunca cada valor de coluna afetado para 1 MB antes que forme o evento de saída. Esse truncamento é incondicional e não registra erros ou avisos. Defina a opção de configuração do servidor max text repl size para permitir a gravação de mais de 65.536 bytes em colunas LOB quando o CES estiver habilitado.

Permissões no banco de dados de origem e residência de dados

A lista a seguir descreve permissões e limitações de residência de dados:

• Para segurança em nível de linha, o CES emite alterações de todas as linhas, independentemente das permissões do usuário.
• O mascaramento dinâmico de dados não se aplica aos dados enviados por meio do CES. Os dados são transmitidos desmascarados, mesmo que a máscara esteja configurada.
• O CES não emite eventos relacionados a alterações de permissão no nível do objeto (por exemplo, concedendo permissões a colunas específicas).
• O CES transmitirá dados para o destino configurado se a configuração de rede permitir. Se o destino estiver em uma região diferente, o CES transmitirá os dados entre regiões. Certifique-se de que isso está em conformidade com seus requisitos de residência de dados e de conformidade.

Rede e conectividade

A lista a seguir descreve uma limitação de rede e conectividade:

• Atualmente, o CES só pode transmitir para os endpoints públicos do Hubs de Eventos do Azure. No momento, não há suporte para pontos de extremidade de serviço e pontos de extremidade privados.
• Ao usar o protocolo AMQP no Instância Gerenciada de SQL do Azure ou SQL Server 2025 (para grupos de stream existentes ainda não migrados), defina a opção de configuração da versão TLS Mínima do Hubs de Eventos do Azure para 1.2. O CES não funciona com TLS 1.3 sobre o protocolo AMQP.

Conteúdo relacionado

• O que é o streaming de eventos de alteração (versão prévia)?
• Perguntas frequentes
• Formato de mensagem JSON – alterar o streaming de eventos
• Transmitir para Fabric Eventstream