cockroachdb · rmloveland · Mar 19, 2025 · Dec 9, 2024 · Mar 19, 2025
diff --git a/src/current/_includes/v23.1/backups/zone-configs-overwritten-during-restore.md b/src/current/_includes/v23.1/backups/zone-configs-overwritten-during-restore.md
@@ -0,0 +1 @@
+During a [cluster restore]({% link {{ page.version.version }}/restore.md %}#full-cluster), any [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) present on the destination cluster are **overwritten** with the zone configurations from the [backed-up cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster). If no customized zone configurations were on the cluster when the backup was taken, then after the restore the destination cluster will use the zone configuration from the [`RANGE DEFAULT` configuration]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone).
diff --git a/src/current/_includes/v23.1/see-zone-config-troubleshooting-guide.md b/src/current/_includes/v23.1/see-zone-config-troubleshooting-guide.md
@@ -0,0 +1 @@
+For instructions showing how to troubleshoot replication zones that may be misconfigured, see [Troubleshoot Replication Zone Configurations]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}).
diff --git a/src/current/_includes/v23.1/sidebar-data/troubleshooting.json b/src/current/_includes/v23.1/sidebar-data/troubleshooting.json
@@ -56,6 +56,12 @@
           "/${VERSION}/query-replication-reports.html"
         ]
       },
+      {
+        "title": "Troubleshoot Replication Zones",
+        "urls": [
+          "/${VERSION}/troubleshoot-replication-zones.html"
+        ]
+      },
       {
         "title": "Benchmarking",
         "items": [

diff --git a/src/current/_includes/v23.1/zone-configs/avoid-manual-zone-configs.md b/src/current/_includes/v23.1/zone-configs/avoid-manual-zone-configs.md
@@ -0,0 +1,3 @@
+Cockroach Labs {% if page.name != "configure-replication-zones.md" %} [does not recommend modifying zone configurations manually]({% link {{ page.version.version }}/configure-replication-zones.md %}#why-manual-zone-config-management-is-not-recommended). {% else %} [does not recommend modifying zone configurations manually](#why-manual-zone-config-management-is-not-recommended). {% endif %}
+
+Most users should use [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) instead. If additional control is needed, use [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) to augment the multi-region SQL statements.
diff --git a/src/current/_includes/v23.2/backups/zone-configs-overwritten-during-restore.md b/src/current/_includes/v23.2/backups/zone-configs-overwritten-during-restore.md
@@ -0,0 +1 @@
+During a [cluster restore]({% link {{ page.version.version }}/restore.md %}#full-cluster), any [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) present on the destination cluster are **overwritten** with the zone configurations from the [backed-up cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster). If no customized zone configurations were on the cluster when the backup was taken, then after the restore the destination cluster will use the zone configuration from the [`RANGE DEFAULT` configuration]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone).
diff --git a/src/current/_includes/v23.2/see-zone-config-troubleshooting-guide.md b/src/current/_includes/v23.2/see-zone-config-troubleshooting-guide.md
@@ -0,0 +1 @@
+For instructions showing how to troubleshoot replication zones that may be misconfigured, see [Troubleshoot Replication Zone Configurations]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}).
diff --git a/src/current/_includes/v23.2/sidebar-data/troubleshooting.json b/src/current/_includes/v23.2/sidebar-data/troubleshooting.json
@@ -56,6 +56,12 @@
           "/${VERSION}/query-replication-reports.html"
         ]
       },
+      {
+        "title": "Troubleshoot Replication Zones",
+        "urls": [
+          "/${VERSION}/troubleshoot-replication-zones.html"
+        ]
+      },
       {
         "title": "Benchmarking",
         "items": [

diff --git a/src/current/_includes/v23.2/zone-configs/avoid-manual-zone-configs.md b/src/current/_includes/v23.2/zone-configs/avoid-manual-zone-configs.md
@@ -0,0 +1,3 @@
+Cockroach Labs {% if page.name != "configure-replication-zones.md" %} [does not recommend modifying zone configurations manually]({% link {{ page.version.version }}/configure-replication-zones.md %}#why-manual-zone-config-management-is-not-recommended). {% else %} [does not recommend modifying zone configurations manually](#why-manual-zone-config-management-is-not-recommended). {% endif %}
+
+Most users should use [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) instead. If additional control is needed, use [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) to augment the multi-region SQL statements.
diff --git a/src/current/_includes/v24.1/backups/zone-configs-overwritten-during-restore.md b/src/current/_includes/v24.1/backups/zone-configs-overwritten-during-restore.md
@@ -0,0 +1 @@
+During a [cluster restore]({% link {{ page.version.version }}/restore.md %}#full-cluster), any [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) present on the destination cluster are **overwritten** with the zone configurations from the [backed-up cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster). If no customized zone configurations were on the cluster when the backup was taken, then after the restore the destination cluster will use the zone configuration from the [`RANGE DEFAULT` configuration]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone).
diff --git a/src/current/_includes/v24.1/see-zone-config-troubleshooting-guide.md b/src/current/_includes/v24.1/see-zone-config-troubleshooting-guide.md
@@ -0,0 +1 @@
+For instructions showing how to troubleshoot replication zones that may be misconfigured, see [Troubleshoot Replication Zone Configurations]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}).
diff --git a/src/current/_includes/v24.1/sidebar-data/troubleshooting.json b/src/current/_includes/v24.1/sidebar-data/troubleshooting.json
@@ -56,6 +56,12 @@
           "/${VERSION}/query-replication-reports.html"
         ]
       },
+      {
+        "title": "Troubleshoot Replication Zones",
+        "urls": [
+          "/${VERSION}/troubleshoot-replication-zones.html"
+        ]
+      },
       {
         "title": "Benchmarking",
         "items": [

diff --git a/src/current/_includes/v24.1/zone-configs/avoid-manual-zone-configs.md b/src/current/_includes/v24.1/zone-configs/avoid-manual-zone-configs.md
@@ -0,0 +1,3 @@
+Cockroach Labs {% if page.name != "configure-replication-zones.md" %} [does not recommend modifying zone configurations manually]({% link {{ page.version.version }}/configure-replication-zones.md %}#why-manual-zone-config-management-is-not-recommended). {% else %} [does not recommend modifying zone configurations manually](#why-manual-zone-config-management-is-not-recommended). {% endif %}
+
+Most users should use [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) instead. If additional control is needed, use [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) to augment the multi-region SQL statements.
diff --git a/src/current/_includes/v24.2/backups/zone-configs-overwritten-during-restore.md b/src/current/_includes/v24.2/backups/zone-configs-overwritten-during-restore.md
@@ -0,0 +1 @@
+During a [cluster restore]({% link {{ page.version.version }}/restore.md %}#full-cluster), any [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) present on the destination cluster are **overwritten** with the zone configurations from the [backed-up cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster). If no customized zone configurations were on the cluster when the backup was taken, then after the restore the destination cluster will use the zone configuration from the [`RANGE DEFAULT` configuration]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone).
diff --git a/src/current/_includes/v24.2/see-zone-config-troubleshooting-guide.md b/src/current/_includes/v24.2/see-zone-config-troubleshooting-guide.md
@@ -0,0 +1 @@
+For instructions showing how to troubleshoot replication zones that may be misconfigured, see [Troubleshoot Replication Zone Configurations]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}).
diff --git a/src/current/_includes/v24.2/sidebar-data/troubleshooting.json b/src/current/_includes/v24.2/sidebar-data/troubleshooting.json
@@ -56,6 +56,12 @@
           "/${VERSION}/query-replication-reports.html"
         ]
       },
