Skip to content

correct & update example to add/drop constraint #21542

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
taroface wants to merge 2 commits into
base: main
Choose a base branch
from
Open

correct & update example to add/drop constraint #21542

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bec8f77
correct & update example to add/drop constraint
taroface Dec 8, 2025
9fcb5fc
drop bad Gemfile line
taroface Dec 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion src/current/Gemfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ gem "redcarpet", "~> 3.6"
gem "rss"
gem "webrick"
gem "jekyll-minifier"
gem "bundler", "~> 2.4"
Copy link
Contributor

@rmloveland rmloveland Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think this should be a separate docs-infra type PR


group :jekyll_plugins do
gem "jekyll-include-cache"
Expand Down
73 changes: 32 additions & 41 deletions src/current/v23.2/alter-table.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1153,71 +1153,66 @@ By default, referenced columns must be in the same database as the referencing f

#### Drop and add a primary key constraint

Suppose that you want to add `name` to the composite primary key of the `users` table, [without creating a secondary index of the existing primary key](#changing-primary-keys-with-add-constraint-primary-key).
Suppose that you want to add `creation_time` to the composite primary key of the `promo_codes` table, [without creating a secondary index of the existing primary key](#changing-primary-keys-with-add-constraint-primary-key).

{% include_cached copy-clipboard.html %}
~~~ sql
> SHOW CREATE TABLE users;
SHOW CREATE TABLE promo_codes;
~~~

~~~
table_name | create_statement
-------------+--------------------------------------------------------------
users | CREATE TABLE users (
| id UUID NOT NULL,
| city VARCHAR NOT NULL,
| name VARCHAR NULL,
| address VARCHAR NULL,
| credit_card VARCHAR NULL,
| CONSTRAINT users_pkey PRIMARY KEY (city ASC, id ASC)
| )
table_name | create_statement
--------------+------------------------------------------------------------
promo_codes | CREATE TABLE public.promo_codes (
| code VARCHAR NOT NULL,
| description VARCHAR NULL,
| creation_time TIMESTAMP NULL,
| expiration_time TIMESTAMP NULL,
| rules JSONB NULL,
| CONSTRAINT promo_codes_pkey PRIMARY KEY (code ASC)
| )
(1 row)
~~~

1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `creation_time` column with [`ALTER COLUMN`](#alter-column):

{% include_cached copy-clipboard.html %}
~~~ sql
> ALTER TABLE users ALTER COLUMN name SET NOT NULL;
ALTER TABLE promo_codes ALTER COLUMN creation_time SET NOT NULL;
~~~

1. In the same transaction, `DROP` the old `"primary"` constraint and [`ADD`](#add-constraint) the new one:

{% include_cached copy-clipboard.html %}
~~~ sql
> BEGIN;
> ALTER TABLE users DROP CONSTRAINT "primary";
> ALTER TABLE users ADD CONSTRAINT "primary" PRIMARY KEY (city, name, id);
> COMMIT;
~~~

~~~
NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
BEGIN;
ALTER TABLE promo_codes DROP CONSTRAINT promo_codes_pkey;
ALTER TABLE promo_codes ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
COMMIT;
~~~

1. View the table structure:
1. View the updated table structure:

{% include_cached copy-clipboard.html %}
~~~ sql
> SHOW CREATE TABLE users;
SHOW CREATE TABLE promo_codes;
~~~

~~~
table_name | create_statement
-------------+---------------------------------------------------------------------
users | CREATE TABLE users (
| id UUID NOT NULL,
| city VARCHAR NOT NULL,
| name VARCHAR NOT NULL,
| address VARCHAR NULL,
| credit_card VARCHAR NULL,
| CONSTRAINT "primary" PRIMARY KEY (city ASC, name ASC, id ASC),
| FAMILY "primary" (id, city, name, address, credit_card)
| )
(1 row)
table_name | create_statement
--------------+----------------------------------------------------------------------------
promo_codes | CREATE TABLE public.promo_codes (
| code VARCHAR NOT NULL,
| description VARCHAR NULL,
| creation_time TIMESTAMP NOT NULL,
| expiration_time TIMESTAMP NULL,
| rules JSONB NULL,
| CONSTRAINT promo_codes_pkey PRIMARY KEY (code ASC, creation_time ASC)
| )
(1 row)
~~~

Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %}#alter-primary-key) would have created a `UNIQUE` secondary index called `users_city_id_key`. Instead, there is just one index for the primary key constraint.
Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %}#alter-primary-key) would have created a `UNIQUE` secondary index called `promo_codes_code_key`. Instead, there is just one index for the primary key constraint.

#### Add a unique index to a `REGIONAL BY ROW` table

Expand Down Expand Up @@ -1828,10 +1823,6 @@ To unhide the column, run:

### Alter a primary key

#### Demo

{% include_cached youtube.html video_id="MPx-LXY2D-c" %}
Copy link
Contributor

@rmloveland rmloveland Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh man -1000 points to slytherin for adding YT links and then making private during a "cleanup"


#### Alter a single-column primary key

Suppose that you are storing the data for users of your application in a table called `users`, defined by the following `CREATE TABLE` statement:
Expand Down
80 changes: 39 additions & 41 deletions src/current/v24.1/alter-table.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1142,71 +1142,73 @@ By default, referenced columns must be in the same database as the referencing f

#### Drop and add a primary key constraint

Suppose that you want to add `name` to the composite primary key of the `users` table, [without creating a secondary index of the existing primary key](#changing-primary-keys-with-add-constraint-primary-key).
Suppose that you want to add `creation_time` to the composite primary key of the `promo_codes` table, [without creating a secondary index of the existing primary key](#changing-primary-keys-with-add-constraint-primary-key).

{% include_cached copy-clipboard.html %}
~~~ sql
> SHOW CREATE TABLE users;
SHOW CREATE TABLE promo_codes;
~~~

~~~
table_name | create_statement
-------------+--------------------------------------------------------------
users | CREATE TABLE users (
| id UUID NOT NULL,
| city VARCHAR NOT NULL,
| name VARCHAR NULL,
| address VARCHAR NULL,
| credit_card VARCHAR NULL,
| CONSTRAINT users_pkey PRIMARY KEY (city ASC, id ASC)
| )
table_name | create_statement
--------------+------------------------------------------------------------
promo_codes | CREATE TABLE public.promo_codes (
| code VARCHAR NOT NULL,
| description VARCHAR NULL,
| creation_time TIMESTAMP NULL,
| expiration_time TIMESTAMP NULL,
| rules JSONB NULL,
| CONSTRAINT promo_codes_pkey PRIMARY KEY (code ASC)
| )
(1 row)
~~~

1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `creation_time` column with [`ALTER COLUMN`](#alter-column):

{% include_cached copy-clipboard.html %}
~~~ sql
> ALTER TABLE users ALTER COLUMN name SET NOT NULL;
ALTER TABLE promo_codes ALTER COLUMN creation_time SET NOT NULL;
~~~

1. Turn off autocommit for DDL for the current session, so that multiple DDL statements can execute within one explicit transaction:

{% include_cached copy-clipboard.html %}
~~~ sql
SET autocommit_before_ddl = false;
~~~

1. In the same transaction, `DROP` the old `"primary"` constraint and [`ADD`](#add-constraint) the new one:

{% include_cached copy-clipboard.html %}
~~~ sql
> BEGIN;
> ALTER TABLE users DROP CONSTRAINT "primary";
> ALTER TABLE users ADD CONSTRAINT "primary" PRIMARY KEY (city, name, id);
> COMMIT;
BEGIN;
ALTER TABLE promo_codes DROP CONSTRAINT promo_codes_pkey;
ALTER TABLE promo_codes ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
COMMIT;
~~~

~~~
NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
~~~

1. View the table structure:
1. View the updated table structure:

{% include_cached copy-clipboard.html %}
~~~ sql
> SHOW CREATE TABLE users;
SHOW CREATE TABLE promo_codes;
~~~

~~~
table_name | create_statement
-------------+---------------------------------------------------------------------
users | CREATE TABLE users (
| id UUID NOT NULL,
| city VARCHAR NOT NULL,
| name VARCHAR NOT NULL,
| address VARCHAR NULL,
| credit_card VARCHAR NULL,
| CONSTRAINT "primary" PRIMARY KEY (city ASC, name ASC, id ASC),
| FAMILY "primary" (id, city, name, address, credit_card)
| )
(1 row)
table_name | create_statement
--------------+----------------------------------------------------------------------------
promo_codes | CREATE TABLE public.promo_codes (
| code VARCHAR NOT NULL,
| description VARCHAR NULL,
| creation_time TIMESTAMP NOT NULL,
| expiration_time TIMESTAMP NULL,
| rules JSONB NULL,
| CONSTRAINT promo_codes_pkey PRIMARY KEY (code ASC, creation_time ASC)
| )
(1 row)
~~~

Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %}#alter-primary-key) would have created a `UNIQUE` secondary index called `users_city_id_key`. Instead, there is just one index for the primary key constraint.
Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %}#alter-primary-key) would have created a `UNIQUE` secondary index called `promo_codes_code_key`. Instead, there is just one index for the primary key constraint.

#### Add a unique index to a `REGIONAL BY ROW` table

Expand Down Expand Up @@ -1817,10 +1819,6 @@ To unhide the column, run:

### Alter a primary key

#### Demo

{% include_cached youtube.html video_id="MPx-LXY2D-c" %}

#### Alter a single-column primary key

Suppose that you are storing the data for users of your application in a table called `users`, defined by the following `CREATE TABLE` statement:
Expand Down
80 changes: 39 additions & 41 deletions src/current/v24.2/alter-table.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1115,71 +1115,73 @@ By default, referenced columns must be in the same database as the referencing f

#### Drop and add a primary key constraint

Suppose that you want to add `name` to the composite primary key of the `users` table, [without creating a secondary index of the existing primary key](#changing-primary-keys-with-add-constraint-primary-key).
Suppose that you want to add `creation_time` to the composite primary key of the `promo_codes` table, [without creating a secondary index of the existing primary key](#changing-primary-keys-with-add-constraint-primary-key).
Copy link
Contributor

@rmloveland rmloveland Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not needed due to https://www.cockroachlabs.com/docs/releases/release-support-policy.html#supported-versions but now that it's here 🆗


{% include_cached copy-clipboard.html %}
~~~ sql
> SHOW CREATE TABLE users;
SHOW CREATE TABLE promo_codes;
~~~

~~~
table_name | create_statement
-------------+--------------------------------------------------------------
users | CREATE TABLE users (
| id UUID NOT NULL,
| city VARCHAR NOT NULL,
| name VARCHAR NULL,
| address VARCHAR NULL,
| credit_card VARCHAR NULL,
| CONSTRAINT users_pkey PRIMARY KEY (city ASC, id ASC)
| )
table_name | create_statement
--------------+------------------------------------------------------------
promo_codes | CREATE TABLE public.promo_codes (
| code VARCHAR NOT NULL,
| description VARCHAR NULL,
| creation_time TIMESTAMP NULL,
| expiration_time TIMESTAMP NULL,
| rules JSONB NULL,
| CONSTRAINT promo_codes_pkey PRIMARY KEY (code ASC)
| )
(1 row)
~~~

1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `creation_time` column with [`ALTER COLUMN`](#alter-column):

{% include_cached copy-clipboard.html %}
~~~ sql
> ALTER TABLE users ALTER COLUMN name SET NOT NULL;
ALTER TABLE promo_codes ALTER COLUMN creation_time SET NOT NULL;
~~~

1. Turn off autocommit for DDL for the current session, so that multiple DDL statements can execute within one explicit transaction:

{% include_cached copy-clipboard.html %}
~~~ sql
SET autocommit_before_ddl = false;
~~~

1. In the same transaction, `DROP` the old `"primary"` constraint and [`ADD`](#add-constraint) the new one:

{% include_cached copy-clipboard.html %}
~~~ sql
> BEGIN;
> ALTER TABLE users DROP CONSTRAINT "primary";
> ALTER TABLE users ADD CONSTRAINT "primary" PRIMARY KEY (city, name, id);
> COMMIT;
BEGIN;
ALTER TABLE promo_codes DROP CONSTRAINT promo_codes_pkey;
ALTER TABLE promo_codes ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
COMMIT;
~~~

~~~
NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
~~~

1. View the table structure:
1. View the updated table structure:

{% include_cached copy-clipboard.html %}
~~~ sql
> SHOW CREATE TABLE users;
SHOW CREATE TABLE promo_codes;
~~~

~~~
table_name | create_statement
-------------+---------------------------------------------------------------------
users | CREATE TABLE users (
| id UUID NOT NULL,
| city VARCHAR NOT NULL,
| name VARCHAR NOT NULL,
| address VARCHAR NULL,
| credit_card VARCHAR NULL,
| CONSTRAINT "primary" PRIMARY KEY (city ASC, name ASC, id ASC),
| FAMILY "primary" (id, city, name, address, credit_card)
| )
(1 row)
table_name | create_statement
--------------+----------------------------------------------------------------------------
promo_codes | CREATE TABLE public.promo_codes (
| code VARCHAR NOT NULL,
| description VARCHAR NULL,
| creation_time TIMESTAMP NOT NULL,
| expiration_time TIMESTAMP NULL,
| rules JSONB NULL,
| CONSTRAINT promo_codes_pkey PRIMARY KEY (code ASC, creation_time ASC)
| )
(1 row)
~~~

Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %}#alter-primary-key) would have created a `UNIQUE` secondary index called `users_city_id_key`. Instead, there is just one index for the primary key constraint.
Using [`ALTER PRIMARY KEY`]({% link {{ page.version.version }}/alter-table.md %}#alter-primary-key) would have created a `UNIQUE` secondary index called `promo_codes_code_key`. Instead, there is just one index for the primary key constraint.

#### Add a unique index to a `REGIONAL BY ROW` table

Expand Down Expand Up @@ -1790,10 +1792,6 @@ To unhide the column, run:

### Alter a primary key

#### Demo

{% include_cached youtube.html video_id="MPx-LXY2D-c" %}

#### Alter a single-column primary key

Suppose that you are storing the data for users of your application in a table called `users`, defined by the following `CREATE TABLE` statement:
Expand Down
Loading
Loading