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

florence-crl · florence-crl · commit f9a6f794c4c7 · 2025-07-09T14:03:30.000-04:00
diff --git a/src/current/_data/releases.yml b/src/current/_data/releases.yml
@@ -9129,3 +9129,31 @@
     docker_arm_limited_access: false
   source: true
   previous_release: v25.3.0-alpha.3
+
+
+- release_name: v25.3.0-beta.2
+  major_version: v25.3
+  release_date: '2025-07-09'
+  release_type: Testing
+  go_version: go1.23.7
+  sha: 931cea93c97da32a66de8eda76733e18ce64f841
+  has_sql_only: true
+  has_sha256sum: true
+  mac:
+    mac_arm: true
+    mac_arm_experimental: true
+    mac_arm_limited_access: false
+  windows: true
+  linux:
+    linux_arm: true
+    linux_arm_experimental: false
+    linux_arm_limited_access: false
+    linux_intel_fips: true
+    linux_arm_fips: false
+  docker:
+    docker_image: cockroachdb/cockroach-unstable
+    docker_arm: true
+    docker_arm_experimental: false
+    docker_arm_limited_access: false
+  source: true
+  previous_release: v25.3.0-beta.1
diff --git a/src/current/_includes/releases/v25.3/v25.3.0-beta.2.md b/src/current/_includes/releases/v25.3/v25.3.0-beta.2.md
@@ -0,0 +1,22 @@
+## v25.3.0-beta.2
+
+Release Date: July 9, 2025
+
+{% include releases/new-release-downloads-docker-image.md release=include.release %}
+
+<h3 id="v25-3-0-beta-2-general-changes">General changes</h3>
+
+- For virtual clusters, hot range logging is now performed by a single job on one node, rather than by tasks on every node.
+ [#148926][#148926]
+
+<h3 id="v25-3-0-beta-2-bug-fixes">Bug fixes</h3>
+
+- CockroachDB now prohibits `ORDER BY` and join equality operations on `REFCURSOR` types, matching PostgreSQL behavior.
+ [#149292][#149292]
+- Fixed an issue where CockroachDB could hit an internal error when performing a `DELETE`, `UPDATE`, or `UPSERT` where the initial scan of the mutation is locking and is on a table different from the one being mutated. A possible workaround was `SET enable_implicit_select_for_update = false`, but this could increase contention. The bug was introduced in v25.2 and is now fixed.
+ [#149302][#149302]
+
+
+[#148926]: https://github.com/cockroachdb/cockroach/pull/148926
+[#149292]: https://github.com/cockroachdb/cockroach/pull/149292
+[#149302]: https://github.com/cockroachdb/cockroach/pull/149302
diff --git a/src/current/v25.2/load-based-splitting.md b/src/current/v25.2/load-based-splitting.md
@@ -71,25 +71,42 @@ This benefit is further amplified by [load-based rebalancing]({% link {{ page.ve
 
 ## Monitor load-based splitting
 
+### Log message
+
 The [`INFO`]({% link {{ page.version.version }}/logging.md %}#info) log message
 
 ~~~
 no split key found: ...
 ~~~
 
-indicates that CockroachDB wants to [split the range]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) due to load, but couldn’t find a key to split at.
+indicates that CockroachDB attempted to [split the range]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) due to load, but could not identify a key at which to split.
+
+You can usually ignore this log message. However, if it appears repeatedly, it may indicate a load imbalance in the cluster. A load imbalance might occur if a range cannot be split because it contains a [hotspot]({% link {{ page.version.version }}/understand-hotspots.md %}). For more information about how to reduce hotspots on your cluster, refer to [Understand hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}).
+
+The log message ends with one of the following patterns that describe the observed load:
+
+1. `popular key detected, clear direction detected`
+1. `popular key detected, no clear direction`
+1. `no popular key, clear direction detected`
+1. `no popular key, no clear direction`
 
-Usually this log message can be ignored, unless it repeatedly shows up, which can indicate there is a load imbalance problem in the cluster. If there is a load imbalance problem, it could be because a [hot range]({% link {{ page.version.version }}/ui-hot-ranges-page.md %}) cannot be split (because it's really a [hot key]({% link {{ page.version.version }}/ui-hot-ranges-page.md %}#range-report)).
+These patterns may indicate either or both of the following conditions:
 
-You can see how often a split key cannot be found over time by looking at the following [time-series metric]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#prometheus-endpoint):
+- `popular key detected` indicates that a significant percentage of reads or writes targets a single row within the range of data.
+- `clear direction detected` indicates that accesses within the range progress steadily in one direction, either increasing or decreasing key order, which generally indicates an [index hotspot]({% link {{ page.version.version }}/understand-hotspots.md %}#index-hotspot).
 
-- `kv.loadsplitter.nosplitkey`
+### Metrics
 
-This metric is directly related to the log message described above.
+These [time-series metrics]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#prometheus-endpoint) correlate with the potential conditions described in the load-based splitting [log message](#log-message). You can monitor how often the load-based splitter fails to find a split key, and whether this is due to a popular key or a clear access direction.
 
-For more information about how to reduce hotspots (including hot ranges) on your cluster, refer to [Understand hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}).
+Metric | Description
+-------|-------------
+`kv.loadsplitter.nosplitkey` | Load-based splitter could not find a split key.
+`kv.loadsplitter.popularkey` | Load-based splitter could not find a split key and the most popular sampled split key occurs in >= 25% of the samples.
+`kv.loadsplitter.cleardirection` | Load-based splitter observed an access direction greater than 80% decreasing (left) or increasing (right) in the samples.
 
 ## See also
 
 - [`SET CLUSTER SETTING`]({% link {{ page.version.version }}/set-cluster-setting.md %})
 - [Load-based replica rebalancing]({% link {{ page.version.version }}/architecture/replication-layer.md %}#load-based-replica-rebalancing)
+- [Understand hotspots]({% link {{ page.version.version }}/understand-hotspots.md %})
diff --git a/src/current/v25.2/logging-use-cases.md b/src/current/v25.2/logging-use-cases.md
@@ -94,6 +94,20 @@ I210517 17:38:20.403619 586 2@util/log/event_log.go:32 ⋮ [n1] 168 ={"Timestamp
 `runtime_stats` events are typically used for troubleshooting. To monitor your cluster's health, see [Monitoring and Alerting]({% link {{ page.version.version }}/monitoring-and-alerting.md %}).
 {{site.data.alerts.end}}
 
+#### Example: Hot ranges stats
+
+Each node checks for [hot ranges]({% link {{ page.version.version }}/understand-hotspots.md %}#hot-range) every minute. If a single [replica]({% link {{ page.version.version }}/architecture/overview.md %}#replica) exceeds 250 ms of CPU time per second, a [`hot_ranges_stats`]({% link {{ page.version.version }}/eventlog.md %}#hot_ranges_stats) event is recorded. In [virtual clusters]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) and [CockroachDB Standard and Basic deployments]({% link cockroachcloud/index.md %}), nodes perform this check every 5 minutes at the cluster level. In addition to these conditional logs, `hot_ranges_stats` logs are automatically emitted every 4 hours.
+
+~~~
+I250602 04:46:54.752464 2023 2@util/log/event_log.go:39 ⋮ [T1,Vsystem,n5] 31977 ={"Timestamp":1748839613749807000,"EventType":"hot_ranges_stats","RangeID":1115,"Qps":0,"LeaseholderNodeID":5,"WritesPerSecond":0.0012048123820978134,"CPUTimePerSecond":251.30338109510822,"Databases":["kv"],"Tables":["kv"],"Indexes":["kv_pkey"]}
+~~~
+
+- Preceding the `=` character is the `crdb-v2` event metadata. See the [reference documentation]({% link {{ page.version.version }}/log-formats.md %}#format-crdb-v2) for details on the fields.
+
+{{site.data.alerts.callout_info}}
+`hot_ranges_stats` events are typically used for troubleshooting [hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}).
+{{site.data.alerts.end}}
+
 ### SQL_SCHEMA
 
 The [`SQL_SCHEMA`]({% link {{ page.version.version }}/logging.md %}#sql_schema) channel logs changes to the SQL logical schema resulting from DDL operations.
diff --git a/src/current/v25.2/ui-hot-ranges-page.md b/src/current/v25.2/ui-hot-ranges-page.md
@@ -15,9 +15,27 @@ When optimizing or troubleshooting statement performance, this page can help you
 
 To view this page, [access the DB Console]({% link {{ page.version.version }}/ui-overview.md %}#db-console-access) and click **Hot Ranges** in the left-hand navigation.
 
+## Select nodes
+
+In the **Select Nodes** filter, choose one or more nodes with high activity, such as high CPU usage, to investigate potential hotspots. Selecting fewer nodes can help identify the hottest ranges more quickly and improve page load time.
+
+Selecting a region, such as `us-east1`, selects all nodes in that region.
+
+In the **Select Nodes** search box, enter numbers to search for specific node IDs. For example, in a cluster with 12 nodes, entering `1` returns checkboxes for node IDs `n1`, `n10`, `n11`, and `n12`. 
+
+Click **Apply** to view the [hot ranges list](#hot-ranges-list) for the selected nodes.
+
 ## Filter hot ranges
 
-Use the **Filter** menu to filter the [hot ranges list](#hot-ranges-list) on any combination of: node ID, store ID, database, table, index, or locality.
+After [selecting nodes](#select-nodes), use the **Filter** menu to filter the [hot ranges list](#hot-ranges-list). You can choose to view all hot ranges across a specific table, index, store ID, and one or more databases.
+
+In the **Databases** dropdown list, you can choose to filter by specific databases (optional).
+
+In the **Table** and **Index** search boxes, enter the complete name of a table or index to return results. For example, in the [`movr` database]({% link {{ page.version.version }}/movr.md %}), search for the exact index name `users_pkey` to return results. Entering a partial index name, such as `user` or `users` returns no results.
+
+In the **Store ID** search box, enter numbers to search for specific store IDs. For example, in a cluster with 12 stores, entering `1` returns results for store IDs `1`, `10`, `11`, and `12`.
+
+Click **Apply** to view the filtered [hot ranges list](#hot-ranges-list).
 
 ## Hot ranges list
 
diff --git a/src/current/v25.3/load-based-splitting.md b/src/current/v25.3/load-based-splitting.md
@@ -71,25 +71,42 @@ This benefit is further amplified by [load-based rebalancing]({% link {{ page.ve
 
 ## Monitor load-based splitting
 
+### Log message
+
 The [`INFO`]({% link {{ page.version.version }}/logging.md %}#info) log message
 
 ~~~
 no split key found: ...
 ~~~
 
-indicates that CockroachDB wants to [split the range]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) due to load, but couldn’t find a key to split at.
+indicates that CockroachDB attempted to [split the range]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) due to load, but could not identify a key at which to split.
+
+You can usually ignore this log message. However, if it appears repeatedly, it may indicate a load imbalance in the cluster. A load imbalance might occur if a range cannot be split because it contains a [hotspot]({% link {{ page.version.version }}/understand-hotspots.md %}). For more information about how to reduce hotspots on your cluster, refer to [Understand hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}).
+
+The log message ends with one of the following patterns that describe the observed load:
+
+1. `popular key detected, clear direction detected`
+1. `popular key detected, no clear direction`
+1. `no popular key, clear direction detected`
+1. `no popular key, no clear direction`
 
-Usually this log message can be ignored, unless it repeatedly shows up, which can indicate there is a load imbalance problem in the cluster. If there is a load imbalance problem, it could be because a [hot range]({% link {{ page.version.version }}/ui-hot-ranges-page.md %}) cannot be split (because it's really a [hot key]({% link {{ page.version.version }}/ui-hot-ranges-page.md %}#range-report)).
+These patterns may indicate either or both of the following conditions:
 
-You can see how often a split key cannot be found over time by looking at the following [time-series metric]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#prometheus-endpoint):
+- `popular key detected` indicates that a significant percentage of reads or writes targets a single row within the range of data.
+- `clear direction detected` indicates that accesses within the range progress steadily in one direction, either increasing or decreasing key order, which generally indicates an [index hotspot]({% link {{ page.version.version }}/understand-hotspots.md %}#index-hotspot).
 
-- `kv.loadsplitter.nosplitkey`
+### Metrics
 
-This metric is directly related to the log message described above.
+These [time-series metrics]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#prometheus-endpoint) correlate with the potential conditions described in the load-based splitting [log message](#log-message). You can monitor how often the load-based splitter fails to find a split key, and whether this is due to a popular key or a clear access direction.
 
-For more information about how to reduce hotspots (including hot ranges) on your cluster, refer to [Understand hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}).
+Metric | Description
+-------|-------------
+`kv.loadsplitter.nosplitkey` | Load-based splitter could not find a split key.
+`kv.loadsplitter.popularkey` | Load-based splitter could not find a split key and the most popular sampled split key occurs in >= 25% of the samples.
+`kv.loadsplitter.cleardirection` | Load-based splitter observed an access direction greater than 80% decreasing (left) or increasing (right) in the samples.
 
 ## See also
 
 - [`SET CLUSTER SETTING`]({% link {{ page.version.version }}/set-cluster-setting.md %})
 - [Load-based replica rebalancing]({% link {{ page.version.version }}/architecture/replication-layer.md %}#load-based-replica-rebalancing)
+- [Understand hotspots]({% link {{ page.version.version }}/understand-hotspots.md %})
diff --git a/src/current/v25.3/logging-use-cases.md b/src/current/v25.3/logging-use-cases.md
@@ -94,6 +94,20 @@ I210517 17:38:20.403619 586 2@util/log/event_log.go:32 ⋮ [n1] 168 ={"Timestamp
 `runtime_stats` events are typically used for troubleshooting. To monitor your cluster's health, see [Monitoring and Alerting]({% link {{ page.version.version }}/monitoring-and-alerting.md %}).
 {{site.data.alerts.end}}
 
+#### Example: Hot ranges stats
+
+Each node checks for [hot ranges]({% link {{ page.version.version }}/understand-hotspots.md %}#hot-range) every minute. If a single [replica]({% link {{ page.version.version }}/architecture/overview.md %}#replica) exceeds 250 ms of CPU time per second, a [`hot_ranges_stats`]({% link {{ page.version.version }}/eventlog.md %}#hot_ranges_stats) event is recorded. In [virtual clusters]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) and [CockroachDB Standard and Basic deployments]({% link cockroachcloud/index.md %}), nodes perform this check every 5 minutes at the cluster level. In addition to these conditional logs, `hot_ranges_stats` logs are automatically emitted every 4 hours.
+
+~~~
+I250602 04:46:54.752464 2023 2@util/log/event_log.go:39 ⋮ [T1,Vsystem,n5] 31977 ={"Timestamp":1748839613749807000,"EventType":"hot_ranges_stats","RangeID":1115,"Qps":0,"LeaseholderNodeID":5,"WritesPerSecond":0.0012048123820978134,"CPUTimePerSecond":251.30338109510822,"Databases":["kv"],"Tables":["kv"],"Indexes":["kv_pkey"]}
+~~~
+
+- Preceding the `=` character is the `crdb-v2` event metadata. See the [reference documentation]({% link {{ page.version.version }}/log-formats.md %}#format-crdb-v2) for details on the fields.
+
+{{site.data.alerts.callout_info}}
+`hot_ranges_stats` events are typically used for troubleshooting [hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}).
+{{site.data.alerts.end}}
+
 ### SQL_SCHEMA
 
 The [`SQL_SCHEMA`]({% link {{ page.version.version }}/logging.md %}#sql_schema) channel logs changes to the SQL logical schema resulting from DDL operations.
diff --git a/src/current/v25.3/ui-hot-ranges-page.md b/src/current/v25.3/ui-hot-ranges-page.md
@@ -15,9 +15,27 @@ When optimizing or troubleshooting statement performance, this page can help you
 
 To view this page, [access the DB Console]({% link {{ page.version.version }}/ui-overview.md %}#db-console-access) and click **Hot Ranges** in the left-hand navigation.
 
+## Select nodes
+
+In the **Select Nodes** filter, choose one or more nodes with high activity, such as high CPU usage, to investigate potential hotspots. Selecting fewer nodes can help identify the hottest ranges more quickly and improve page load time.
+
+Selecting a region, such as `us-east1`, selects all nodes in that region.
+
+In the **Select Nodes** search box, enter numbers to search for specific node IDs. For example, in a cluster with 12 nodes, entering `1` returns checkboxes for node IDs `n1`, `n10`, `n11`, and `n12`. 
+
+Click **Apply** to view the [hot ranges list](#hot-ranges-list) for the selected nodes.
+
 ## Filter hot ranges
 
-Use the **Filter** menu to filter the [hot ranges list](#hot-ranges-list) on any combination of: node ID, store ID, database, table, index, or locality.
+After [selecting nodes](#select-nodes), use the **Filter** menu to filter the [hot ranges list](#hot-ranges-list). You can choose to view all hot ranges across a specific table, index, store ID, and one or more databases.
+
+In the **Databases** dropdown list, you can choose to filter by specific databases (optional).
+
+In the **Table** and **Index** search boxes, enter the complete name of a table or index to return results. For example, in the [`movr` database]({% link {{ page.version.version }}/movr.md %}), search for the exact index name `users_pkey` to return results. Entering a partial index name, such as `user` or `users` returns no results.
+
+In the **Store ID** search box, enter numbers to search for specific store IDs. For example, in a cluster with 12 stores, entering `1` returns results for store IDs `1`, `10`, `11`, and `12`.
+
+Click **Apply** to view the filtered [hot ranges list](#hot-ranges-list).
 
 ## Hot ranges list
 
