sys.sp_cdc_enable_table (Transact-SQL)

Artigo
04/15/2014

Habilita o Change Data Capture para a tabela de origem especificada no banco de dados atual. Quando uma tabela está habilitada para Change Data Capture, um registro de cada operação DML (Linguagem de Manipulação de Dados) aplicado à tabela é gravado no log de transações. O processo do Change Data Capture recupera essas informações a partir do log e grava-as nas tabelas de alteração que são acessadas usando um conjunto de funções.

A captura de dados de alterações não está disponível em todas as edições do Microsoft SQL Server. Para obter uma lista de recursos com suporte nas edições do SQL Server, consulte Recursos compatíveis com as edições do SQL Server 2012.

Ícone de vínculo de tópico Convenções da sintaxe Transact-SQL

Sintaxe

sys.sp_cdc_enable_table 
  [ @source_schema = ] 'source_schema', 
  [ @source_name = ] 'source_name' ,
  [,[ @capture_instance = ] 'capture_instance' ]
  [,[ @supports_net_changes = ] supports_net_changes ]
  , [ @role_name = ] 'role_name'
  [,[ @index_name = ] 'index_name' ]
  [,[ @captured_column_list = ] 'captured_column_list' ]
  [,[ @filegroup_name = ] 'filegroup_name' ]
  [,[ @allow_partition_switch = ] 'allow_partition_switch' ]
  [;]

Argumentos

[ @source_schema = ] 'source_schema'
É o nome do esquema ao qual a tabela de origem pertence. source_schema é sysname, sem padrão e não pode ser NULL.
[ @source_name = ] 'source_name'
É o nome da tabela de origem na qual habilitar a captura de dados de alteração. source_name é sysname, sem padrão e não pode ser NULL.

source_name deve existir no banco de dados atual. Não podem ser habilitadas tabelas no esquema cdc para Change Data Capture.
[ @role_name = ] 'role_name'
É o nome da função de banco de dados usada como acesso aos dados de alteração. role_name é sysname e deve ser especificado. Se explicitamente definido como NULL, nenhuma função associada será usada para limitar o acesso aos dados de alteração.

Se a função existir atualmente, ela será usada. Se a função não existir, será feita uma tentativa de criar uma função de banco de dados com o nome especificado. Os espaços em branco do nome da função à direita da cadeia de caracteres são eliminados antes de tentar criar a função. Se o chamador não for autorizado a criar uma função dentro do banco de dados, a operação de procedimento armazenado irá falhar.
[ @capture_instance = ] 'capture_instance'
É o nome da instância de captura usada para nomear objetos do Change Data Capture específicos. capture_instance é sysname e não pode ser NULL.

Se não for especificado, o nome será derivado do nome do esquema de origem mais o nome de tabela de origem, no formato schemaname_sourcename. capture_instance não pode exceder 100 caracteres e deve ser exclusivo no banco de dados. Seja especificado ou derivado, qualquer espaço em branco à direita da cadeia de caracteres de capture_instance será eliminado.

Uma tabela de origem pode ter um máximo de duas instâncias de captura. Para obter mais informações, consulte sys.sp_cdc_help_change_data_capture (Transact-SQL).
[ @supports_net_changes = ] supports_net_changes
Indica se o suporte à consulta de alterações líquidas será habilitado para esta instância de captura. supports_net_changes será bit com um padrão de 1 se a tabela tiver uma chave primária ou se a tabela tiver um índice exclusivo identificado usando o parâmetro @index\_name. Caso contrário, o parâmetro será padronizado como 0.

Se for 0, somente as funções de suporte à consulta de todas as alterações serão geradas.

Se for 1, as funções necessárias à consulta de alterações líquidas também serão geradas.

Se supports_net_changes for definido como 1, index_name deverá ser especificado ou a tabela de origem deverá ter uma chave primária definida.
[ @index_name = ] **'**index_name'
O nome de um índice exclusivo a ser usado para identificar exclusivamente as linhas na tabela de origem. index_name é sysname e pode ser NULL. Se for especificado, index_name deverá ser um índice exclusivo válido na tabela de origem. Se index_name for especificado, as colunas de índice identificadas terão precedência sobre quaisquer colunas de chave primária definidas como o identificador de linha exclusivo da tabela.
[ @captured_column_list = ] 'captured_column_list'
Identifica as colunas da tabela de origem a serem incluídas na tabela de alteração. captured_column_list é nvarchar(max) e pode ser NULL. Se for NULL, todas as colunas serão incluídas na tabela de alteração.

Nomes de Coluna devem ser colunas válidas na tabela de origem. Colunas definidas em um índice de chave primária ou colunas definidas em um índice referenciado por index_name devem ser incluídas.

captured_column_list é uma lista de nomes de colunas separados por vírgula. Nomes de colunas individuais na lista podem ser citados opcionalmente usando aspas duplas ("") ou colchetes ([]). Se um nome de coluna contiver uma vírgula inserida, o nome de coluna deve ser citado.

captured_column_list não pode conter os seguintes nomes de colunas reservados: __$start_lsn, __$end_lsn, __$seqval, __$operation e __$update_mask.
[ @filegroup_name = ] 'filegroup_name'
É o grupo de arquivos a ser usado para a tabela de alteração criada para a instância de captura. filegroup_name é sysname e pode ser NULL. Se especificado, filegroup_name deverá ser definido para o banco de dados atual. Se for NULL, o grupo de arquivos padrão será usado.

Recomendamos a criação de um grupo de arquivos separado para tabelas de alteração do Change Data Capture.

