From 46151f9894ec17d970ddf6c302129acdffdb8e3f Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 28 Mar 2019 17:05:01 -0400 Subject: [PATCH] Document asynchronous CHECK constraint validation Fixes #4362. Summary of changes: - Update `CHECK` constraint page to note that validation is now asynchronous. - Update 'Add Constraint' page to note that validation is now asynchronous, and to give an example of adding a CHECK constraint to a column added earlier in the same transaction. --- v19.1/add-constraint.md | 23 ++++++++++++++++++++++- v19.1/check.md | 4 ++-- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/v19.1/add-constraint.md b/v19.1/add-constraint.md index a466ab06ff6..44eb087e479 100644 --- a/v19.1/add-constraint.md +++ b/v19.1/add-constraint.md @@ -55,9 +55,30 @@ Adding the [`CHECK` constraint](check.html) requires that all of a column's valu {% include copy-clipboard.html %} ~~~ sql -> ALTER TABLE orders ADD CONSTRAINT total_0_check CHECK (total > 0); +> ALTER TABLE orders ADD CONSTRAINT check_id_non_zero CHECK (id > 0); ~~~ +New in v19.1: Check constraints can be added to columns that were created earlier in the transaction. For example: + +{% include copy-clipboard.html %} +~~~ sql +> BEGIN; +> ALTER TABLE customers ADD COLUMN gdpr_status STRING; +> ALTER TABLE customers ADD CONSTRAINT check_gdpr_status CHECK (gdpr_status IN ('yes', 'no', 'unknown')); +> COMMIT; +~~~ + +~~~ +BEGIN +ALTER TABLE +ALTER TABLE +COMMIT +~~~ + +{{site.data.alerts.callout_info}} +If an existing row is found that violates the check constraint, the entire transaction will be rolled back, including any new columns that were added. +{{site.data.alerts.end}} + ### Add the foreign key constraint with `CASCADE` Before you can add the [foreign key](foreign-key.html) constraint to columns, the columns must already be indexed. If they are not already indexed, use [`CREATE INDEX`](create-index.html) to index them and only then use the `ADD CONSTRAINT` statement to add the Foreign Key constraint to the columns. diff --git a/v19.1/check.md b/v19.1/check.md index 7257f5500c4..dc39bc34971 100644 --- a/v19.1/check.md +++ b/v19.1/check.md @@ -6,10 +6,10 @@ toc: true The `CHECK` [constraint](constraints.html) specifies that values for the column in [`INSERT`](insert.html) or [`UPDATE`](update.html) statements must return `TRUE` or `NULL` for a Boolean expression. If any values return `FALSE`, the entire statement is rejected. - ## Details -- If you add a `CHECK` constraint to an existing table, added values, along with any updates to current values, are checked. To check the existing rows, use [`VALIDATE CONSTRAINT`](validate-constraint.html). +- New in v19.1: If you add a `CHECK` constraint to an existing table, CockroachDB starts validating existing table data asynchronously as soon as the transaction where the constraint was added commits. If a row is found that violates the constraint during the validation step, the [`ADD CONSTRAINT`](add-constraint.html) statement will fail. This differs from previous versions of CockroachDB, which allowed you to add a check constraint that was enforced for writes but could be violated by rows that existed prior to adding the constraint. +- New in v19.1: Check constraints can be added to columns that were created earlier in the same transaction. For an example, see [Add the `CHECK` constraint](add-constraint.html#add-the-check-constraint). - `CHECK` constraints may be specified at the column or table level and can reference other columns within the table. Internally, all column-level `CHECK` constraints are converted to table-level constraints so they can be handled consistently. - You can have multiple `CHECK` constraints on a single column but ideally, for performance optimization, these should be combined using the logical operators. For example: