copy editing constraint pages #964

sploiselle · 2017-01-05T02:11:12Z

Edited pages for constraints
Unified style for referencing constraints using format constraint. For example, "the Primary Key constraint". When talking about a concept and not a constraint itself, use the term without any caps. For example, "primary key".
Changed references of "Default value" to "Default Value."

Closes #313

This change is

cockroach-teamcity · 2017-01-05T02:12:06Z

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

dt · 2017-01-11T17:51:06Z

Not sure if we care, but lots of cases where we say things restrict values inserted but it constraints all writes, including UPDATES.

Mentioned in one place but applicable elsewhere: no difference between expressing a constraint on a col or at table level except for NULL and DEFAULT. We should probably document the table level and then only mention the single-col as a shorthand.

Reviewed 4 of 25 files at r1.
Review status: 4 of 25 files reviewed at latest revision, 11 unresolved discussions.

check.md, line 13 at r1 (raw file):

## Details

- If you add a Check constraint to an existing table, existing values are not checked. However, any updates to those values will be.

We might want to note that this is is a temporary limitation, not a permanent design decision -- in the future, the modifier NOT VALID would trigger this behavior (where the check is added quickly but only applies to new writes), but the default will be to check existing data. Currently we always do the NOT VALID behavior only because we haven't implemented queuing up the validation.

check.md, line 103 at r1 (raw file):

- [Constraints](constraints.html)
- [`DROP CONSTRAINTS`](drop-constraint.html)

Should this be plural?

constraints.md, line 7 at r1 (raw file):

---

Constraints provide additional data integrity beyond SQL's type checking. They let you define additional parameters for a column's data, which are checked whenever values are manipulated (inserted, deleted, or updated) and reject modifications that violate the constraint.

I don't know if I'd really think about them as related to type checking -- it's more about domain/business logic specific to your application being additionally enforced by the DB -- you could (and probably should, to have more control over error handling) check these things in your application, but also adding constraints on the db itself is an additional layer of safety, particularly for something like FKs where the app may operate on related tables separately.

constraints.md, line 9 at r1 (raw file):

Constraints provide additional data integrity beyond SQL's type checking. They let you define additional parameters for a column's data, which are checked whenever values are manipulated (inserted, deleted, or updated) and reject modifications that violate the constraint.

For example, the Unique constraint requires that all values in a column be unique from one another (except *NULL* values). If you attempt to insert a duplicate value, the constraint rejects the entire statement.

updates can also create dupes.

not-null.md, line 23 at r1 (raw file):

  CockroachDB tries to write a *NULL* value into column `b`. If that column has the Not Null constraint, the `INSERT` statement is rejected.

- You can only define the Not Null constraint when [creating a table](#syntax); you cannot add it to an existing table. However, you can [migrate data](constraints.html#table-migrations-to-add-or-change-immutable-constraints) from your current table to a new table with the constraint you want to use.

might want to note this is only current limitation, not a long-term decision.

not-null.md, line 75 at r1 (raw file):

- [Constraints](constraints.html)
- [`DROP CONSTRAINTS`](drop-constraint.html)

plural?

unique.md, line 3 at r1 (raw file):

---
title: Unique Constraint
summary: The Unique constraint specifies that each value in the constrained column must be unique (though *NULL* values are still allowed).

"still" seems strange to me (ditto below).
maybe just "non-null values must be unique?

unique.md, line 13 at r1 (raw file):

## Details

- You can still insert *NULL* values into columns with the Unique constraint because *NULL*s are not considered equal to other *NULL*s and therefore don't appear as the same value. This means that it's possible to insert rows that appear to be duplicates if one of the values is *NULL*.

I might lead with the fact that NULL is the absence of a value, so it is never equal and thus not considered a duplicate value. Thus if one uses NULL for one of the columns in a constraint etc.

unique.md, line 23 at r1 (raw file):

## Syntax

The syntax of the Unique constraint depends on whether you want the constraint to use a [single column](#single-column-column-level) or [multiple columns](#multiple-column-table-level).

Eh, you can use the table-level constraint on a single col -- in fact, except for DEFAULT and NULL, the col-level one is just a shorthand that we translate to table level constraint (on a single-col) before evaluating it, so that's what you'll see in SHOW CREATE TABLE.

unique.md, line 73 at r1 (raw file):

## Usage Example

Be aware that if a table has a Unique constraint on columns without the [Not Null constraint](not-null.html), it is possible to insert rows that appear to be duplicates if they contain a *NULL* value in at least one of the columns. This is because *NULL*s are never considered equal and hence don't violate the uniqueness constraint.

Maybe just me, but I found this one a little hard to follow / it sounded like we had some sort of defect that meant I needed to use NOT NULL for it to work, and it's duplicative with the statement above about nulls.

unique.md, line 101 at r1 (raw file):

- [Constraints](constraints.html)
- [`DROP CONSTRAINTS`](drop-constraint.html)

plural?

Comments from Reviewable

jseldess · 2017-01-12T15:57:45Z

@sploiselle, would you mind incorporating this change into the foreign key doc as well? #990

Here's how Ben summarized it in this week's release notes:

The ALTER TABLE VALIDATE CONSTRAINT command can now be used to validate foreign keys in the UNVALIDATED state.

It's another ALTER TABLE substatement, though, so if you prefer we handle this separately, that's fine, too. Just seems like we'll need to reference the substatement in the FK doc.

sploiselle · 2017-01-12T18:04:20Z

Review status: 4 of 25 files reviewed at latest revision, 11 unresolved discussions.

check.md, line 13 at r1 (raw file):