[ @allow_partition_switch= ] 'allow_partition_switch'
Indica se o comando SWITCH PARTITION de ALTER TABLE pode ser executado em uma tabela que está habilitada para o Change Data Capture. allow_partition_switch é bit, com um padrão de 1.

Para tabelas não particionadas, a configuração de alternância é sempre 1 e a configuração real é ignorada. Se a alternância estiver explicitamente definida como 0 para uma tabela não particionada, o aviso 22857 será emitido para indicar que a configuração de alternância foi ignorada. Se a alternância estiver explicitamente definida como 0 para uma tabela particionada, o aviso 22356 será emitido para indicar que as operações de alternância da partição na tabela de origem não serão permitidas. Finalmente, se a configuração de alternância estiver explicitamente definida como 1 ou permitida para ser padronizada como 1 e a tabela habilitada estiver particionada, o aviso 22855 será emitido para indicar que as alternâncias de partição não serão bloqueadas. Se ocorrer qualquer alternância de partição, o Change Data Capture não controlará as alterações resultantes da alternância. Isso provocará inconsistências de dados quando os dados de alteração forem consumidos.

Importante
SWITCH PARTITION é uma operação de metadados, mas provoca alterações nos dados. As alterações de dados associadas a essa operação não são capturadas nas tabelas de alteração do Change Data Capture. Considere uma tabela com três partições em que são feitas alterações. O processo de captura rastreará operações de inserção, atualização e exclusão de usuário que são executadas na tabela. Entretanto, se uma partição for alternada para outra tabela (por exemplo, para executar uma exclusão em massa), as linhas movidas como parte dessa operação não serão capturadas como linhas excluídas na tabela de alteração. Da mesma forma, se uma nova partição com linhas previamente populadas for adicionada à tabela, essas linhas não constarão na tabela de alteração. Isso pode causar inconsistência de dados quando as alterações forem consumidas por um aplicativo e aplicadas a um destino.

SWITCH PARTITION é uma operação de metadados, mas provoca alterações nos dados. As alterações de dados associadas a essa operação não são capturadas nas tabelas de alteração do Change Data Capture. Considere uma tabela com três partições em que são feitas alterações. O processo de captura rastreará operações de inserção, atualização e exclusão de usuário que são executadas na tabela. Entretanto, se uma partição for alternada para outra tabela (por exemplo, para executar uma exclusão em massa), as linhas movidas como parte dessa operação não serão capturadas como linhas excluídas na tabela de alteração. Da mesma forma, se uma nova partição com linhas previamente populadas for adicionada à tabela, essas linhas não constarão na tabela de alteração. Isso pode causar inconsistência de dados quando as alterações forem consumidas por um aplicativo e aplicadas a um destino.

Valores de código de retorno

0 (êxito) ou 1 (falha)

Conjuntos de resultados

Nenhum

Comentários

Antes de habilitar uma tabela para Change Data Capture, o banco de dados deve estar habilitado. Para determinar se o banco de dados está habilitado para o Change Data Capture, consulte a coluna is_cdc_enabled na exibição do catálogo sys.databases. Para habilitar o banco de dados, use o procedimento armazenado sys.sp_cdc_enable_db.

Quando o Change Data Capture está habilitado para uma tabela, uma tabela de alteração e uma ou duas funções de consulta são geradas. A tabela de alteração serve como um repositório para as alterações da tabela de origem extraídas do log de transações pelo processo de captura. As funções de consulta são usadas para extrair dados da tabela de alteração. Os nomes dessas funções são derivados do parâmetro capture_instance das seguintes maneiras:

A função de todas as alterações: cdc.fn_cdc_get_all_changes_<capture_instance>
A função de alterações líquidas: cdc.fn_cdc_get_net_changes_<capture_instance>

sys.sp_cdc_enable_table também criará os trabalhos de captura e de limpeza para o banco de dados, se a tabela de origem for a primeira tabela no banco de dados a ser habilitada para o Change Data Capture e se nenhuma publicação transacional existir no banco de dados. Define a coluna is_tracked_by_cdc na exibição de catálogo sys.tables como 1.

Observação
O SQL Server Agent não precisa estar em execução quando o Change Data Capture estiver habilitado para uma tabela. No entanto o processo de captura não processará o log de transações e não gravará as entradas na tabela de alteração, a não ser que o SQL Server Agent esteja em execução.

Permissões

Requer associação na função de banco de dados fixa db_owner.

Exemplos

A.Habilitando o Change Data Capture especificando somente os parâmetros necessários

O exemplo a seguir habilita o Change Data Capture na tabela HumanResources.Employee. Somente os parâmetros necessários são especificados.

USE AdventureWorks2012;
GO
EXECUTE sys.sp_cdc_enable_table
    @source_schema = N'HumanResources'
  , @source_name = N'Employee'
  , @role_name = N'cdc_Admin';
GO

B.Habilitando o Change Data Capture especificando parâmetros opcionais adicionais

O exemplo a seguir habilita o Change Data Capture na tabela HumanResources.Department. Todos os parâmetros, exceto o @allow\_partition\_switch são especificados.

USE AdventureWorks2012;
GO
EXEC sys.sp_cdc_enable_table
    @source_schema = N'HumanResources'
  , @source_name = N'Department'
  , @role_name = N'cdc_admin'
  , @capture_instance = N'HR_Department' 
  , @supports_net_changes = 1
  , @index_name = N'AK_Department_Name' 
  , @captured_column_list = N'DepartmentID, Name, GroupName' 
  , @filegroup_name = N'PRIMARY';
GO