From 5d59352a6611e83d61207c32201bc96881696c70 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 8 Oct 2025 15:17:48 -0400 Subject: [PATCH 1/2] Update `sql.defaults.results_buffer.size` docs Fixes: - DOC-10360 - DOC-12305 Summary of changes: - This update removes all mentions of the default value in prose, and instead points the user to the single source of truth on the cluster settings page. - Files updated: `READ COMMITTED` page, and an include used on the 'Transactions' and 'Transaction Retry Error Reference' pages --- .../_includes/v24.1/performance/increase-server-side-retries.md | 2 +- src/current/v24.1/read-committed.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/_includes/v24.1/performance/increase-server-side-retries.md b/src/current/_includes/v24.1/performance/increase-server-side-retries.md index 95f2c2a9647..a5957921abb 100644 --- a/src/current/_includes/v24.1/performance/increase-server-side-retries.md +++ b/src/current/_includes/v24.1/performance/increase-server-side-retries.md @@ -2,4 +2,4 @@ -- Limit the size of the result sets of your transactions to under 16KB, so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set over 16KB, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the `sql.defaults.results_buffer.size` [cluster setting](cluster-settings.html), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). +- Limit the size of the result sets of your transactions to less than the value of the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set larger than the configured buffer size, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). diff --git a/src/current/v24.1/read-committed.md b/src/current/v24.1/read-committed.md index bcf0a5d9f92..6b83f50d88d 100644 --- a/src/current/v24.1/read-committed.md +++ b/src/current/v24.1/read-committed.md @@ -154,7 +154,7 @@ Starting a transaction as `READ COMMITTED` does not affect the [default isolatio - [Constraint]({% link {{ page.version.version }}/constraints.md %}) violations will abort transactions at all isolation levels. -- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to 16 KiB before overflowing and being streamed to the client. You can configure the result buffer size using the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting. +- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to the value of the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting before overflowing and being streamed to the client. ### Concurrency anomalies From 042fe9c26fef3ec942a84751922af04dd594455b Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 9 Oct 2025 15:22:14 -0400 Subject: [PATCH 2/2] NB. Changes ported to supported versions v24.1+ --- .../_includes/v24.3/performance/increase-server-side-retries.md | 2 +- .../_includes/v25.2/performance/increase-server-side-retries.md | 2 +- .../_includes/v25.3/performance/increase-server-side-retries.md | 2 +- .../_includes/v25.4/performance/increase-server-side-retries.md | 2 +- src/current/v24.3/read-committed.md | 2 +- src/current/v25.2/read-committed.md | 2 +- src/current/v25.3/read-committed.md | 2 +- src/current/v25.4/read-committed.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/current/_includes/v24.3/performance/increase-server-side-retries.md b/src/current/_includes/v24.3/performance/increase-server-side-retries.md index 95f2c2a9647..a5957921abb 100644 --- a/src/current/_includes/v24.3/performance/increase-server-side-retries.md +++ b/src/current/_includes/v24.3/performance/increase-server-side-retries.md @@ -2,4 +2,4 @@ -- Limit the size of the result sets of your transactions to under 16KB, so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set over 16KB, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the `sql.defaults.results_buffer.size` [cluster setting](cluster-settings.html), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). +- Limit the size of the result sets of your transactions to less than the value of the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set larger than the configured buffer size, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). diff --git a/src/current/_includes/v25.2/performance/increase-server-side-retries.md b/src/current/_includes/v25.2/performance/increase-server-side-retries.md index 95f2c2a9647..a5957921abb 100644 --- a/src/current/_includes/v25.2/performance/increase-server-side-retries.md +++ b/src/current/_includes/v25.2/performance/increase-server-side-retries.md @@ -2,4 +2,4 @@ -- Limit the size of the result sets of your transactions to under 16KB, so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set over 16KB, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the `sql.defaults.results_buffer.size` [cluster setting](cluster-settings.html), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). +- Limit the size of the result sets of your transactions to less than the value of the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set larger than the configured buffer size, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). diff --git a/src/current/_includes/v25.3/performance/increase-server-side-retries.md b/src/current/_includes/v25.3/performance/increase-server-side-retries.md index 95f2c2a9647..a5957921abb 100644 --- a/src/current/_includes/v25.3/performance/increase-server-side-retries.md +++ b/src/current/_includes/v25.3/performance/increase-server-side-retries.md @@ -2,4 +2,4 @@ -- Limit the size of the result sets of your transactions to under 16KB, so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set over 16KB, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the `sql.defaults.results_buffer.size` [cluster setting](cluster-settings.html), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). +- Limit the size of the result sets of your transactions to less than the value of the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set larger than the configured buffer size, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). diff --git a/src/current/_includes/v25.4/performance/increase-server-side-retries.md b/src/current/_includes/v25.4/performance/increase-server-side-retries.md index 95f2c2a9647..a5957921abb 100644 --- a/src/current/_includes/v25.4/performance/increase-server-side-retries.md +++ b/src/current/_includes/v25.4/performance/increase-server-side-retries.md @@ -2,4 +2,4 @@ -- Limit the size of the result sets of your transactions to under 16KB, so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set over 16KB, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the `sql.defaults.results_buffer.size` [cluster setting](cluster-settings.html), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). +- Limit the size of the result sets of your transactions to less than the value of the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), so that CockroachDB is more likely to [automatically retry]({% link {{ page.version.version }}/transactions.md %}#automatic-retries) when [previous reads are invalidated]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#read-refreshing) at a [pushed timestamp]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#timestamp-cache). When a transaction returns a result set larger than the configured buffer size, even if that transaction has been sent as a single batch, CockroachDB cannot automatically retry the transaction. You can change the results buffer size for all new sessions using the [`sql.defaults.results_buffer.size` cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size), or for a specific session using the `results_buffer_size` [connection parameter]({% link {{page.version.version}}/connection-parameters.md %}#additional-connection-parameters). diff --git a/src/current/v24.3/read-committed.md b/src/current/v24.3/read-committed.md index bcf0a5d9f92..6b83f50d88d 100644 --- a/src/current/v24.3/read-committed.md +++ b/src/current/v24.3/read-committed.md @@ -154,7 +154,7 @@ Starting a transaction as `READ COMMITTED` does not affect the [default isolatio - [Constraint]({% link {{ page.version.version }}/constraints.md %}) violations will abort transactions at all isolation levels. -- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to 16 KiB before overflowing and being streamed to the client. You can configure the result buffer size using the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting. +- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to the value of the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting before overflowing and being streamed to the client. ### Concurrency anomalies diff --git a/src/current/v25.2/read-committed.md b/src/current/v25.2/read-committed.md index bcf0a5d9f92..6b83f50d88d 100644 --- a/src/current/v25.2/read-committed.md +++ b/src/current/v25.2/read-committed.md @@ -154,7 +154,7 @@ Starting a transaction as `READ COMMITTED` does not affect the [default isolatio - [Constraint]({% link {{ page.version.version }}/constraints.md %}) violations will abort transactions at all isolation levels. -- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to 16 KiB before overflowing and being streamed to the client. You can configure the result buffer size using the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting. +- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to the value of the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting before overflowing and being streamed to the client. ### Concurrency anomalies diff --git a/src/current/v25.3/read-committed.md b/src/current/v25.3/read-committed.md index bcf0a5d9f92..6b83f50d88d 100644 --- a/src/current/v25.3/read-committed.md +++ b/src/current/v25.3/read-committed.md @@ -154,7 +154,7 @@ Starting a transaction as `READ COMMITTED` does not affect the [default isolatio - [Constraint]({% link {{ page.version.version }}/constraints.md %}) violations will abort transactions at all isolation levels. -- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to 16 KiB before overflowing and being streamed to the client. You can configure the result buffer size using the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting. +- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to the value of the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting before overflowing and being streamed to the client. ### Concurrency anomalies diff --git a/src/current/v25.4/read-committed.md b/src/current/v25.4/read-committed.md index bcf0a5d9f92..6b83f50d88d 100644 --- a/src/current/v25.4/read-committed.md +++ b/src/current/v25.4/read-committed.md @@ -154,7 +154,7 @@ Starting a transaction as `READ COMMITTED` does not affect the [default isolatio - [Constraint]({% link {{ page.version.version }}/constraints.md %}) violations will abort transactions at all isolation levels. -- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to 16 KiB before overflowing and being streamed to the client. You can configure the result buffer size using the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting. +- In rare cases under `READ COMMITTED` isolation, a [`RETRY_WRITE_TOO_OLD`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#retry_write_too_old) or [`ReadWithinUncertaintyIntervalError`]({% link {{ page.version.version }}/transaction-retry-error-reference.md %}#readwithinuncertaintyintervalerror) error can be returned to the client if a statement has already begun streaming a partial result set back to the client and cannot retry transparently. By default, the result set is buffered up to the value of the [`sql.defaults.results_buffer.size`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-results-buffer-size) cluster setting before overflowing and being streamed to the client. ### Concurrency anomalies