Let's continue from my last two posts. Here is some more information regarding CDC
"Now, how does SQLCDC handle new columns being added to a source table being monitored/captured by SQLCDC?"
I’ll first address the inverse of this question. How does SQLCDC handle columns that are removed from a source table? The answer is that SQL CDC does the best it can do, by not altering the source table’s corresponding Change Table schema so as not to break any downstream consuming applications/services. And thus, any columns dropped from the source table remain in the change table with NULLs being inserted into the removed column going forward.
Now, moving on, in regard to this actual question, SQLCDC (for the same reasons cited above) does not alter a source table’s corresponding change table when a new column gets added to a source table being captured by SQLCDC. To enable SQLCDC to capture the new column you simply need to create a second capture instance which will then capture the new column and it’s data.
Note
A source table being captured by SQL CDC can only have up to 2 Capture Instances. If a source table incurs regular columns being added/removed you will need to recycle your capture instances.
Step 1
Add a New Column to the HumanResources.Employee Table.
- ALTER TABLE humanresources.employee
- ADD [NewCol] INT;
- GO
A source table can only have 2 capture instances associated with it!
Step 2
Create a new, second capture instance to facilitate the capture of change data for the new column.
- EXEC Sp_cdc_enable_table
- humanresources ,
- employee ,
- ‘HumanResources_Employee_New’ ,
- 1 ,
- dbo
- GO
Step 3
Sample DML Statement.
- UPDATE humanresources.employee
- SET newcol = 1
- WHERE employeeid = 1
- GO
Step 4
Create a new, second UDF that uses the new capture instance to collect the new column’s data.
- CREATE FUNCTION [dbo].[Udf_employee_newcol] ( @start_time DATETIME,
- @end_time DATETIME )
- returns @EMPLOYEE TABLE
- (
- employeeid INT,
- nationalidnumber NVARCHAR(15),
- contactid INT,
- managerid INT,
- title NVARCHAR(50),
- birthdate DATETIME,
- maritalstatus NCHAR(1),
- gender NCHAR(1),
- hiredate DATETIME,
- salariedflag [FLAG],
- vacationhours SMALLINT,
- sickleavehours SMALLINT,
- currentflag [FLAG],
- rowguid UNIQUEIDENTIFIER,
- [user] NVARCHAR(50),
- [NewCol] INT,
- cdc_operation VARCHAR(1)
- )
- AS BEGIN –declare local variables TO hold lsns
- DECLARE @from_lsn binary(10),
- @to_lsn binary(10) –map the time interval TO a change data capture query range.IF (@start_time IS NULL)
- BEGIN
- SELECT @from_lsn = sys.fn_cdc_get_min_lsn( ‘humanresources_employee_new’ )
- END
- ELSE
- BEGIN
- SELECT @from_lsn = sys.fn_cdc_map_time_to_lsn( ‘smallest greater than
- OR equal’, @start_time )
- END
- IF (@end_time IS NULL)
- BEGIN
- SELECT @to_lsn = sys.fn_cdc_get_max_lsn()
- END
- ELSE
- BEGIN
- SELECT @to_lsn = sys.fn_cdc_map_time_to_lsn( ‘largest less than
- OR equal’, @end_time )
- END
- –if same THEN
- EXIT
- IF ( @from_lsn = sys.fn_cdc_increment_lsn(@to_lsn) )
- BEGIN
- RETURN
- END
- — query FOR change data
- INSERT INTO @Employee
- SELECT employeeid,
- nationalidnumber,
- contactid,
- managerid,
- title,
- birthdate,
- maritalstatus,
- gender,
- hiredate,
- salariedflag,
- vacationhours,
- sickleavehours,
- currentflag,
- rowguid,
- [user],
- [NewCol],
- CASE __$operation
- WHEN 1 THEN ‘d’
- WHEN 2 THEN ‘i’
- WHEN 4 THEN ‘u’
- ELSE NULL
- END AS cdc_operation
- FROM cdc.fn_cdc_get_net_changes_humanresources_employee_new(@from_lsn, @to_lsn, ’all’)
- RETURN
- ENDgo
Step 5
Query the new UDF for the sample DML.
- SELECT *
- FROM [dbo].[Udf_employee_newcol](NULL,NULL)
- GO
UPDATE 2
I have received several questions regarding how/if you can capture the user that commits DML statements to a change table. As I mentioned in my feedback for this post, there is no out-of-the-box solution to capture the user who commits the changes (DML) being captured, however you can build a custom solution, such as the script below.
-
- USE [AdventureWorks] GO –append new user COLUMN TO the HumanResources.Employee TABLE
-
- ALTER TABLE humanresources.employee ADD [User] NVARCHAR(50) GO –disable ANY triggers DISABLE TRIGGER ALL ON HumanResources.employee GO –enable CDC
- FOR AW
-
- EXEC Sp_cdc_enable_db GO –enable CDC
- FOR HumanResources.Employee
-
- EXEC Sp_cdc_enable_table humanresources
- ,employee
- ,NULL
- ,1
- ,dbo GO –create sample UDF TO
-
- RETURN change data
-
- CREATE FUNCTION [dbo].[Udf_employee] (
- @start_time DATETIME
- ,@end_time DATETIME
- )
- RETURNS @Employee TABLE (
- employeeid INT
- ,nationalidnumber NVARCHAR(15)
- ,contactid INT
- ,managerid INT
- ,title NVARCHAR(50)
- ,birthdate DATETIME
- ,maritalstatus NCHAR(1)
- ,gender NCHAR(1)
- ,hiredate DATETIME
- ,salariedflag [FLAG]
- ,vacationhours SMALLINT
- ,sickleavehours SMALLINT
- ,currentflag [FLAG]
- ,rowguid UNIQUEIDENTIFIER
- ,[user] NVARCHAR(50)
- ,cdc_operation VARCHAR(1)
- )
- AS
- BEGIN
- –declare LOCAL variables TO hold LSNs
-
- DECLARE @from_lsn BINARY (10)
- ,@to_lsn BINARY (10) –Map the TIME interval TO a change data capture query range.
-
- IF (@start_time IS NULL)
- BEGIN
- SELECT @from_lsn = sys.Fn_cdc_get_min_lsn(‘HumanResources_Employee’)
- END
- ELSE
- BEGIN
- SELECT @from_lsn = sys.Fn_cdc_map_time_to_lsn(‘smallest greater than
- OR equal’, @start_time)
- END
-
- IF (@end_time IS NULL)
- BEGIN
- SELECT @to_lsn = sys.Fn_cdc_get_max_lsn()
- END
- ELSE
- BEGIN
- SELECT @to_lsn = sys.Fn_cdc_map_time_to_lsn(‘largest less than
- OR equal’, @end_time)
- END –if same then EXIT
-
- IF (@from_lsn = sys.Fn_cdc_increment_lsn(@to_lsn))
- BEGIN
- RETURN
- END — Query
- FOR change data
-
- INSERT INTO @Employee
- SELECT employeeid
- ,nationalidnumber
- ,contactid
- ,managerid
- ,title
- ,birthdate
- ,maritalstatus
- ,gender
- ,hiredate
- ,salariedflag
- ,vacationhours
- ,sickleavehours
- ,currentflag
- ,rowguid
- ,[user]
- ,CASE __$operation
- WHEN 1
- THEN ‘D’
- WHEN 2
- THEN ‘I’
- WHEN 4
- THEN ‘U’
- ELSE NULL
- END AS cdc_operation
- FROM cdc.Fn_cdc_get_net_changes_humanresources_employee(@from_lsn, @to_lsn, ’all’)
-
- RETURN
- END GO –sample DML statement
-
- UPDATE humanresources.employee
- SET title = ‘Marketing Director’
- ,[User] = system_user
- WHERE employeeid = 13 –get the net change OF the sample DML including the User
-
- SELECT *
- FROM [dbo].[Udf_employee](NULL, NULL)
Introduction
One of the SQL Server 2008’s biggest BI features being touted is Change Data Capture (CDC). CDC is basically supposed to be a built-in solution to the old-age practice in ETL solutions of identifying and using change identifiers columns in source systems. I have now spent a fair amount of time using this feature and more importantly how to leverage it inside of SSIS packages for incremental ETL solutions. My work here has been to prepare for an upcoming demonstration of CDC in SSIS. This post/Q&A is a brief summary of my findings thus far…
*CDC is being positioned as the ‘design of choice’ for SQL Server 2008+ OLTP database servers for exposing changed relational data for data warehousing consumption purposes.
What is Change Data Capture (CDC)?
CDC records (or captures) DML activity on designated tables. CDC works by scanning the transaction log for a designated table’s ‘captured columns’ whose content has changed and then making those changes available for data syncronizing purposes in a relational format. As you can see, this feature in entrenched in transaction log architecture and thus, a lot of metadata in CDC is related around the concept of a Log Sequence Number (LSN).
So whats a LSN?
Here is the definition of a LSN per Books Online: "Every record in the Microsoft SQL Server transaction log is uniquely identified by a log sequence number (LSN). LSNs are ordered such that if LSN2 is greater than LSN1, the change described by the log record referred to by LSN2 occurred after the change described by the log record LSN. "
How do I get CDC?
CDC is a feature of SQL Server 2008 Enterprise, Developer, and Evaluation editions.
What are the target applications or consumers of the CDC technology?
ETL Solutions are the most common, however any data consuming application that requires syncronizing data could benefit from the technology.
Is CDC configurable via a UI or just TSQL?
As of this time, just TSQL.
How do you configure CDC?
- Enable CDC for a database
- Enables the current database via the USE statement *select is_cdc_enabled from sys.databases where [name] = ‘AdventureWorks’ to determine if DB is allready enabled *Also note that when you do this all of the below system objects get created in the selected database
- Enable CDC for a given table and it’s selected columns
- Specify the captured table’s schema, name, database role, capture instance name (defaults to schema_name), support net changes (bit, set it to 1 if you want both change data table-valued functions created), name of captured table’s unique index, captured column list (null/default to all columns), filegroup for the change table (null/defaults to default filegroup)
- Query Change Data via 1 of 2 built in table-valued functions created during step #2
- For all changes (meaning a row is returned for each DML) use cdc.fn_cdc_get_all_changes_<capture_instance>
- For the net changes (meaning one row returned for each source row modified among 1 or more DMLs) use cdc.fn_cdc_get_net_changes_<capture_instance>
What are all of the CDC system objects available to me?
System Tables
- cdc.captured_columns
- cdc.change_tables
- cdc.ddl_history
- cdc.index_columns
- cdc.lsn_time_mapping
- cdc.Schema_Name_CT (change tables) *this is just the default naming convention, configurable via the enable table sysproc
DMVs
- sys.dm_cdc_log_scan_sessions
- sys.dm_repl_traninfo
- sys.dm_cdc_errors
System Stored Procedures
- sys.sp_cdc_enabledb
- sys.sp_cdc_disabledb
- sys.sp_cdc_cleanup_change_table
- sys.sp_cdc_disable_db_change_data_capture
- sys.sp_cdc_disable_table_change_data_capture
- sys.sp_cdc_enable_db_change_data_capture
- sys.sp_cdc_enable_table_change_data_capture
- sys.sp_cdc_get_ddl_history
- sys.sp_cdc_get_captured_columns
- sys.sp_cdc_help_change_data_capture
System Functions
- cdc.fn_cdc_get_all_changes_<capture_instance>
- cdc.fn_cdc_get_net_changes_<capture_instance>
- sys.fn_cdc_decrement_lsn
- sys.fn_cdc_get_column_ordinal ( ‘capture_instance’ , ‘column_name’ )
- sys.fn_cdc_get_max_lsn
- sys.fn_cdc_get_min_lsn
- sys.fn_cdc_has_column_changed
- sys.fn_cdc_increment_lsn
- sys.fn_cdc_is_bit_set
- sys.fn_cdc_map_lsn_to_time
- sys.fn_cdc_map_time_to_lsn
Do the change tables keep growing?
No, there is an automatic cleanup process that occurs every three days (and this is configurable). For more intense environments, you can leverage the manual method using the system stored procedure: sys.sp_cdc_cleanup_change_table. When you execute this system procedure, you specify the low LSN and any change records occuring before this point are removed and the start_lsn is set to the low LSN you specified.
How do you leverage CDC in SSIS Packages?
Books Online in CTP5 (November) actually has a sample package in the topic ‘change data capture in integration services’ and I found this to be a good starting point to build from. For my CDC/SSIS demo here is the Control/Data Flow I am using,
- Calculate Date Intervals (these will correspond to LSNs later) *also note that in both BOL and my own package we are using fixed intervals, in the real world this will be driven by a table solution which tells the SSIS package when the last successful execution occurs (starting point of next package iteration)
- Check is any data is available in the selected date/time interval. This is important because the rest of the package will fail if no data is ready. BOL recommends performing Thead.Sleep/WAITFORs here. I am not for demo purposes but its not a bad idea.
- Build the query via a SSIS variable *BOL states that SSIS packages cannot call the cdc.fn_cdc_getnet|all functions and must use a wrapper. Whether or not we end up being forced to do this, it is a good design practice, below is my custom function that SSIS calls passing in the start/end datetime values to get the actual change data in the data flow step below.
- Create a data flow task that executes the SSIS variable query (OLEDB source), and then splits the rows into via a conditional split based on the CDC_OPERATION column calculated in the function below.
-
- CREATE FUNCTION [dbo].[Udf_promotion] (
- @start_time DATETIME
- ,@end_time DATETIME
- )
- RETURNS @Promotion TABLE (
- specialofferid INT
- ,DESCRIPTION NVARCHAR(255)
- ,discountpct SMALLMONEY
- ,[Type] NVARCHAR(50)
- ,category NVARCHAR(50)
- ,startdate DATETIME
- ,enddate DATETIME
- ,minqty INT
- ,maxqty INT
- ,rowguid UNIQUEIDENTIFIER
- ,modifieddate DATETIME
- ,cdc_operation VARCHAR(1)
- )
- AS
- BEGIN
- –declare LOCAL variables TO hold LSNs
-
- DECLARE @from_lsn BINARY (10)
- ,@to_lsn BINARY (10) –Map the TIME interval TO a change data capture query range.
-
- IF (@start_time IS NULL)
- BEGIN
- SELECT @from_lsn = sys.Fn_cdc_get_min_lsn(‘Sales_SpecialOffer’)
- END
- ELSE
- BEGIN
- SELECT @from_lsn = sys.Fn_cdc_map_time_to_lsn(‘smallest greater than
- OR equal’, @start_time)
- END
-
- IF (@end_time IS NULL)
- BEGIN
- SELECT @to_lsn = sys.Fn_cdc_get_max_lsn()
- END
- ELSE
- BEGIN
- SELECT @to_lsn = sys.Fn_cdc_map_time_to_lsn(‘largest less than
- OR equal’, @end_time)
- END –if same then EXIT
-
- IF (@from_lsn = sys.Fn_cdc_increment_lsn(@to_lsn))
- BEGIN
- RETURN
- END — Query
- FOR change data
-
- INSERT INTO @Promotion
- SELECT specialofferid
- ,DESCRIPTION
- ,discountpct
- ,[Type]
- ,category
- ,startdate
- ,enddate
- ,minqty
- ,maxqty
- ,rowguid
- ,modifieddate
- ,CASE __$operation
- WHEN 1
- THEN ‘D’
- WHEN 2
- THEN ‘I’
- WHEN 4
- THEN ‘U’
- ELSE NULL
- END AS cdc_operation
- FROM cdc.Fn_cdc_get_net_changes_sales_specialoffer(@from_lsn, @to_lsn, ’all’)
-
- RETURN
- END GO
Overall Impression?
I’m quite impressed with the new CDC feature built into the SQL Server relational engine. It is fairly easy to configure and use. In terms of enhancements, I think the matter of replacing the typical ‘ETL Run’ table should be considered. For example, when we configure this new technology going forward to replace our old source ‘change identifier’ columns we will still need a solution (usually table-based) for tracking when our ETL Packages have last ran (both successful and failed). It would be nice if we could somehow configure the CDC technology to say ‘this SSIS Package is the only consuming application, therefore purge the data in a transactional manner once I retrieve it (which we could do manual right now I believe)’. Basically, give the option of replacing the LSN filtering of records to just retrieve and purge to so I can rely on the fact that the change table only contains data I have yet to process. Also, CDC can only work with SQL Server. While this is an obvious constraint, it would be nice to overcome it since SQL Server BI Systems will typically query other types of RDBMS for their source system data and not just SQL Server.
Overall, the feature is great. It replaces the need for source column change identifers, and it relocates the ETL querying load to a seperate change table in the source system. If your organization has a complete SQL Server based environment, CDC is a great candidate for your future ETL solutions.
CDC is only available in SQL Server 2008 Enterprise, Developer ,and Evaluation editions. Furthermore, CDC is enabled at two levels, first a database level and then on specific tables you identify via the sys.sp_cdc_enable_table command.
- sys.sp_cdc_enable_table
- [ @source_schema = ] ‘source_schema’,
- [ @source_name = ] ‘source_name’ ,
- [ @role_name = ] ‘role_name’
- [,[ @capture_instance = ] ‘capture_instance’ ]
- [,[ @supports_net_changes = ] supports_net_changes ]
- [,[ @index_name = ] ‘index_name’ ]
- [,[ @captured_column_list = ] ‘captured_column_list’ ]
- [,[ @filegroup_name = ] ‘filegroup_name’ ]
- [,[ @partition_switch = ] ‘partition_switch’ ]
If you have a Master|Child detail tables you would have to enable both tables for CDC if you need to detect and consume the change data of both.