sys.sp_cdc_enable_table (Transact-SQL)

Se aplica a: SQL Server

Habilita la captura de datos modificados para la tabla de origen especificada en la base de datos actual. Cuando una tabla está habilitada para la captura de datos modificados, un registro de cada operación del lenguaje de manipulación de datos (DML) aplicada a la tabla se escribe en el registro de transacciones. El proceso de captura de datos de cambio recupera esta información del registro y la escribe para cambiar las tablas a las que se accede mediante un conjunto de funciones.

La captura de datos modificados no está disponible en todas las ediciones de SQL Server. Para obtener una lista de las características admitidas por las ediciones de SQL Server, consulte Ediciones y características admitidas de SQL Server 2022.

Convenciones de sintaxis de Transact-SQL

Sintaxis

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 = ] N'captured_column_list' ]
    [ , [ @filegroup_name = ] 'filegroup_name' ]
    [ , [ @allow_partition_switch = ] 'allow_partition_switch' ]
[ ; ]

Argumentos

[ @source_schema = ] 'source_schema'

Nombre del esquema al que pertenece la tabla de origen. @source_schema es sysname, sin ningún valor predeterminado y no puede ser NULL.

[ @source_name = ] 'source_name'

Nombre de la tabla de origen en la que se va a habilitar la captura de datos modificados. @source_name es sysname, sin valor predeterminado y no puede ser NULL.

source_name debe existir en la base de datos actual. Las tablas del cdc esquema no se pueden habilitar para la captura de datos modificados.

[ @role_name = ] 'role_name'

Nombre del rol de base de datos que se usa para permitir el acceso a los datos modificados. @role_name es sysname y debe especificarse. Si se establece NULLexplícitamente en , no se usa ningún rol de acceso para limitar el acceso a los datos modificados.

Si el rol existe actualmente, se usa. Si el rol no existe, se intenta crear un rol de base de datos con el nombre especificado. Antes de intentar crear el rol, se recortan los espacios en blanco a la derecha de la cadena del nombre del rol. Si el autor de la llamada no está autorizado para crear un rol dentro de la base de datos, se produce un error en la operación de procedimiento almacenado.

[ @capture_instance = ] 'capture_instance'

el nombre de la instancia de captura que se usa para denominar los objetos de captura de datos modificados específicos de una instancia. @capture_instance es sysname y no puede ser NULL.

Si no se especifica, el nombre se obtiene del nombre del esquema de origen al que se agrega el nombre de la tabla de origen en el formato <schemaname>_<sourcename>. @capture_instance no puede superar los 100 caracteres y debe ser único dentro de la base de datos. Tanto si se especifica como si se deriva, se recorta @capture_instance de cualquier espacio en blanco a la derecha de la cadena.

Una tabla de origen puede tener un máximo de dos instancias de captura. Para obtener más información, consulte sys.sp_cdc_help_change_data_capture.

[ @supports_net_changes = ] supports_net_changes

Indica si se permiten las consultas de cambios netos para esta instancia de captura. @supports_net_changes es bit con un valor predeterminado de 1 si la tabla tiene una clave principal o la tabla tiene un índice único que se ha identificado mediante el parámetro @index_name. De lo contrario, el parámetro tiene 0como valor predeterminado .

• Si 0es , solo se generan las funciones de soporte técnico para consultar todos los cambios.
• Si 1es , también se generan las funciones necesarias para consultar los cambios netos.

Si @supports_net_changes se establece 1en , se debe especificar @index_name o la tabla de origen debe tener una clave principal definida.

Cuando @supports_net_changes se establece 1en , se crea un índice no clúster adicional en la tabla de cambios y se crea la función de consulta net changes. Dado que es necesario mantener este índice, habilitar los cambios netos puede tener un efecto negativo en el rendimiento cdc.

[ @index_name = ] 'index_name'

Nombre de un índice único que se va a usar para identificar de manera inequívoca las filas de la tabla de origen. @index_name es sysname y puede ser NULL. Si se especifica, @index_name debe ser un índice único válido en la tabla de origen. Si se especifica @index_name , las columnas de índice identificadas tienen prioridad sobre las columnas de clave principal definidas como identificador de fila único para la tabla.

[ @captured_column_list = ] N'captured_column_list'

Identifica las columnas de la tabla de origen que se incluirán en la tabla de cambios. @captured_column_list es nvarchar(max) y puede ser NULL. Si NULLes , todas las columnas se incluyen en la tabla de cambios.

Los nombres de columna deben ser columnas válidas de la tabla de origen. Se deben incluir columnas definidas en un índice de clave principal o columnas definidas en un índice al que hace referencia @index_name .

@captured_column_list es una lista separada por comas de nombres de columna. Los nombres de columna individuales de la lista se pueden citar opcionalmente mediante comillas dobles ("") o corchetes ([]). Si un nombre de columna contiene una coma, se debe entrecomillar el nombre de columna.

@captured_column_list no puede contener los siguientes nombres de columna reservados: __$start_lsn, __$end_lsn, __$seqval, __$operationy __$update_mask.

[ @filegroup_name = ] 'filegroup_name'

Grupo de archivos que se va a usar para la tabla de cambios creada para la instancia de captura. @filegroup_name es sysname y puede ser NULL. Si se especifica, @filegroup_name debe definirse para la base de datos actual. Si NULLes , se usa el grupo de archivos predeterminado.

Se recomienda crear un grupo de archivos independiente para las tablas de cambios de la captura de datos modificados.

[ @allow_partition_switch = ] 'allow_partition_switch'