+      {
+        "title": "Troubleshoot Replication Zones",
+        "urls": [
+          "/${VERSION}/troubleshoot-replication-zones.html"
+        ]
+      },
       {
         "title": "Benchmarking",
         "items": [

diff --git a/src/current/_includes/v24.2/zone-configs/avoid-manual-zone-configs.md b/src/current/_includes/v24.2/zone-configs/avoid-manual-zone-configs.md
@@ -0,0 +1,3 @@
+Cockroach Labs {% if page.name != "configure-replication-zones.md" %} [does not recommend modifying zone configurations manually]({% link {{ page.version.version }}/configure-replication-zones.md %}#why-manual-zone-config-management-is-not-recommended). {% else %} [does not recommend modifying zone configurations manually](#why-manual-zone-config-management-is-not-recommended). {% endif %}
+
+Most users should use [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) instead. If additional control is needed, use [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) to augment the multi-region SQL statements.
diff --git a/src/current/_includes/v24.3/backups/zone-configs-overwritten-during-restore.md b/src/current/_includes/v24.3/backups/zone-configs-overwritten-during-restore.md
@@ -0,0 +1 @@
+During a [cluster restore]({% link {{ page.version.version }}/restore.md %}#full-cluster), any [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) present on the destination cluster are **overwritten** with the zone configurations from the [backed-up cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster). If no customized zone configurations were on the cluster when the backup was taken, then after the restore the destination cluster will use the zone configuration from the [`RANGE DEFAULT` configuration]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone).
diff --git a/src/current/_includes/v24.3/see-zone-config-troubleshooting-guide.md b/src/current/_includes/v24.3/see-zone-config-troubleshooting-guide.md
@@ -0,0 +1 @@
+For instructions showing how to troubleshoot replication zones that may be misconfigured, see [Troubleshoot Replication Zone Configurations]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}).
diff --git a/src/current/_includes/v24.3/sidebar-data/troubleshooting.json b/src/current/_includes/v24.3/sidebar-data/troubleshooting.json
@@ -56,6 +56,12 @@
           "/${VERSION}/query-replication-reports.html"
         ]
       },
+      {
+        "title": "Troubleshoot Replication Zones",
+        "urls": [
+          "/${VERSION}/troubleshoot-replication-zones.html"
+        ]
+      },
       {
         "title": "Benchmarking",
         "items": [

diff --git a/src/current/_includes/v24.3/zone-configs/avoid-manual-zone-configs.md b/src/current/_includes/v24.3/zone-configs/avoid-manual-zone-configs.md
@@ -0,0 +1,3 @@
+Cockroach Labs {% if page.name != "configure-replication-zones.md" %} [does not recommend modifying zone configurations manually]({% link {{ page.version.version }}/configure-replication-zones.md %}#why-manual-zone-config-management-is-not-recommended). {% else %} [does not recommend modifying zone configurations manually](#why-manual-zone-config-management-is-not-recommended). {% endif %}
+
+Most users should use [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) instead. If additional control is needed, use [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) to augment the multi-region SQL statements.
diff --git a/src/current/_includes/v25.1/backups/zone-configs-overwritten-during-restore.md b/src/current/_includes/v25.1/backups/zone-configs-overwritten-during-restore.md
@@ -0,0 +1 @@
+During a [cluster restore]({% link {{ page.version.version }}/restore.md %}#full-cluster), any [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) present on the destination cluster are **overwritten** with the zone configurations from the [backed-up cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster). If no customized zone configurations were on the cluster when the backup was taken, then after the restore the destination cluster will use the zone configuration from the [`RANGE DEFAULT` configuration]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone).
diff --git a/src/current/_includes/v25.1/see-zone-config-troubleshooting-guide.md b/src/current/_includes/v25.1/see-zone-config-troubleshooting-guide.md
@@ -0,0 +1 @@
+For instructions showing how to troubleshoot replication zones that may be misconfigured, see [Troubleshoot Replication Zone Configurations]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}).
diff --git a/src/current/_includes/v25.1/sidebar-data/troubleshooting.json b/src/current/_includes/v25.1/sidebar-data/troubleshooting.json
@@ -62,6 +62,12 @@
           "/${VERSION}/query-replication-reports.html"
         ]
       },
