Document asynchronous CHECK constraint validation

[rmloveland]

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.

[cockroach-teamcity]

This change is 

[cockroach-teamcity]

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/fe4dd1c6e0860e153eba14b5c979edf632483702/

[rmloveland]

Direct links for easier reference:

• CHECK constraint > Details
• Add constraint > Add the check constraint

[thoszhang]

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @lucy-zhang and @rmloveland)

---

v19.1/add-constraint.md, line 60 at r1 (raw file):

~~~

<span class="version-tag">New in v19.1</span>: Check constraints begin validating table data asynchronously as soon as the transaction where the constraint was added commits.  Also, check constraints can be added to columns that were created earlier in the transaction.  For example:

It's currently not entirely clear what "validating" means in this context. We should mention that if a row is found that violates the constraint during the validation step, the ADD CONSTRAINT will fail, which is very different from the previous behavior of VALIDATE CONSTRAINT. If the column was added in the same transaction, it will also be rolled back. (Currently, there's no longer a way to add a check constraint that's enforced for writes but is potentially violated for pre-existing rows.)

This can happen if someone adds a column with a default value or a computed column, and tries to add a constraint on the column in the same transaction, but the default/computed values violate the constraint. In that case, the column won't be added.

[rmloveland]

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @lucy-zhang)

---

v19.1/add-constraint.md, line 60 at r1 (raw file):

Previously, lucy-zhang (Lucy Zhang) wrote…

It's currently not entirely clear what "validating" means in this context. We should mention that if a row is found that violates the constraint during the validation step, the ADD CONSTRAINT will fail, which is very different from the previous behavior of VALIDATE CONSTRAINT. If the column was added in the same transaction, it will also be rolled back. (Currently, there's no longer a way to add a check constraint that's enforced for writes but is potentially violated for pre-existing rows.)

This can happen if someone adds a column with a default value or a computed column, and tries to add a constraint on the column in the same transaction, but the default/computed values violate the constraint. In that case, the column won't be added.

Thanks for this additional info.

I have updated this example and the CHECK constraint page, split up across them roughly as follows:

• CHECK was updated to include everything you mentioned above, since it's supposed to be a reference
• This example on ADD CONSTRAINT focuses more on the "if you add a column, then a check that fails, your add column is rolled back" since that is what's happening in the example (and the user can refer to CHECK for more info)

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/46151f9894ec17d970ddf6c302129acdffdb8e3f/

Edited pages:

• v19.1/add-constraint.md
• v19.1/check.md

[rmloveland]

@lucy-zhang are you ok with this as it stands? I'd like to move it into the docs team review stage if you're satisfied with the updates.

[rmloveland]

@lucy-zhang ping

[thoszhang]

Sorry for the delay.

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @lucy-zhang and @rmloveland)

---

v19.1/add-constraint.md, line 79 at r2 (raw file):

{{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.

I think this could still be clearer about what "existing row" means; part of the behavior is that if any value that would have been in the new column (if the column has a default/computed value) would violate the constraint, the column will not get added.

Maybe add a sentence like "If any new column has a default value or is a computed column, and would have contained values that violate the new check constraint, then the entire transaction will also be rolled back," though that's a little clunky.

---

v19.1/check.md, line 11 at r2 (raw file):
For the first sentence, I actually think

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.

or something like that would be preferable here. It's a comparable level of detail to our existing docs for online schema changes, and I'm worried people might interpret the existing sentence as "the async job runs sometime after a result for ALTER TABLE is returned to the client," which isn't the case.

[rmloveland]

No problem, thanks for the good review feedback

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @lucy-zhang)

---

v19.1/add-constraint.md, line 79 at r2 (raw file):

Previously, lucy-zhang (Lucy Zhang) wrote…

I think this could still be clearer about what "existing row" means; part of the behavior is that if any value that would have been in the new column (if the column has a default/computed value) would violate the constraint, the column will not get added.

Maybe add a sentence like "If any new column has a default value or is a computed column, and would have contained values that violate the new check constraint, then the entire transaction will also be rolled back," though that's a little clunky.

Thanks. I tried rewriting it as a bulleted list of cases (existing, new) based on your comment. PTAL.

---

v19.1/check.md, line 11 at r2 (raw file):

Previously, lucy-zhang (Lucy Zhang) wrote…

For the first sentence, I actually think

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.

or something like that would be preferable here. It's a comparable level of detail to our existing docs for online schema changes, and I'm worried people might interpret the existing sentence as "the async job runs sometime after a result for ALTER TABLE is returned to the client," which isn't the case.

Thanks for explaining that. I think I got a little turned around by trying to rephrase one of your commit messages and ended up at the wrong level of detail.

I swapped out the old sentence for yours. It sounds/looks much better to my ear/eye as well.

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/6cd3922741bbf6306fba77e323dfa5ed38562cad/

Edited pages:

• v19.1/add-constraint.md
• v19.1/check.md

[jseldess]

with a few small nits

Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on @jseldess, @lucy-zhang, and @rmloveland)

---

v19.1/add-constraint.md, line 60 at r1 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

Thanks for this additional info.

I have updated this example and the CHECK constraint page, split up across them roughly as follows:

• CHECK was updated to include everything you mentioned above, since it's supposed to be a reference
• This example on ADD CONSTRAINT focuses more on the "if you add a column, then a check that fails, your add column is rolled back" since that is what's happening in the example (and the user can refer to CHECK for more info)

nit: Remove extra space after period.

---

v19.1/check.md, line 12 at r3 (raw file):

- <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).

nit: Remove extra space after period.

[rmloveland]

Thanks for the review Jesse!

Reviewable status: complete! 0 of 0 LGTMs obtained (and 1 stale) (waiting on @jseldess and @lucy-zhang)

---

v19.1/add-constraint.md, line 60 at r1 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

nit: Remove extra space after period.

Fixed.

---

v19.1/check.md, line 12 at r3 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

nit: Remove extra space after period.

Fixed.

[cockroach-teamcity]

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/6da2683c82359f7cc8660c6c2444ac93badacefe/

Edited pages:

• v19.1/add-constraint.md
• v19.1/check.md