Skip to content

Commit d002d58

Browse files
denreadenrea
authored
Merge pull request #22107 from VanMSFT/resumabletableconstr2022
adding resumable table add constraints
2 parents bb728c6 + 4ba7a29 commit d002d58

6 files changed

Lines changed: 228 additions & 9 deletions

File tree

‎docs/relational-databases/security/resumable-add-table-constraints.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
title: "Resumable add table constraints"
3+
description: New resumable capabilities to support pausing and resuming a running ALTER TABLE ADD CONSTRAINT operation.
4+
ms.custom: ""
5+
ms.date: "05/24/2022"
6+
ms.prod: sql
7+
ms.reviewer: ""
8+
ms.technology: security
9+
ms.topic: conceptual
10+
author: VanMSFT
11+
ms.author: vanto
12+
monikerRange: ">=sql-server-ver16||>= sql-server-linux-ver16"
13+
---
14+
15+
# Resumable add table constraints
16+
17+
[!INCLUDE [SQL Server 2022](../../includes/applies-to-version/sqlserver2022.md)]
18+
19+
Starting with SQL Server 2022, resumable operations for online index creation and rebuild are supported. The resumable operations allow index operations to be executed while the table is [online](/sql/t-sql/statements/alter-table-transact-sql#with--online--on--off-as-applies-to-altering-a-column) (`ONLINE=ON`) and also:
20+
21+
- Pause and restart an index create or rebuild operation multiple times to fit a maintenance window
22+
23+
- Recover from index creation or rebuild failures, such as database failovers or running out of disk space.
24+
25+
- Enable truncation of transaction logs during an index creation or rebuild operation.
26+
27+
- When an index operation is paused, both the original index and the newly created one require disk space and need to be updated during [Data Manipulation Language (DML)](/sql/t-sql/statements/statements#data-manipulation-language) operations.
28+
29+
The new SQL Server extensions allow a resumable operation for the [Data Definition Language (DDL)](/sql/t-sql/statements/statements#data-definition-language) command [ALTER TABLE ADD CONSTRAINT](/sql/t-sql/statements/alter-table-transact-sql) and adding a Primary or Unique Key. For more information on adding a Primary or Unique Key, see [ALTER TABLE table_constraint](/sql/t-sql/statements/alter-table-table-constraint-transact-sql).
30+
31+
## Resumable operations
32+
33+
In previous versions of SQL Server, the `ALTER TABLE ADD CONSTRAINT` operation can be executed with the `ONLNE=ON` option. However, the operation may take many hours for a large table to complete, and can consume a great number of resources. There's also the possibility of failures or interruption during such execution. We've introduced resumable capabilities to `ALTER TABLE ADD CONSTRAINT` for users to pause the operation during a maintenance window, or to restart it from where it was interrupted during an execution failure, without restarting the operation from the beginning.
34+
35+
## Supported scenarios
36+
37+
The new resumable capability for `ALTER TABLE ADD CONSTRAINT` supports the following customer scenarios:
38+
39+
- Pause or resume running `ALTER TABLE ADD CONSTRAINT` operation, such as pausing it for a maintenance window, and resuming the operation once the maintenance window is complete.
40+
41+
- Resume `ALTER TABLE ADD CONSTRAINT` operation after failovers and system failures.
42+
43+
- Executing `ALTER TABLE ADD CONSTRAINT` operation on a large table despite the small log size available.
44+
45+
> [!NOTE]
46+
> The resumable operation for `ALTER TABLE ADD CONSTRAINT` requires the `ALTER` command to be executed online (`WITH ONLINE = ON`).
47+
48+
This feature is especially useful for large tables.
49+
50+
## T-SQL Syntax for ALTER TABLE
51+
52+
For information on the syntax used to enable resumable operations on a table constraint, see the syntax and options in [ALTER TABLE (Transact-SQL)](/sql/t-sql/statements/alter-table-transact-sql#resumable).
53+
54+
### Remarks for ALTER TABLE
55+
56+
- A new clause **WITH <resumable_options** have been added to the current T-SQL syntax in [ALTER TABLE (Transact-SQL)](/sql/t-sql/statements/alter-table-transact-sql).
57+
58+
- The option **RESUMABLE** is new and has been added to the existing [ALTER TABLE (Transact-SQL)](/sql/t-sql/statements/alter-table-transact-sql) syntax.
59+
60+
- `MAX_DURATION` = *time* \[MINUTES\] used with `RESUMABLE = ON` (requires `ONLINE = ON`). `MAX_DURATION` indicates time (an integer value specified in minutes) that a resumable online add constraint operation is executed before being paused. If not specified, the operation continues until completion.
61+
62+
## T-SQL syntax for ALTER INDEX
63+
64+
To pause, resume, or abort the resumable table constraint operation for `ALTER TABLE ADD CONSTRAINT`, use the T-SQL syntax [ALTER INDEX (Transact-SQL)](/sql/t-sql/statements/alter-index-transact-sql).
65+
66+
For resumable constraints the existing ALTER INDEX ALL command is used.
67+
68+
```syntaxsql
69+
ALTER INDEX ALL ON <table_name>
70+
{ RESUME [WITH (<resumable_index_options>,[...n])]
71+
| PAUSE
72+
| ABORT
73+
}
74+
<resumable_index_option> ::=
75+
{
76+
MAXDOP = max_degree_of_parallelism
77+
| MAX_DURATION =<time> [MINUTES]
78+
| <low_priority_lock_wait>
79+
}
80+
<low_priority_lock_wait>::=
81+
{
82+
WAIT_AT_LOW_PRIORITY ( MAX_DURATION = <time> [ MINUTES ] ,
83+
ABORT_AFTER_WAIT = { NONE | SELF | BLOCKERS } )
84+
}
85+
```
86+
87+
### Remarks for ALTER INDEX
88+
89+
`ALTER INDEX ALL ON <Table> PAUSE`
90+
91+
- Pause a resumable and online add table constraint operation that is being executed
92+
93+
`ALTER INDEX ALL ON <Table> RESUME [WITH (<resumable_index_options>,[...n])]`
94+
95+
- Resume an add table constraint operation that is paused manually or due to a failure.
96+
97+
`MAX_DURATION` used with `RESUMABLE=ON `
98+
99+
- The time (an integer value specified in minutes) that the resumable add table constraint operation is executed after being resumed. Once the time expires, the resumable operation is paused if it's still running.
100+
101+
`WAIT_AT_LOW_PRIORITY` used with `RESUMABLE=ON` and `ONLINE = ON`
102+
103+
- Resuming an online add table constraint operation after a pause must wait for blocking operations on this table. `WAIT_AT_LOW_PRIORITY` indicates that the add table constraint operation will wait for low priority locks, allowing other operations to proceed while the resumable operation is waiting. Omitting the `WAIT_AT_LOW_PRIORITY` option is equivalent to `WAIT_AT_LOW_PRIORITY (MAX_DURATION = 0 minutes, ABORT_AFTER_WAIT = NONE)`. For more information, see [WAIT_AT_LOW_PRIORITY](/sql/t-sql/statements/alter-index-transact-sql#wait-at-low-priority).
104+
105+
`ALTER INDEX ALL ON <Table> ABORT`
106+
107+
- Abort a running or paused add table constraint operation that was declared as resumable. The abort operation must be explicitly executed as an `ABORT` command to terminate a resumable constraint operation. Failure or pausing a resumable table constraint operation doesn't terminate its execution. Rather, it leaves the operation in an indefinite paused state.
108+
109+
For more information on `PAUSE`, `RESUME`, and `ABORT` options available for resumable operations, see [ALTER INDEX (Transact-SQL)](/sql/t-sql/statements/alter-index-transact-sql).
110+
111+
## View the status for resumable operation
112+
113+
To view the status for the resumable table constraint operation, use the view [sys.index_resumable_operations](/sql/relational-databases/system-catalog-views/sys-index-resumable-operations).
114+
115+
## Permissions
116+
117+
Requires `ALTER` permission on the table.
118+
119+
No new permissions for resumable `ALTER TABLE ADD CONSTRAINT` are required.
120+
121+
## Examples
122+
123+
Here are some examples on using resumable add table constraint operations.
124+
125+
### Example 1
126+
127+
Resumable `ALTER TABLE` operation for adding a primary key clustered on column (a) with `MAX_DURATION` of 240 minutes.
128+
129+
```sql
130+
ALTER TABLE table1
131+
ADD CONSTRAINT PK_Constrain PRIMARY KEY CLUSTERED (a)
132+
WITH (ONLINE = ON, MAXDOP = 2, RESUMABLE = ON, MAX_DURATION = 240);
133+
```
134+
135+
### Example 2
136+
137+
Resumable `ALTER TABLE` operation for adding a unique constraint on two columns (a and b) with `MAX_DURATION` of 240 minutes.
138+
139+
```sql
140+
ALTER TABLE table2
141+
ADD CONSTRAINT PK_Constrain UNIQUE CLUSTERED (a,b)
142+
WITH (ONLINE = ON, MAXDOP = 2, RESUMABLE = ON, MAX_DURATION = 240);
143+
```
144+
145+
### Example 3
146+
147+
`ALTER TABLE` operation for adding a primary key clustered being paused and resumed.
148+
149+
The table below shows two sessions (`Session #1` and `Session #2`) being executed chronologically using the following T-SQL statements. `Session #1` executes a resumable `ALTER TABLE ADD CONSTRAINT` operation creating a primary key on column `Col1`. `Session #2` checks the execution status for the running constraint. After some time, it pauses the reusable operation. `Session #2` checks the status for the paused constraint. Finally, `Session #1` resumes the paused constraint and `Session #2` checks the status again.
150+
151+
|Session #1|Session #2|
152+
|-----|-----|
153+
|Execute resumable add constraint <br><br> `ALTER TABLE TestConstraint` <br> `ADD CONSTRAINT PK_TestConstraint PRIMARY KEY (Col1)` <br> `WITH (ONLINE = ON, MAXDOP = 2, RESUMABLE = ON, MAX_DURATION = 30);`||
154+
||Check the constraint status <br><br> `SELECT sql_text, state_desc, percent_complete` <br> `FROM sys.index_resumable_operations;`|
155+
|Output showing the operation <br><br> <table border="1"><tr><td>**sql_text**</td><td>**state_desc**</td><td>**percent_complete**</td></tr><tr><td>`ALTER TABLE TestConstraint (...)`</td><td>RUNNING</td><td>43.552</td></tr></table>||
156+
||Pause the resumable constraint <br><br> `ALTER INDEX ALL ON TestConstraint PAUSE;`|
157+
|**Error** <br><br> `Msg 1219, Level 16, State 1, Line 6` <br> `Your session has been disconnected because of a high priority DDL operation.` <br><br> `Msg 1750, Level 16, State 1, Line 6` <br> `Could not create constraint or index. See previous errors.` <br><br> `Msg 0, Level 20, State 0, Line 5` <br> `A severe error occurred on the current command.` <br> `The results, if any, should be discarded.`||
158+
||Check the constraint status <br><br> `SELECT sql_text, state_desc, percent_complete` <br> `FROM sys.index_resumable_operations;`|
159+
|Output showing the operation <br><br> <table border="1"><tr><td>**sql_text**</td><td>**state_desc**</td><td>**percent_complete**</td></tr><tr><td>`ALTER TABLE TestConstraint (...)`</td><td>PAUSED</td><td>65.339</td></tr></table>||
160+
|`ALTER INDEX ALL ON TestConstraint RESUME;`||
161+
||Check the constraint status <br><br> `SELECT sql_text, state_desc, percent_complete` <br> `FROM sys.index_resumable_operations;`|
162+
|Output showing the operation <br><br> <table border="1"><tr><td>**sql_text**</td><td>**state_desc**</td><td>**percent_complete**</td></tr><tr><td>`ALTER TABLE TestConstraint (...)`</td><td>RUNNING</td><td>90.238</td></tr></table>||
163+
164+
Once the operation is completed, execute the following T-SQL statement to check the constraint:
165+
166+
```sql
167+
SELECT constraint_name, table_name, constraint_type
168+
FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS WHERE CONSTRAINT_TYPE='PRIMARY KEY';
169+
GO
170+
```
171+
172+
Here's the result set:
173+
174+
|constraint_name|table_name|constraint_type|
175+
|-----|-----|-----|
176+
|PK_Constraint|TestConstraint|PRIMARY KEY|
177+
178+
## See also
179+
180+
- [Guidelines for Online Index Operations](/sql/relational-databases/indexes/guidelines-for-online-index-operations)
181+
- [CREATE INDEX (Transact-SQL)](/sql/t-sql/statements/create-index-transact-sql)
182+
- [ALTER INDEX (Transact-SQL)](/sql/t-sql/statements/alter-index-transact-sql)
183+
- [sys.index_resumable_operations](/sql/relational-databases/system-catalog-views/sys-index-resumable-operations)
184+
- [WAIT_AT_LOW_PRIORITY](/sql/t-sql/statements/alter-index-transact-sql#wait-at-low-priority)
185+
- [ALTER TABLE (Transact-SQL)](/sql/t-sql/statements/alter-table-transact-sql)
186+
- [ALTER TABLE index_option](/sql/t-sql/statements/alter-table-index-option-transact-sql)

‎docs/sql-server/what-s-new-in-sql-server-2022.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ The following sections provide an overview of these features.
121121
| Time series functions | You can store and analyze data that changes over time, using time-windowing, aggregation, and filtering capabilities.<br/>- [DATE_BUCKET](../t-sql/functions/date-bucket-transact-sql.md)<br/>- [GENERATE_SERIES](../t-sql/functions/generate-series-transact-sql.md)<br/><br/>The following adds support to IGNORE NULLS and RESPECT NULLS:<br/>- [FIRST_VALUE](../t-sql/functions/first-value-transact-sql.md)<br/>- [LAST_VALUE](../t-sql/functions/last-value-transact-sql.md)|
122122
| JSON functions | - [ISJSON (Transact-SQL)](../t-sql/functions/isjson-transact-sql.md)<br/>- [JSON_PATH_EXISTS (Transact-SQL)](../t-sql/functions/json-path-exists-transact-sql.md)<br/>- [JSON_OBJECT (Transact-SQL)](../t-sql/functions/json-object-transact-sql.md)<br/>- [JSON_ARRAY (Transact-SQL)](../t-sql/functions/json-array-transact-sql.md)|
123123
|SELECT ... WINDOW clause | Determines the partitioning and ordering of a rowset before the window function which uses the window in OVER clause is applied. See [SELECT - WINDOW - (Transact-SQL)](../t-sql/queries/select-window-transact-sql.md).|
124-
| Resumable ALTER TABLE ADD CONSTRAINT | Support to pause, and resume a running ADD CONSTRAINT operation to perform it during maintenance windows. Resume such operation after failovers and system failures. Execute such operation on a large table despite the small log size available. See [ALTER TABLE (Transact-SQL)](../t-sql/statements/alter-table-transact-sql.md)|
124+
| Resumable add table constraints | Supports [pausing and resuming an ALTER TABLE ADD CONSTRAINT](/sql/relational-databases/security/resumable-table-add-constraints) operation. Resume such operation after maintenance windows, failovers, or system failures.
125125
|T-SQL functions |- [GREATEST (Transact-SQL)](../t-sql/functions/logical-functions-greatest-transact-sql.md)<br/>- [LEAST (Transact-SQL)](../t-sql/functions/logical-functions-least-transact-sql.md)<br/>- [STRING_SPLIT (Transact-SQL)](../t-sql/functions/string-split-transact-sql.md).|
126126

127127
## Tools

‎docs/t-sql/statements/alter-table-index-option-transact-sql.md‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
description: "ALTER TABLE index_option (Transact-SQL)"
33
title: "ALTER TABLE index_option (Transact-SQL)"
44
ms.custom: ""
5-
ms.date: 05/09/2022
5+
ms.date: 05/24/2022
66
ms.prod: sql
77
ms.prod_service: "database-engine, sql-database"
88
ms.reviewer: randolphwest
@@ -41,7 +41,9 @@ ms.author: wiassaf
4141
| XML_COMPRESSION = { ON | OFF }
4242
[ ON PARTITIONS ({ <partition_number_expression> | <range> }
4343
[ , ...n ] ) ]
44-
| ONLINE = { ON [ ( <low_priority_lock_wait> ) ] | OFF }
44+
| ONLINE = { ON | OFF }
45+
| RESUMABLE = { ON | OFF }
46+
| MAX_DURATION = <time> [MINUTES]
4547
}
4648
4749
<range> ::=
@@ -59,7 +61,7 @@ ms.author: wiassaf
5961
{
6062
WAIT_AT_LOW_PRIORITY ( MAX_DURATION = <time> [ MINUTES ] ,
6163
ABORT_AFTER_WAIT = { NONE | SELF | BLOCKERS } )
62-
}
64+
}
6365
```
6466

6567
[!INCLUDE[sql-server-tsql-previous-offline-documentation](../../includes/sql-server-tsql-previous-offline-documentation.md)]
@@ -168,7 +170,16 @@ Specifies whether or not to optimize for last-page insert contention. The defaul
168170

169171
> [!NOTE]
170172
> Online index operations are not available in every edition of [!INCLUDE[msCoName](../../includes/msconame-md.md)][!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)]. For a list of features that are supported by the editions of [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)], see [Features Supported by the Editions of SQL Server 2016](~/sql-server/editions-and-supported-features-for-sql-server-2016.md).
171-
173+
174+
RESUMABLE = { ON | OFF}
175+
**Applies to**: SQL Server 2022 and later.
176+
177+
Specifies whether an `ALTER TABLE ADD CONSTRAINT` operation is resumable. Add table constraint operation is resumable when `ON`. Add table constraint operation is not resumable when `OFF`. Default is `OFF`. When the `RESUMABLE` option is set to `ON`, the option `ONLINE = ON` is required.
178+
179+
**MAX_DURATION** when used with `RESUMABLE = ON` (requires `ONLINE = ON`) indicates time (an integer value specified in minutes) that a resumable online add constraint operation is executed before being paused. If not specified, the operation continues until completion. **MAXDOP** is supported with `RESUMABLE = ON` as well.
180+
181+
For more information on enabling and using resumable `ALTER TABLE ADD CONSTRAINT` operations, see [Resumable add table constraints](/sql/relational-databases/security/resumable-add-table-constraints).
182+
172183
MAXDOP **=**_max_degree_of_parallelism_
173184
**Applies to**: [!INCLUDE[ssKatmai](../../includes/sskatmai-md.md)] and later.
174185

‎docs/t-sql/statements/alter-table-table-constraint-transact-sql.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
description: "ALTER TABLE table_constraint (Transact-SQL)"
33
title: "table_constraint (Transact-SQL) | Microsoft Docs"
44
ms.custom: ""
5-
ms.date: "03/01/2019"
5+
ms.date: "05/24/2022"
66
ms.prod: sql
77
ms.prod_service: "database-engine, sql-database"
88
ms.reviewer: ""
@@ -187,6 +187,8 @@ ms.author: vanto
187187
When FOREIGN KEY or CHECK constraints are added, all existing data is verified for constraint violations unless the WITH NOCHECK option is specified. If any violations occur, ALTER TABLE fails and an error is returned. When a new PRIMARY KEY or UNIQUE constraint is added to an existing column, the data in the column or columns must be unique. If duplicate values are found, ALTER TABLE fails. The WITH NOCHECK option has no effect when PRIMARY KEY or UNIQUE constraints are added.
188188

189189
Each PRIMARY KEY and UNIQUE constraint generates an index. The number of UNIQUE and PRIMARY KEY constraints cannot cause the number of indexes on the table to exceed 999 nonclustered indexes and 1 clustered index. Foreign key constraints do not automatically generate an index. However, foreign key columns are frequently used in join criteria in queries by matching the column or columns in the foreign key constraint of one table with the primary or unique key column or columns in the other table. An index on the foreign key columns enables the [!INCLUDE[ssDE](../../includes/ssde-md.md)] to quickly find related data in the foreign key table.
190+
191+
SQL Server 2022 introduces resumable operations for adding table constraints for primary key and unique key constraints. For more information on enabling and using resumable `ALTER TABLE ADD CONSTRAINT` operations, see [Resumable add table constraints](/sql/relational-databases/security/resumable-add-table-constraints).
190192

191193
## Examples
192194
For examples, see [ALTER TABLE &#40;Transact-SQL&#41;](../../t-sql/statements/alter-table-transact-sql.md).

0 commit comments

Comments
 (0)