Indica si el comando SWITCH PARTITION de ALTER TABLE se puede ejecutar en una tabla que esté habilitada para la captura de datos de cambio. @allow_partition_switch es bit, con un valor predeterminado de 1.

Para las tablas sin particiones, el valor del modificador es siempre 1 y se omite el valor real. Si el modificador se establece 0 explícitamente en para una tabla no particionada, se emite la advertencia 22857 para indicar que se ha omitido la configuración del modificador. Si el modificador se establece 0 explícitamente en para una tabla con particiones, se emite la advertencia 22356 para indicar que no se permiten las operaciones del conmutador de partición en la tabla de origen. Por último, si la configuración del modificador se establece explícitamente 1 en o se permite establecer de forma predeterminada en 1 y la tabla habilitada tiene particiones, se emite la advertencia 22855 para indicar que no se bloquearán los modificadores de partición. Si se produce algún modificador de partición, la captura de datos modificados no realiza un seguimiento de los cambios resultantes del modificador. Esto provoca incoherencias en los datos cuando se consumen los datos modificados.

SWITCH PARTITION es una operación de metadatos, pero produce cambios en los datos. Los cambios de datos asociados a esta operación no se capturan en las tablas de cambios de captura de datos modificados. Considere una tabla que tiene tres particiones. Se realizan cambios en esta tabla. El proceso de captura realiza un seguimiento de las operaciones de inserción, actualización y eliminación de usuarios que se ejecutan en la tabla. Sin embargo, si una partición se cambia a otra tabla (por ejemplo, para realizar una eliminación masiva), las filas que se movieron como parte de esta operación no se capturan como filas eliminadas en la tabla de cambios. De forma similar, si se agrega una nueva partición que tiene filas rellenadas previamente a la tabla, estas filas no se reflejan en la tabla de cambios. Esto puede producir incoherencias en los datos cuando una aplicación utilice los cambios y los aplique en el destino.

Si habilita la conmutación de particiones en SQL Server, es posible que también necesite operaciones de división y combinación en un futuro próximo. Antes de ejecutar una operación de división o combinación en una tabla replicada o habilitada para CDC, asegúrese de que la partición en cuestión no tenga comandos replicados pendientes. También debe asegurarse de que no se ejecuten operaciones DML en la partición durante las operaciones de división y combinación. Si hay transacciones que el trabajo de captura CDC o lector de registro no ha procesado, o si las operaciones DML se realizan en una partición de una tabla replicada o habilitada para CDC mientras se ejecuta una operación de división o combinación (que implica la misma partición), podría provocar un error de procesamiento (error 608: no se encontró ninguna entrada de catálogo para el identificador de partición) con el agente de registro del log o el trabajo de captura CDC. Para corregir el error, es posible que sea necesario reinicializar la suscripción o deshabilitar CDC en esa tabla o base de datos.

Valores de código de retorno

0 (correcto) o 1 (erróneo).

Conjunto de resultados

Ninguno.

Comentarios

Para poder habilitar una tabla para la captura de datos modificados, la base de datos debe estar habilitada. Para determinar si la base de datos está habilitada para la captura de datos modificados, consulte la is_cdc_enabled columna en la vista de catálogo sys.databases . Para habilitar la base de datos, use el procedimiento almacenado sys.sp_cdc_enable_db .

Cuando la captura de datos modificados está habilitada para una tabla, se generan una tabla de cambios y una o dos funciones de consulta. La tabla de cambios actúa de repositorio para los cambios de la tabla de origen extraídos del registro de transacciones por el proceso de captura. Las funciones de consulta se utilizan para extraer los datos de la tabla de cambios. Los nombres de estas funciones se derivan del parámetro @capture_instance de las siguientes maneras:

• Todas las funciones de cambios: cdc.fn_cdc_get_all_changes_<capture_instance>
• Función de cambios netos: cdc.fn_cdc_get_net_changes_<capture_instance>

sys.sp_cdc_enable_table también crea los trabajos de captura y limpieza de la base de datos si la tabla de origen es la primera tabla de la base de datos que se va a habilitar para la captura de datos modificados y no existen publicaciones transaccionales para la base de datos. Establece la is_tracked_by_cdc columna en la vista de catálogo sys.tables en 1.

Agente SQL Server no tiene que ejecutarse cuando CDC está habilitado para una tabla. Sin embargo, el proceso de captura no procesa el registro de transacciones y escribe entradas en la tabla de cambios a menos que se ejecute Agente SQL Server.

Permisos

Requiere pertenencia al rol fijo de base de datos db_owner.

Ejemplos

A Habilitación de la captura de datos modificados especificando solo los parámetros necesarios

En el siguiente ejemplo se habilita la captura de datos modificados para la tabla HumanResources.Employee. Solo se especifican los parámetros necesarios.

USE AdventureWorks2022;
GO

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

B. Habilitación de la captura de datos modificados especificando parámetros opcionales adicionales

En el siguiente ejemplo se habilita la captura de datos modificados para la tabla HumanResources.Department. Se especifican todos los parámetros excepto @allow_partition_switch .

USE AdventureWorks2022;
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

Contenido relacionado

• sys.sp_cdc_disable_table (Transact-SQL)
• sys.sp_cdc_help_change_data_capture (Transact-SQL)
• <cdc.fn_cdc_get_all_changes_capture_instance> (Transact-SQL)
• <cdc.fn_cdc_get_net_changes_capture_instance> (Transact-SQL)
• sys.sp_cdc_help_jobs (Transact-SQL)