Temporal Tables–Simple Guide to implement History Tables using SQL Server 2016/2017–Part 4–Managing Temporal Tables and History Data

In previous posts, we saw

Part 1 – How to create Temporal Tables

Part 2 – Accessing History data from Temporal Tables

Part 3 – Modifying Temporal Tables, Disabling System versioning and why we need to disable ?

In this post we will see how to manage Temporal tables and History

To get list of Temporal Tables – Snippet 1

SELECT name,
       object_id,
       temporal_type,
       temporal_type_desc,
       history_table_id,
       is_remote_data_archive_enabled,
       is_external,
       history_retention_period,
       history_retention_period_unit,
       history_retention_period_unit_desc
FROM sys.tables
WHERE temporal_type > 0
ORDER BY name;

Output

If we see the output, we can identify the following

1. Type of Temporal Table – System Versioned or History table using “temporal_type” and “temporal_type_desc” columns

2. For System Versioned tables, we can also see the History Table ID

3. History Retention Period can be determined using history_retention_period, history_retention_period_unit and history_retention_period_unit_desc

history_retention_period = -1  = History is kept forever

Positive Integer = Refers to the number of Days/Weeks/Years

history_retention_period_unit will have one of these values

-1 = INFINITE

3 = DAY(S)

4 = WEEK(S)

5 = MONTH(S)

6 = YEAR(S)

By default, when we create temporal tables, if we don’t specify Retention period, it will be created with Infinite period of retention

Modifying Retention Period

Let us see how we can change Retention Period for an existing Temporal Table

Code to alter table to set Retention Period for 2 days – Snippet 2

ALTER TABLE dbo.Demo
	SET (SYSTEM_VERSIONING = ON
			(
				HISTORY_TABLE = dbo.DemoHistory,
				HISTORY_RETENTION_PERIOD = 2 DAYS
			)
		)

If we run query from Snippet 1, we will see below output

To get list of Databases with Retention Enabled – Snippet 3

Once retention period is enabled for any table in the database, SQL Server will set the is_temporal_history_retention_enabled flag = 1 for the database by default and also create background jobs to cleanup the history data

SELECT name,
       database_id,
       is_temporal_history_retention_enabled
FROM sys.databases
WHERE is_temporal_history_retention_enabled = 1
ORDER BY name;

Output

If you want to disable automatic cleanup task, Please use below command

Query to disable cleanup task – Snippet 4

ALTER DATABASE SQL2017_DEMO
     SET TEMPORAL_HISTORY_RETENTION OFF

If we run the query in Snippet 3, we can see the changes

How to cleanup History tables manually ?

If you prefer to cleanup the History tables manually rather than automated, Please follow below steps

1. Make your application offline

2. Run query to disable System versioning on required tables

3. Run query to delete data from History using SysEndTime as Filter criteria

4. Run query to enable System versioning for tables disabled in Step 2

5. Make your application online

If your application has to be on 24/7, better option is to use the in-built automated cleanup task

Hope you find this post helpful !!!

Author: Arunraj

I am a Microsoft Certified Technology Specialist (Database Developer). I work on SQL Server programming since SQL Server 7.0 specializes in SQL Server Programming and Performance Tuning and has 14 years of hands-on experience. I hold a Master Degree in Computer Applications. I am also part of NJSQL User Group and Northern New Jersey .Net User Group. View all posts by Arunraj