Merge remote-tracking branch 'origin/main' into DOC-12392

Author: florence-crl

CONTRIBUTING.md

@@ -6,11 +6,6 @@ This repository contains the source files for the CockroachDB documentation avai
 
 Want a topic added to the docs? Need additional details or clarification? See an error or other problem? Please [open an issue](https://github.com/cockroachdb/docs/issues).
 
-## Write Docs
-
-Want to contribute to the docs? See [CONTRIBUTING](CONTRIBUTING.md) for details about setting yourself up and getting started.
-
 ## Resources
 
-- [Code of conduct](CODE_OF_CONDUCT.md)
-- [Contributing](CONTRIBUTING.md)
+- [Code of conduct](CODE_OF_CONDUCT.md)

README.md

@@ -213,7 +213,7 @@ CockroachDB docs are mainly comprised of pages (`.md`) and images (`.png` or `.g
 - `this-is-a-doc.md`
 - `name-of-your-image.png`
 
-Each version's pages are found in a directory named for the version. For example, pages for CockroachDB v21.1 are in the `docs > v21.1` directory. For more information about page structure, see the [Pages](https://github.com/cockroachdb/docs/blob/main/CONTRIBUTING.md#pages) section in our [Contributing Guide](https://github.com/cockroachdb/docs/blob/main/CONTRIBUTING.md). For more information about how to style page content, see [Components](#components).
+Each version's pages are found in a directory named for the version. For example, pages for CockroachDB v21.1 are in the `docs > src > current > v21.1` directory. For more information about how to style page content, see [Components](#components).
 
 Each version's images are stored in a versioned directory under the `images` directory. For example, images for CockroachDB v21.1 are in the `docs > images > v21.1` directory. For more information, see [Images](#images).
 

StyleGuide.md

@@ -2,53 +2,55 @@ The following table describes the high level permissions given by each Cockroach
 
 <div class="roles-table" markdown="1">
 
-|  | Org. Member | Org. Admin | Billing Coord. | Cluster Creator | Cluster Operator | Cluster Admin | Cluster Developer | Folder Admin | Folder Mover |
-|---|-------------|-------------|------------------|------------------|-------------------|----------------|--------------------|----------------|----------------|
+|  | [Org. Member]({% link cockroachcloud/authorization.md %}#organization-member) | [Org. Admin]({% link cockroachcloud/authorization.md %}#organization-admin) | [Billing Coord.]({% link cockroachcloud/authorization.md %}#billing-coordinator) | [Cluster Creator]({% link cockroachcloud/authorization.md %}#cluster-creator) | [Cluster Operator]({% link cockroachcloud/authorization.md %}#cluster-operator) | [Cluster Admin]({% link cockroachcloud/authorization.md %}#cluster-admin) | [Cluster Developer]({% link cockroachcloud/authorization.md %}#cluster-developer) | [Cluster Monitor]({% link cockroachcloud/authorization.md %}#cluster-monitor)<sup id="fnref1"><a href="#fn1">1</a></sup> | [Metrics Viewer]({% link cockroachcloud/authorization.md %}#metrics-viewer)<sup id="fnref1"><a href="#fn1">1</a></sup> | [Folder Admin]({% link cockroachcloud/authorization.md %}#folder-admin) | [Folder Mover]({% link cockroachcloud/authorization.md %}#folder-mover) |
+|---|-------------|-------------|------------------|------------------|-------------------|----------------|--------------------|------------------|----------------|----------------|----------------|
 | **User/Access Management** |  |  |  |  |  |  |  |  |  |
-| Assign and revoke roles | — | ✓ | — | — | — | ✓ | — | — | — |
-| Assign {{ site.data.products.cloud }} user and service account roles | — | — | — | — | — | ✓ | — | — | — |
-| Manage SQL users | — | — | — | — | — | ✓ | — | — | — |
-| Manage {{ site.data.products.cloud }} users and service accounts | — | ✓ | — | — | — | ✓ | — | — | — |
-| Apply roles at the [folder]({% link cockroachcloud/folders.md %}) scope | — | — | — | — | — | — | — | ✓ | — |
+| Assign and revoke roles | — | ✓ | — | — | — | ✓ | — | — | — | — | — |
+| Assign {{ site.data.products.cloud }} user and service account roles | — | — | — | — | — | ✓ | — | — | — | — | — |
+| Manage SQL users | — | — | — | — | — | ✓ | — | — | — | — | — |
+| Manage {{ site.data.products.cloud }} users and service accounts | — | ✓ | — | — | — | ✓ | — | — | — | — | — |
+| Apply roles at the [folder]({% link cockroachcloud/folders.md %}) scope | — | — | — | — | — | — | — | — | — | ✓ | — |
 | **Cluster & Infrastructure** |  |  |  |  |  |  |  |  |  |
-| Create cluster or [private cluster]({% link cockroachcloud/private-clusters.md %}) | — | — | — | ✓ | — | — | — | — | — |
-| Create / edit / delete cluster | — | — | — | — | — | ✓ | — | — | — |
-| Edit / delete clusters created by this user | — | — | — | ✓ | — | — | — | — | — |
-| Create / delete / manage [folders]({% link cockroachcloud/folders.md %}) | — | — | — | — | — | — | — | ✓ | — |
-| Move cluster between [folders]({% link cockroachcloud/folders.md %}) | — | — | — | — | — | — | — | — | ✓ |
-| Scale nodes | — | — | — | — | ✓ | ✓ | — | — | — |
-| Upgrade CockroachDB | — | — | — | — | ✓ | ✓ | — | — | — |
-| Configure [maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) | — | — | — | — | ✓ | ✓ | — | — | — |
-| Use the [{{ site.data.products.cloud }} Terraform provider]({% link cockroachcloud/provision-a-cluster-with-terraform.md %}) | — | — | — | ✓ | — | ✓ | — | — | — |
+| Create cluster or [private cluster]({% link cockroachcloud/private-clusters.md %}) | — | — | — | ✓ | — | — | — | — | — | — | — |
+| Create / edit / delete cluster | — | — | — | — | — | ✓ | — | — | — | — | — |
+| Edit / delete clusters created by this user | — | — | — | ✓ | — | — | — | — | — | — | — |
+| Create / delete / manage [folders]({% link cockroachcloud/folders.md %}) | — | — | — | — | — | — | — | — | — | ✓ | — |
+| Move cluster between [folders]({% link cockroachcloud/folders.md %}) | — | — | — | — | — | — | — | — | — | — | ✓ |
+| Scale nodes | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| Upgrade CockroachDB | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| Configure [maintenance windows]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| Use the [{{ site.data.products.cloud }} Terraform provider]({% link cockroachcloud/provision-a-cluster-with-terraform.md %}) | — | — | — | ✓ | — | ✓ | — | — | — | — | — |
 | **Monitoring & Observability** |  |  |  |  |  |  |  |  |  |
-| View cluster details | — | — | — | — | — | — | ✓ | — | — |
-| View [audit logs]({% link cockroachcloud/cloud-org-audit-logs.md %}) | — | — | — | — | ✓ | — | — | — | — |
-| View [insights]({% link cockroachcloud/insights-page.md %}) | — | — | — | — | ✓ | ✓ | — | — | — |
-| View [jobs]({% link cockroachcloud/jobs-page.md %}) | — | — | — | — | ✓ | — | — | — | — |
-| View [metrics]({% link cockroachcloud/metrics.md %}) | — | — | — | — | ✓ | ✓ | — | — | — |
-| Send [test alerts]({% link cockroachcloud/alerts-page.md %}#send-a-test-alert) | — | — | — | — | ✓ | — | — | — | — |
-| Access [DB console]({% link cockroachcloud/network-authorization.md %}#db-console) | — | — | — | — | ✓ | ✓ | ✓ | — | — |
+| View cluster details | — | — | — | — | — | — | ✓ | — | — | — | — |
+| View [audit logs]({% link cockroachcloud/cloud-org-audit-logs.md %}) | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| View [insights]({% link cockroachcloud/insights-page.md %}) | — | — | — | — | ✓ | ✓ | — | ✓ | — | — | — |
+| View [jobs]({% link cockroachcloud/jobs-page.md %}) | — | — | — | — | ✓ | ✓ | — | ✓ | — | — | — |
+| View [sql activity]({% link cockroachcloud/statements-page.md %}) | — | — | — | — | ✓ | ✓ | — | ✓ | — | — | — |
+| View [metrics]({% link cockroachcloud/metrics.md %}) | — | — | — | — | ✓ | ✓ | — | — | ✓ | — | — |
+| Send [test alerts]({% link cockroachcloud/alerts-page.md %}#send-a-test-alert) | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| Access [DB console]({% link cockroachcloud/network-authorization.md %}#db-console) | — | — | — | — | ✓ | ✓ | ✓ | — | — | — | — |
 | **Security** |  |  |  |  |  |  |  |  |  |
-| Configure [cluster SSO]({% link cockroachcloud/cloud-sso-sql.md %}) | — | — | — | — | ✓ | ✓ | — | — | — |
-| Manage [egress perimeter controls]({% link cockroachcloud/egress-perimeter-controls.md %}) | — | — | — | — | — | ✓ | — | — | — |
-| Manage [network authorization]({% link cockroachcloud/network-authorization.md %}) | — | — | — | — | ✓ | ✓ | — | — | — |
-| View PCI status | — | — | — | — | ✓ | ✓ | — | — | — |
+| Configure [cluster SSO]({% link cockroachcloud/cloud-sso-sql.md %}) | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| Manage [egress perimeter controls]({% link cockroachcloud/egress-perimeter-controls.md %}) | — | — | — | — | — | ✓ | — | — | — | — | — |
+| Manage [network authorization]({% link cockroachcloud/network-authorization.md %}) | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| View PCI status | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
 | **Database & Data** |  |  |  |  |  |  |  |  |  |
-| Manage databases | — | — | — | — | ✓ | ✓ | — | — | — |
-| View / restore [backups]({% link cockroachcloud/backup-and-restore-overview.md %}) | — | — | — | — | ✓ | ✓ | — | — | — |
+| Manage databases | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
+| View / restore [backups]({% link cockroachcloud/backup-and-restore-overview.md %}) | — | — | — | — | ✓ | ✓ | — | — | — | — | — |
 | **Billing & Licensing** |  |  |  |  |  |  |  |  |  |
-| Manage [billing]({% link cockroachcloud/billing-management.md %}) | — | — | ✓ | — | — | — | — | — | — |
-| Manage [email alerts]({% link cockroachcloud/alerts-page.md %}#configure-alerts) | — | ✓ | — | — | — | — | — | — | — |
-| Manage CockroachDB [Self-Hosted cluster licenses]({% link {{ site.current_cloud_version }}/licensing-faqs.md %}#obtain-a-license) | — | ✓ | — | — | — | — | — | — | — |
+| Manage [billing]({% link cockroachcloud/billing-management.md %}) | — | — | ✓ | — | — | — | — | — | — | — | — |
+| Manage [email alerts]({% link cockroachcloud/alerts-page.md %}#configure-alerts) | — | ✓ | — | — | — | — | — | — | — | — | — |
+| Manage CockroachDB [Self-Hosted cluster licenses]({% link {{ site.current_cloud_version }}/licensing-faqs.md %}#obtain-a-license) | — | ✓ | — | — | — | — | — | — | — | — | — |
 
 </div>
+<a id="fn1"><sup>1</sup></a>**This feature is in [limited access]({% link {{ site.current_cloud_version }}/cockroachdb-feature-availability.md %})** and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
 
 Some roles can be assigned to users at specific levels of scope to provide more granular permission control:
 
 | **Scope level** | **Description** | **Applicable roles** |
 |---|---|---|
-| `Organization` | Applies to the entire CockroachDB {{ site.data.products.cloud }} organization, including all clusters and folders | `Cluster Operator`, `Cluster Admin`, `Cluster Creator`, `Cluster Developer`, `Billing Coordinator`, `Organization Admin`, `Folder Admin`, `Folder Mover` |
-| `Folder` | Applies to clusters within a specific [folder]({% link cockroachcloud/folders.md %}). Only available as a selectable scope if folders have been created within the organization by a user with the `Folder Admin` role | `Cluster Operator`, `Cluster Admin`, `Cluster Creator`, `Cluster Developer`, `Folder Admin`, `Folder Mover` |
-| `Cluster` | Applies to a specific cluster | `Cluster Operator`, `Cluster Admin`, `Cluster Developer` |
+| `Organization` | Applies to the entire CockroachDB {{ site.data.products.cloud }} organization, including all clusters and folders | `Cluster Operator`, `Cluster Admin`, `Cluster Creator`, `Cluster Developer`, `Cluster Monitor`, `Metrics Viewer`, `Billing Coordinator`, `Organization Admin`, `Folder Admin`, `Folder Mover` |
+| `Folder` | Applies to clusters within a specific [folder]({% link cockroachcloud/folders.md %}). Only available as a selectable scope if folders have been created within the organization by a user with the `Folder Admin` role | `Cluster Operator`, `Cluster Admin`, `Cluster Creator`, `Cluster Developer`, `Cluster Monitor`, `Metrics Viewer`, `Folder Admin`, `Folder Mover` |
+| `Cluster` | Applies to a specific cluster | `Cluster Operator`, `Cluster Admin`, `Cluster Developer`, `Cluster Monitor`, `Metrics Viewer` |
 
-{% if page.name != 'authorization.md' %}For more information on these roles and the specific permissions given, see [Organization user roles]({% link cockroachcloud/authorization.md %}#organization-member).{% endif %}
+{% if page.name != 'authorization.md' %}For more information on these roles and the specific permissions given, see [Organization user roles]({% link cockroachcloud/authorization.md %}#organization-member).{% endif %}

src/current/_includes/cockroachcloud/org-roles/cloud-roles-table.md

@@ -8,7 +8,7 @@ To keep your database credentials out of shell history and logs, follow these be
 
 		{% include_cached copy-clipboard.html %}
 		~~~ shell
-		molt escape-password 'a$52&'
+		molt escape-password --password 'a$52&'
 		~~~
 
 		Use the encoded password in your `--source` connection string. For example:

src/current/_includes/molt/fetch-secure-connection-strings.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.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;
+    ~~~