+      {
+        "title": "Troubleshoot Replication Zones",
+        "urls": [
+          "/${VERSION}/troubleshoot-replication-zones.html"
+        ]
+      },
       {
         "title": "Benchmarking",
         "items": [

diff --git a/src/current/_includes/v25.1/zone-configs/avoid-manual-zone-configs.md b/src/current/_includes/v25.1/zone-configs/avoid-manual-zone-configs.md
@@ -0,0 +1,3 @@
+Cockroach Labs {% if page.name != "configure-replication-zones.md" %} [does not recommend modifying zone configurations manually]({% link {{ page.version.version }}/configure-replication-zones.md %}#why-manual-zone-config-management-is-not-recommended). {% else %} [does not recommend modifying zone configurations manually](#why-manual-zone-config-management-is-not-recommended). {% endif %}
+
+Most users should use [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) instead. If additional control is needed, use [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) to augment the multi-region SQL statements.
diff --git a/src/current/images/v23.1/zone-config-inheritance-diagram.png b/src/current/images/v23.1/zone-config-inheritance-diagram.png
diff --git a/src/current/images/v23.2/zone-config-inheritance-diagram.png b/src/current/images/v23.2/zone-config-inheritance-diagram.png
diff --git a/src/current/images/v24.1/zone-config-inheritance-diagram.png b/src/current/images/v24.1/zone-config-inheritance-diagram.png
diff --git a/src/current/images/v24.2/zone-config-inheritance-diagram.png b/src/current/images/v24.2/zone-config-inheritance-diagram.png
diff --git a/src/current/images/v24.3/zone-config-inheritance-diagram.png b/src/current/images/v24.3/zone-config-inheritance-diagram.png
diff --git a/src/current/images/v25.1/zone-config-inheritance-diagram.png b/src/current/images/v25.1/zone-config-inheritance-diagram.png
diff --git a/src/current/v23.1/alter-database.md b/src/current/v23.1/alter-database.md
@@ -169,6 +169,10 @@ For usage, see [Synopsis](#synopsis).
 If you directly change a database's zone configuration with `ALTER DATABASE ... CONFIGURE ZONE`, CockroachDB will block all [`ALTER DATABASE ... SET PRIMARY REGION`](#set-primary-region) statements on the database.
 {{site.data.alerts.end}}
 
+{{site.data.alerts.callout_danger}}
+{% include {{ page.version.version }}/zone-configs/avoid-manual-zone-configs.md %}
+{{site.data.alerts.end}}
+
 You can use *replication zones* to control the number and location of replicas for specific sets of data, both when replicas are first added and when they are rebalanced to maintain cluster equilibrium.
 
 For examples, see [Replication Controls](#configure-replication-zones).
@@ -691,6 +695,10 @@ HINT: you must first drop super region usa before you can drop the region us-wes
 
 ### Configure replication zones
 
+{{site.data.alerts.callout_danger}}
+{% include {{ page.version.version }}/zone-configs/avoid-manual-zone-configs.md %}
+{{site.data.alerts.end}}
+
 {% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %}
 
 #### Create a replication zone for a database
@@ -717,6 +725,10 @@ You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or
 ALTER DATABASE movr CONFIGURE ZONE DISCARD;
 ~~~
 
+### Troubleshoot replication zones
+
+{% include {{ page.version.version }}/see-zone-config-troubleshooting-guide.md %}
+
 ### Use Zone Config Extensions
 
 The following examples show:
@@ -1080,6 +1092,12 @@ When you discard a zone configuration, the objects it was applied to will then i
 However, this statement will not remove any configuration created by the [multi-region abstractions]({% link {{ page.version.version }}/multiregion-overview.md %}).
 {{site.data.alerts.end}}
 
+#### Troubleshoot Zone Config Extensions
+
+The process for troubleshooting Zone Config Extensions is the same as troubleshooting any other changes to zone configs.
+
+{% include {{ page.version.version }}/see-zone-config-troubleshooting-guide.md %}
+
 ### Change database owner
 
 {% include {{page.version.version}}/sql/movr-statements.md %}
@@ -1285,3 +1303,4 @@ For more information about the region survival goal, see [Surviving region failu
 - [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %})
 - [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %})
 - [SQL Statements]({% link {{ page.version.version }}/sql-statements.md %})
+- [Troubleshoot Replication Zones]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %})
diff --git a/src/current/v23.1/alter-index.md b/src/current/v23.1/alter-index.md
@@ -46,12 +46,12 @@ Subcommand | Description |
 
 `ALTER INDEX ... CONFIGURE ZONE` is used to add, modify, reset, or remove replication zones for an index. To view details about existing replication zones, use [`SHOW ZONE CONFIGURATIONS`]({% link {{ page.version.version }}/show-zone-configurations.md %}). For more information about replication zones, see [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %}).
 
-
-
 You can use *replication zones* to control the number and location of replicas for specific sets of data, both when replicas are first added and when they are rebalanced to maintain cluster equilibrium.
 
 For examples, see [Replication Controls](#configure-replication-zones).
 
+{% include {{ page.version.version }}/see-zone-config-troubleshooting-guide.md %}
+
 #### Required privileges
 
 The user must be a member of the [`admin` role]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role) or have been granted [`CREATE`]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) or [`ZONECONFIG`]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) privileges. To configure [`system` objects]({% link {{ page.version.version }}/configure-replication-zones.md %}#for-system-data), the user must be a member of the `admin` role.
@@ -213,6 +213,10 @@ You cannot `DISCARD` any zone configurations on multi-region tables, indexes, or
 ALTER INDEX vehicles@vehicles_auto_index_fk_city_ref_users CONFIGURE ZONE DISCARD;
 ~~~
 
+#### Troubleshoot replication zones
+
+{% include {{ page.version.version }}/see-zone-config-troubleshooting-guide.md %}
+
 ### Define partitions
 
 #### Define a list partition on an index

diff --git a/src/current/v23.1/alter-partition.md b/src/current/v23.1/alter-partition.md
@@ -9,6 +9,8 @@ docs_area: reference.sql
 
 To view details about existing replication zones, use [`SHOW ZONE CONFIGURATIONS`]({% link {{ page.version.version }}/show-zone-configurations.md %}). For more information about replication zones, see [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %}).
 
