Cockroach Labs supports the current stable release and two releases prior. Therefore, this version will no longer be supported after the Spring 2019 release.

The ADD CONSTRAINT statement is part of ALTER TABLE and can add the following constraints to columns:


The Primary Key and Not Null constraints can only be applied through CREATE TABLE. The Default constraint is managed through ALTER COLUMN.


ALTER TABLE IF EXISTS table_name ADD CONSTRAINT name constraint_elem

Required Privileges

The user must have the CREATE privilege on the table.


Parameter Description
table_name The name of the table containing the column you want to constrain.
name The name of the constraint, which must be unique to its table and follow these identifier rules.
constraint_elem The Check, Foreign Keys, Unique constraint you want to add.

Adding/changing a Default constraint is done through ALTER COLUMN.

Adding/changing the table's Primary Key is not supported through ALTER TABLE; it can only be specified during table creation.

Viewing Schema Changes New in v1.1

Whenever you initiate a schema change, CockroachDB registers it as a job, which you can view with SHOW JOBS.


Add the Unique Constraint

Adding the Unique constraint requires that all of a column's values be distinct from one another (except for NULL values).

> ALTER TABLE orders ADD CONSTRAINT id_customer_unique UNIQUE (id, customer);

Add the Check Constraint

Adding the Check constraint requires that all of a column's values evaluate to TRUE for a Boolean expression.

> ALTER TABLE orders ADD CONSTRAINT total_0_check CHECK (total > 0);

Add the Foreign Key Constraint

Before you can add the Foreign Key constraint to columns, the columns must already be indexed. If they are not already indexed, use CREATE INDEX to index them and only then use the ADD CONSTRAINT statement to add the Foreign Key constraint to the columns.

For example, let's say you have two simple tables, orders and customers:

> SHOW CREATE TABLE customers;
|   Table   |                   CreateTable                   |
| customers | CREATE TABLE customers (␤                       |
|           |     id INT NOT NULL,␤                           |
|           |     "name" STRING NOT NULL,␤                    |
|           |     address STRING NULL,␤                       |
|           |     CONSTRAINT "primary" PRIMARY KEY (id ASC),␤ |
|           |     FAMILY "primary" (id, "name", address)␤     |
|           | )                                               |
(1 row)
| Table  |                                                 CreateTable                                                 |
| orders | CREATE TABLE orders (␤                                                                                      |
|        |     id INT NOT NULL,␤                                                                                       |
|        |     customer_id INT NULL,␤                                                                                  |
|        |     status STRING NOT NULL,␤                                                                                |
|        |     CONSTRAINT "primary" PRIMARY KEY (id ASC),␤                                                             |
|        |     FAMILY "primary" (id, customer_id, status),␤                                                            |
|        |     CONSTRAINT check_status CHECK (status IN ('open':::STRING, 'complete':::STRING, 'cancelled':::STRING))␤ |
|        | )                                                                                                           |
(1 row)

To ensure that each value in the orders.customer_id column matches a unique value in the column, you want to add the Foreign Key constraint to orders.customer_id. So you first create an index on orders.customer_id:

> CREATE INDEX ON orders (customer_id);

Then you add the Foreign Key constraint:

> ALTER TABLE orders ADD CONSTRAINT customer_fk FOREIGN KEY (customer_id) REFERENCES customers (id);

If you had tried to add the constraint before indexing the column, you would have received an error:

pq: foreign key requires an existing index on columns ("customer_id")

See Also

Yes No