Primary Key Constraint

On this page

The Primary Key constraint specifies that the constrained columns' values must uniquely identify each row.

Unlike other constraints which have very specific uses, the Primary Key constraint should be used for every table because it provides an intrinsic structure to the table's data. This both makes it easier to understand, as well as improving query performance.

Note:

A table's primary key can only be specified in the CREATE TABLE statement. It cannot be changed later using ALTER TABLE, though it is possible to go through a process to create a new table with the new primary key you want and then migrate the data.

Details

Tables can only have one primary key.
To ensure each row has a unique identifier, the Primary Key constraint combines the properties of both the Unique and Not Null constraints. The properties of both constraints are necessary to make sure each row's primary key columns contain distinct sets of values.
- The properties of the Unique constraint ensure that each value is distinct from all other values.
- However, because NULL values never equal other NULL values, the Unique constraint is not enough (two rows can appear the same if one of the values is NULL). To prevent the appearance of duplicated values, the Primary Key constraint also enforces the properties of the Not Null constraint.
The columns in the Primary Key constraint are used to create its primary index, which CockroachDB uses by default to access the table's data.

This index does not take up additional disk space (unlike secondary indexes, which do) because CockroachDB uses the primary index to structure the table's data in the key-value layer. For more information, see our blog post SQL in CockroachDB: Mapping Table Data to Key-Value Storage.

For optimal performance, we recommend defining a primary key for every table.

If you create a table without defining a primary key, CockroachDB uses a unique identifier for each row, which it then uses for the primary index. Because you cannot meaningfully use this unique row identifier column to filter table data, it does not offer any performance optimization. This means you will always have improved performance by defining a primary key for a table. For more information, see our blog post Index Selection in CockroachDB.

Syntax

Primary Key constraints can be defined at the table level. However, if you only want the constraint to apply to a single column, it can be applied at the column level.

Column Level

Parameter	Description
`table_name`	The name of the table you're creating.
`column_name`	The name of the Primary Key column.
`column_type`	The Primary Key column's data type.
`column_constraints`	Any other column-level constraints you want to apply to this column.
`column_def`	Definitions for any other columns in the table.
`table_constraints`	Any table-level constraints you want to apply.

Example

> CREATE TABLE orders (
    order_id        INT PRIMARY KEY,
    order_date      TIMESTAMP NOT NULL,
    order_mode      STRING(8),
    customer_id     INT,
    order_status    INT
  );

Table Level

Parameter	Description
`table_name`	The name of the table you're creating.
`column_def`	Definitions for any other columns in the table.
`name`	The name you want to use for the constraint, which must be unique to its table and follow these identifier rules.
`column_name`	The name of the column you want to use as the Primary Key. The order in which you list columns here affects the structure of the `primary` index.
`table_constraints`	Any other table-level constraints you want to apply.

Example

> CREATE TABLE IF NOT EXISTS inventories (
    product_id        INT,
    warehouse_id      INT,
    quantity_on_hand  INT NOT NULL,
    PRIMARY KEY (product_id, warehouse_id)
  );

Usage Example

> CREATE TABLE IF NOT EXISTS inventories (
    product_id        INT,
    warehouse_id      INT,
    quantity_on_hand  INT NOT NULL,
    PRIMARY KEY (product_id, warehouse_id)
  );

> INSERT INTO inventories VALUES (1, 1, 100);

> INSERT INTO inventories VALUES (1, 1, 200);

pq: duplicate key value (product_id,warehouse_id)=(1,1) violates unique constraint "primary"

> INSERT INTO inventories VALUES (1, NULL, 100);

pq: null value in column "warehouse_id" violates not-null constraint

Pricing

Contact us

Sign In