+{% include {{ page.version.version }}/see-zone-config-troubleshooting-guide.md %}
+
 You can use *replication zones* to control the number and location of replicas for specific sets of data, both when replicas are first added and when they are rebalanced to maintain cluster equilibrium.
 
 
@@ -44,3 +46,11 @@ The user must have the [`CREATE`]({% link {{ page.version.version }}/grant.md %}
 ### Create a replication zone for a partition
 
 {% include {{ page.version.version }}/zone-configs/create-a-replication-zone-for-a-table-partition.md hide-enterprise-warning="true" %}
+
+{% include {{ page.version.version }}/see-zone-config-troubleshooting-guide.md %}
+
+## See also
+
+- [Table partitioning]({% link {{page.version.version}}/partitioning.md %})
+- [`SHOW PARTITIONS`]({% link {{page.version.version}}/show-partitions.md %})
+- [Troubleshoot Replication Zones]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %})
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		During a [cluster restore]({% link {{ page.version.version }}/restore.md %}#full-cluster), any [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) present on the destination cluster are overwritten with the zone configurations from the [backed-up cluster]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster). If no customized zone configurations were on the cluster when the backup was taken, then after the restore the destination cluster will use the zone configuration from the [`RANGE DEFAULT` configuration]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		For instructions showing how to troubleshoot replication zones that may be misconfigured, see [Troubleshoot Replication Zone Configurations]({% link {{ page.version.version}}/troubleshoot-replication-zones.md %}).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		Cockroach Labs {% if page.name != "configure-replication-zones.md" %} [does not recommend modifying zone configurations manually]({% link {{ page.version.version }}/configure-replication-zones.md %}#why-manual-zone-config-management-is-not-recommended). {% else %} [does not recommend modifying zone configurations manually](#why-manual-zone-config-management-is-not-recommended). {% endif %}

		Most users should use [multi-region SQL statements]({% link {{ page.version.version }}/multiregion-overview.md %}) instead. If additional control is needed, use [Zone Config Extensions]({% link {{ page.version.version }}/zone-config-extensions.md %}) to augment the multi-region SQL statements.