diff --git a/src/current/v23.2/alter-table.md b/src/current/v23.2/alter-table.md
index d374d303954..f7b7deb5e1c 100644
--- a/src/current/v23.2/alter-table.md
+++ b/src/current/v23.2/alter-table.md
@@ -1153,71 +1153,71 @@ 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).
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
-
-~~~
- 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)
- | )
-(1 row)
-~~~
-
-1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
+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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
+
+1. View the details of the `promo_codes` table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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 `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:
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
- {% 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;
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-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
@@ -1828,10 +1828,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:
diff --git a/src/current/v23.2/online-schema-changes.md b/src/current/v23.2/online-schema-changes.md
index 85840ac932f..81e5ae9aa14 100644
--- a/src/current/v23.2/online-schema-changes.md
+++ b/src/current/v23.2/online-schema-changes.md
@@ -181,7 +181,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs
diff --git a/src/current/v24.1/alter-table.md b/src/current/v24.1/alter-table.md
index 30192484011..31dc7775054 100644
--- a/src/current/v24.1/alter-table.md
+++ b/src/current/v24.1/alter-table.md
@@ -1142,71 +1142,71 @@ 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).
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
-
-~~~
- 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)
- | )
-(1 row)
-~~~
-
-1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
+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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
+
+1. View the details of the `promo_codes` table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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 `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:
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
- {% 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;
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-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
@@ -1817,10 +1817,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:
diff --git a/src/current/v24.1/online-schema-changes.md b/src/current/v24.1/online-schema-changes.md
index 7c8ec88ba25..e021c0a2835 100644
--- a/src/current/v24.1/online-schema-changes.md
+++ b/src/current/v24.1/online-schema-changes.md
@@ -181,7 +181,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs
diff --git a/src/current/v24.2/alter-table.md b/src/current/v24.2/alter-table.md
index 3595a373921..2a2bb72cab2 100644
--- a/src/current/v24.2/alter-table.md
+++ b/src/current/v24.2/alter-table.md
@@ -1115,71 +1115,71 @@ 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).
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
-
-~~~
- 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)
- | )
-(1 row)
-~~~
-
-1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
+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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
+
+1. View the details of the `promo_codes` table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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 `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:
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
- {% 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;
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-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
@@ -1790,10 +1790,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:
diff --git a/src/current/v24.2/online-schema-changes.md b/src/current/v24.2/online-schema-changes.md
index 9624b8c3119..b566a71ece2 100644
--- a/src/current/v24.2/online-schema-changes.md
+++ b/src/current/v24.2/online-schema-changes.md
@@ -19,7 +19,9 @@ Schema changes consume additional resources, and if they are run when the cluste
{{site.data.alerts.end}}
{{site.data.alerts.callout_info}}
-CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
+CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
+
+Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
{{site.data.alerts.end}}
## How online schema changes work
@@ -181,7 +183,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs
diff --git a/src/current/v24.3/alter-table.md b/src/current/v24.3/alter-table.md
index 30192484011..31dc7775054 100644
--- a/src/current/v24.3/alter-table.md
+++ b/src/current/v24.3/alter-table.md
@@ -1142,71 +1142,71 @@ 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).
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
-
-~~~
- 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)
- | )
-(1 row)
-~~~
-
-1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
+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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
+
+1. View the details of the `promo_codes` table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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 `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:
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
- {% 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;
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-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
@@ -1817,10 +1817,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:
diff --git a/src/current/v25.1/alter-table.md b/src/current/v25.1/alter-table.md
index 7d4cd6ba99f..34d8d457995 100644
--- a/src/current/v25.1/alter-table.md
+++ b/src/current/v25.1/alter-table.md
@@ -1113,71 +1113,71 @@ 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).
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
-
-~~~
- 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)
- | )
-(1 row)
-~~~
-
-1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
+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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
+
+1. View the details of the `promo_codes` table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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 `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:
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
- {% 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;
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-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
@@ -1773,10 +1773,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:
diff --git a/src/current/v25.1/online-schema-changes.md b/src/current/v25.1/online-schema-changes.md
index 395d6c3b920..e2b5d79529a 100644
--- a/src/current/v25.1/online-schema-changes.md
+++ b/src/current/v25.1/online-schema-changes.md
@@ -19,7 +19,9 @@ Schema changes consume additional resources, and if they are run when the cluste
{{site.data.alerts.end}}
{{site.data.alerts.callout_info}}
-CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
+CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
+
+Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
{{site.data.alerts.end}}
## How online schema changes work
@@ -181,7 +183,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs
diff --git a/src/current/v25.2/alter-table.md b/src/current/v25.2/alter-table.md
index a952ea00636..8bb08b8c17e 100644
--- a/src/current/v25.2/alter-table.md
+++ b/src/current/v25.2/alter-table.md
@@ -1203,71 +1203,71 @@ 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).
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
-
-~~~
- 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)
- | )
-(1 row)
-~~~
-
-1. Add a [`NOT NULL`]({% link {{ page.version.version }}/not-null.md %}) constraint to the `name` column with [`ALTER COLUMN`](#alter-column).
+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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
+
+1. View the details of the `promo_codes` table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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 `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:
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
- {% 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;
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-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
@@ -1869,10 +1869,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:
diff --git a/src/current/v25.2/online-schema-changes.md b/src/current/v25.2/online-schema-changes.md
index 395d6c3b920..e2b5d79529a 100644
--- a/src/current/v25.2/online-schema-changes.md
+++ b/src/current/v25.2/online-schema-changes.md
@@ -19,7 +19,9 @@ Schema changes consume additional resources, and if they are run when the cluste
{{site.data.alerts.end}}
{{site.data.alerts.callout_info}}
-CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
+CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
+
+Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
{{site.data.alerts.end}}
## How online schema changes work
@@ -181,7 +183,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs
diff --git a/src/current/v25.3/alter-table.md b/src/current/v25.3/alter-table.md
index 9f0679c48c0..b2ab953e84f 100644
--- a/src/current/v25.3/alter-table.md
+++ b/src/current/v25.3/alter-table.md
@@ -1203,71 +1203,87 @@ 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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
+1. View the details of the `promo_codes` table:
-~~~
- 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)
- | )
-(1 row)
-~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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)
+ | ) WITH (schema_locked = true);
+ (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:
+1. The `promo_codes` table is schema-locked with the [`schema_locked` table parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#table-parameters), and the `DROP CONSTRAINT` and `ADD CONSTRAINT` schema changes cannot automatically unset `schema_locked`. In this case, you must manually unlock the table with `schema_locked = false`, complete the schema change, and then lock the table again with `schema_locked = true`.
- {% 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;
- ~~~
+ Unlock the table:
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes SET (schema_locked = false);
+ ~~~
+
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
+
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-1. View the table structure:
+1. Re-enable `schema_locked` on the table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes SET (schema_locked = true);
+ ~~~
+
+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)
+ | ) WITH (schema_locked = true);
+ (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
@@ -1863,10 +1879,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:
diff --git a/src/current/v25.3/online-schema-changes.md b/src/current/v25.3/online-schema-changes.md
index 395d6c3b920..e2b5d79529a 100644
--- a/src/current/v25.3/online-schema-changes.md
+++ b/src/current/v25.3/online-schema-changes.md
@@ -19,7 +19,9 @@ Schema changes consume additional resources, and if they are run when the cluste
{{site.data.alerts.end}}
{{site.data.alerts.callout_info}}
-CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
+CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
+
+Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
{{site.data.alerts.end}}
## How online schema changes work
@@ -181,7 +183,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs
diff --git a/src/current/v25.4/alter-table.md b/src/current/v25.4/alter-table.md
index d87e7812434..aa3e4fe6484 100644
--- a/src/current/v25.4/alter-table.md
+++ b/src/current/v25.4/alter-table.md
@@ -1203,71 +1203,87 @@ 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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
+1. View the details of the `promo_codes` table:
-~~~
- 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)
- | )
-(1 row)
-~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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)
+ | ) WITH (schema_locked = true);
+ (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:
+1. The `promo_codes` table is schema-locked with the [`schema_locked` table parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#table-parameters), and the `DROP CONSTRAINT` and `ADD CONSTRAINT` schema changes cannot automatically unset `schema_locked`. In this case, you must manually unlock the table with `schema_locked = false`, complete the schema change, and then lock the table again with `schema_locked = true`.
- {% 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;
- ~~~
+ Unlock the table:
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes SET (schema_locked = false);
+ ~~~
+
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
+
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-1. View the table structure:
+1. Re-enable `schema_locked` on the table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes SET (schema_locked = true);
+ ~~~
+
+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)
+ | ) WITH (schema_locked = true);
+ (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
@@ -1863,10 +1879,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:
diff --git a/src/current/v25.4/online-schema-changes.md b/src/current/v25.4/online-schema-changes.md
index 395d6c3b920..e2b5d79529a 100644
--- a/src/current/v25.4/online-schema-changes.md
+++ b/src/current/v25.4/online-schema-changes.md
@@ -19,7 +19,9 @@ Schema changes consume additional resources, and if they are run when the cluste
{{site.data.alerts.end}}
{{site.data.alerts.callout_info}}
-CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
+CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
+
+Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
{{site.data.alerts.end}}
## How online schema changes work
@@ -181,7 +183,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs
diff --git a/src/current/v26.1/alter-table.md b/src/current/v26.1/alter-table.md
index d87e7812434..b4e6e7121bb 100644
--- a/src/current/v26.1/alter-table.md
+++ b/src/current/v26.1/alter-table.md
@@ -1203,71 +1203,87 @@ 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). To do so, use [`DROP CONSTRAINT`](#drop-constraint) and [`ADD CONSTRAINT`](#add-constraint) in a single `ALTER TABLE` statement.
-{% include_cached copy-clipboard.html %}
-~~~ sql
-> SHOW CREATE TABLE users;
-~~~
+1. View the details of the `promo_codes` table:
-~~~
- 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)
- | )
-(1 row)
-~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ SHOW CREATE TABLE promo_codes;
+ ~~~
+
+ ~~~
+ 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)
+ | ) WITH (schema_locked = true);
+ (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:
+1. The `promo_codes` table is schema-locked with the [`schema_locked` table parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#table-parameters), and the `DROP CONSTRAINT` and `ADD CONSTRAINT` schema changes cannot automatically unset `schema_locked`. In this case, you must manually unlock the table with `schema_locked = false`, complete the schema change, and then lock the table again with `schema_locked = true`.
- {% 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;
- ~~~
+ Unlock the table:
- ~~~
- NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
- ~~~
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes SET (schema_locked = false);
+ ~~~
+
+1. To issue the schema change atomically, use single statements as an implicit transaction. `DROP CONSTRAINT` and `ADD CONSTRAINT` can be combined in a single `ALTER TABLE` statement:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes
+ DROP CONSTRAINT promo_codes_pkey,
+ ADD CONSTRAINT promo_codes_pkey PRIMARY KEY (code, creation_time);
+ ~~~
+
+ {{site.data.alerts.callout_info}}
+ You should **not** execute the schema change with multiple statements within an explicit transaction. Refer to [Schema changes within transactions]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions).
+ {{site.data.alerts.end}}
-1. View the table structure:
+1. Re-enable `schema_locked` on the table:
+
+ {% include_cached copy-clipboard.html %}
+ ~~~ sql
+ ALTER TABLE promo_codes SET (schema_locked = true);
+ ~~~
+
+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)
+ | ) WITH (schema_locked = true);
+ (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
@@ -1863,10 +1879,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:
diff --git a/src/current/v26.1/online-schema-changes.md b/src/current/v26.1/online-schema-changes.md
index 395d6c3b920..e2b5d79529a 100644
--- a/src/current/v26.1/online-schema-changes.md
+++ b/src/current/v26.1/online-schema-changes.md
@@ -19,7 +19,9 @@ Schema changes consume additional resources, and if they are run when the cluste
{{site.data.alerts.end}}
{{site.data.alerts.callout_info}}
-CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
+CockroachDB [does not support schema changes within explicit transactions](#schema-changes-within-transactions) with full atomicity guarantees. CockroachDB only supports DDL changes within implicit transactions (individual statements). If a schema management tool uses transactions on your behalf, it should only execute one schema change operation per transaction.
+
+Some tools and applications may be able to workaround CockroachDB's lack of transactional schema changes by [enabling a setting that automatically commits before running schema changes inside transactions](#enable-automatic-commit-before-running-schema-changes-inside-transactions).
{{site.data.alerts.end}}
## How online schema changes work
@@ -181,7 +183,7 @@ COMMIT
### Run multiple schema changes in a single `ALTER TABLE` statement
-Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, see [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}). For a demonstration, see [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically).
+Some schema changes can be used in combination in a single `ALTER TABLE` statement. For a list of commands that can be combined, refer to [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}#subcommands). For examples, refer to [Add and rename columns atomically]({% link {{ page.version.version }}/alter-table.md %}#add-and-rename-columns-atomically) and [Drop and add a primary key constraint]({% link {{ page.version.version }}/alter-table.md %}#drop-and-add-a-primary-key-constraint).
### Show all schema change jobs