Skip to content

Commit

Permalink
Document asynchronous CHECK constraint validation
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
rmloveland committed Apr 15, 2019
1 parent 0d37ad3 commit 6da2683
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 3 deletions.
26 changes: 25 additions & 1 deletion v19.1/add-constraint.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,33 @@ 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);
~~~

<span class="version-tag">New in v19.1</span>: 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}}
The entire transaction will be rolled back, including any new columns that were added, in the following cases:

- If an existing column is found containing values that violate the new constraint.
- If a new column has a default value or is a [computed column](computed-columns.html) that would have contained values that violate the new constraint.
{{site.data.alerts.end}}

### Add the foreign key constraint with `CASCADE`

To add a foreign key constraint, use the steps shown below.
Expand Down
4 changes: 2 additions & 2 deletions v19.1/check.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
- <span class="version-tag">New in v19.1</span>: If you add a `CHECK` constraint to an existing table, CockroachDB will run a background job to validate existing table data in the process of adding the constraint. 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.
- <span class="version-tag">New in v19.1</span>: 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:

Expand Down

0 comments on commit 6da2683

Please sign in to comment.