Document modifying the region column or expression (#20271)

Fixes DOC-14702

Summary of changes:

- Update `CREATE TABLE`, `ALTER TABLE`, and computed columns docs with instructions for modifying the region column or its expression

NB. Changes ported to v25.1, v25.3, v25.4

Author: rmloveland

src/current/_includes/v25.2/sql/modify-region-column-or-its-expression.md

@@ -0,0 +1,29 @@
+The following instructions show how to change the mapping of the [`crdb_internal_region`]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) column that determines row locality for a [regional by row table]({% link {{ page.version.version }}/regional-tables.md %}#regional-by-row-tables) where the [column was already defined with `REGIONAL BY ROW AS {column}`]{% if page.name == "create-table.md" %}(#create-a-table-with-a-regional-by-row-locality-using-a-custom-region-column){% elsif page.name == "alter-table.md" %}(#rename-crdb_region){% else %}({% link {{ page.version.version }}/create-table.md %}#create-a-table-with-a-regional-by-row-locality-using-a-custom-region-column){% endif %}. This method [alters the computed column's expression]({% link {{ page.version.version }}/computed-columns.md %}#alter-the-formula-for-a-computed-column).
+
+1. [Add a new region column]({% link {{ page.version.version }}/alter-table.md %}#add-column) of the same type (`crdb_internal_region`) with the updated scalar expression for the computed column:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users ADD COLUMN region_new crdb_internal_region AS ({new_expression}) STORED;
+    ~~~
+
+1. Atomically [swap the column names]({% link {{ page.version.version }}/alter-table.md %}#rename-column) so the new computed column takes the original name:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users RENAME COLUMN region TO region_prev, RENAME COLUMN region_new TO region;
+    ~~~
+
+1. Point the table locality at the new computed column using [`ALTER TABLE ... SET LOCALITY`]({% link {{ page.version.version }}/alter-table.md %}#set-locality):
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users SET LOCALITY REGIONAL BY ROW AS region;
+    ~~~
+
+1. After verifying the changes have occurred (using a query like `SELECT region, * FROM app.public.users WHERE ...`), [drop the previous computed column]({% link {{ page.version.version }}/alter-table.md %}#drop-column):
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users DROP COLUMN region_prev;
+    ~~~

src/current/_includes/v25.3/sql/modify-region-column-or-its-expression.md

@@ -0,0 +1,29 @@
+The following instructions show how to change the mapping of the [`crdb_internal_region`]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) column that determines row locality for a [regional by row table]({% link {{ page.version.version }}/regional-tables.md %}#regional-by-row-tables) where the [column was already defined with `REGIONAL BY ROW AS {column}`]{% if page.name == "create-table.md" %}(#create-a-table-with-a-regional-by-row-locality-using-a-custom-region-column){% elsif page.name == "alter-table.md" %}(#rename-crdb_region){% else %}({% link {{ page.version.version }}/create-table.md %}#create-a-table-with-a-regional-by-row-locality-using-a-custom-region-column){% endif %}. This method [alters the computed column's expression]({% link {{ page.version.version }}/computed-columns.md %}#alter-the-formula-for-a-computed-column).
+
+1. [Add a new region column]({% link {{ page.version.version }}/alter-table.md %}#add-column) of the same type (`crdb_internal_region`) with the updated scalar expression for the computed column:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users ADD COLUMN region_new crdb_internal_region AS ({new_expression}) STORED;
+    ~~~
+
+1. Atomically [swap the column names]({% link {{ page.version.version }}/alter-table.md %}#rename-column) so the new computed column takes the original name:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users RENAME COLUMN region TO region_prev, RENAME COLUMN region_new TO region;
+    ~~~
+
+1. Point the table locality at the new computed column using [`ALTER TABLE ... SET LOCALITY`]({% link {{ page.version.version }}/alter-table.md %}#set-locality):
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users SET LOCALITY REGIONAL BY ROW AS region;
+    ~~~
+
+1. After verifying the changes have occurred (using a query like `SELECT region, * FROM app.public.users WHERE ...`), [drop the previous computed column]({% link {{ page.version.version }}/alter-table.md %}#drop-column):
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users DROP COLUMN region_prev;
+    ~~~

src/current/_includes/v25.4/sql/modify-region-column-or-its-expression.md

@@ -0,0 +1,29 @@
+The following instructions show how to change the mapping of the [`crdb_internal_region`]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) column that determines row locality for a [regional by row table]({% link {{ page.version.version }}/regional-tables.md %}#regional-by-row-tables) where the [column was already defined with `REGIONAL BY ROW AS {column}`]{% if page.name == "create-table.md" %}(#create-a-table-with-a-regional-by-row-locality-using-a-custom-region-column){% elsif page.name == "alter-table.md" %}(#rename-crdb_region){% else %}({% link {{ page.version.version }}/create-table.md %}#create-a-table-with-a-regional-by-row-locality-using-a-custom-region-column){% endif %}. This method [alters the computed column's expression]({% link {{ page.version.version }}/computed-columns.md %}#alter-the-formula-for-a-computed-column).
+
+1. [Add a new region column]({% link {{ page.version.version }}/alter-table.md %}#add-column) of the same type (`crdb_internal_region`) with the updated scalar expression for the computed column:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users ADD COLUMN region_new crdb_internal_region AS ({new_expression}) STORED;
+    ~~~
+
+1. Atomically [swap the column names]({% link {{ page.version.version }}/alter-table.md %}#rename-column) so the new computed column takes the original name:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users RENAME COLUMN region TO region_prev, RENAME COLUMN region_new TO region;
+    ~~~
+
+1. Point the table locality at the new computed column using [`ALTER TABLE ... SET LOCALITY`]({% link {{ page.version.version }}/alter-table.md %}#set-locality):
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users SET LOCALITY REGIONAL BY ROW AS region;
+    ~~~
+
+1. After verifying the changes have occurred (using a query like `SELECT region, * FROM app.public.users WHERE ...`), [drop the previous computed column]({% link {{ page.version.version }}/alter-table.md %}#drop-column):
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    ALTER TABLE app.public.users DROP COLUMN region_prev;
+    ~~~

src/current/v25.2/alter-table.md

@@ -1314,6 +1314,12 @@ To ensure that the uniqueness constraint is enforced properly across regions whe
 
 {% include {{page.version.version}}/sql/locality-optimized-search.md %}
 
+<a name="modify-rbr-region-column"></a>
+
+#### Modify the region column or its expression
+
+{% include {{ page.version.version }}/sql/modify-region-column-or-its-expression.md %}
+
 #### Using `DEFAULT gen_random_uuid()` in `REGIONAL BY ROW` tables
 
 To auto-generate unique row identifiers in `REGIONAL BY ROW` tables, use the [`UUID`]({% link {{ page.version.version }}/uuid.md %}) column with the `gen_random_uuid()` [function]({% link {{ page.version.version }}/functions-and-operators.md %}#id-generation-functions) as the [default value]({% link {{ page.version.version }}/default-value.md %}):

src/current/v25.2/computed-columns.md

@@ -101,6 +101,10 @@ For more information, see [`ADD COLUMN`]({% link {{ page.version.version }}/alte
 
 {% include {{ page.version.version }}/computed-columns/alter-computed-column.md %}
 
+{{site.data.alerts.callout_info}}
+If the computed column controls row locality in a [`REGIONAL BY ROW`]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) table (for example, using a custom [`crdb_internal_region`]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) column with `REGIONAL BY ROW AS`), you can change its expression by following the steps in [Modify the region column or its expression]({% link {{ page.version.version }}/alter-table.md %}#modify-rbr-region-column).
+{{site.data.alerts.end}}
+
 ## See also
 
 - [Scalar Expressions]({% link {{ page.version.version }}/scalar-expressions.md %})

src/current/v25.2/create-table.md

@@ -863,6 +863,10 @@ For example:
 
 CockroachDB will then assign a region to each row, based on the value of the `region` column. In this example, the `region` column is computed from the value of the `city` column.
 
+#### Modify the region column or its expression
+
+{% include {{ page.version.version }}/sql/modify-region-column-or-its-expression.md %}
+
 ### Create a table with an identity column
 
  [Identity columns](#identity-columns) define a sequence from which to populate a column when a new row is inserted.

src/current/v25.2/table-localities.md

@@ -29,6 +29,8 @@ Table locality settings are used for optimizing latency under different read and
 
 {% include {{page.version.version}}/sql/regional-by-row-table-description.md %}
 
+To change the column or expression used to determine row locality for a regional by row table defined with `REGIONAL BY ROW AS {column}`, refer to [Modify the region column or its expression]({% link {{ page.version.version }}/alter-table.md %}#modify-rbr-region-column).
+
 ### Indexes on `REGIONAL BY ROW` tables
 
 {% include {{page.version.version}}/sql/indexes-regional-by-row.md %}

src/current/v25.3/alter-table.md

@@ -2618,6 +2618,12 @@ ALTER TABLE rides ADD COLUMN region crdb_internal_region AS (
 
 {% include {{page.version.version}}/sql/locality-optimized-search.md %}
 
+<a name="modify-rbr-region-column"></a>
+
+#### Modify the region column or its expression
+
+{% include {{ page.version.version }}/sql/modify-region-column-or-its-expression.md %}
+
 #### Infer a row's home region from a foreign key
 
 {{site.data.alerts.callout_info}}

src/current/v25.3/computed-columns.md

@@ -101,6 +101,10 @@ For more information, see [`ADD COLUMN`]({% link {{ page.version.version }}/alte
 
 {% include {{ page.version.version }}/computed-columns/alter-computed-column.md %}
 
+{{site.data.alerts.callout_info}}
+If the computed column controls row locality in a [`REGIONAL BY ROW`]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) table (for example, using a custom [`crdb_internal_region`]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) column with `REGIONAL BY ROW AS`), you can change its expression by following the steps in [Modify the region column or its expression]({% link {{ page.version.version }}/alter-table.md %}#modify-rbr-region-column).
+{{site.data.alerts.end}}
+
 ## See also
 
 - [Scalar Expressions]({% link {{ page.version.version }}/scalar-expressions.md %})

src/current/v25.3/create-table.md

@@ -863,6 +863,10 @@ For example:
 
 CockroachDB will then assign a region to each row, based on the value of the `region` column. In this example, the `region` column is computed from the value of the `city` column.
 
+#### Modify the region column or its expression
+
+{% include {{ page.version.version }}/sql/modify-region-column-or-its-expression.md %}
+
 ### Create a table with an identity column
 
  [Identity columns](#identity-columns) define a sequence from which to populate a column when a new row is inserted.