From 11814dbc1f38598463e4038b70d098cd2dc6e148 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 16 Apr 2026 14:20:44 -0400 Subject: [PATCH 1/3] Add docs on: TCP keepalive updates; `schema.auto_unlock` variable; `fuzzystrmatch` extension Fixes DOC-16221 --- .../v26.2/cdc/cdc-schema-locked-example.md | 4 ++-- .../v26.2/misc/table-storage-parameters.md | 2 +- src/current/v26.2/online-schema-changes.md | 2 +- src/current/v26.2/set-vars.md | 21 +++++++++++++++++++ src/current/v26.2/sql-feature-support.md | 1 + 5 files changed, 26 insertions(+), 4 deletions(-) diff --git a/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md b/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md index 8ac147c428f..08016be41d2 100644 --- a/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md +++ b/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md @@ -7,9 +7,9 @@ Enable `schema_locked` on the watched table with the [`ALTER TABLE`]({% link {{ ALTER TABLE watched_table SET (schema_locked = true); ~~~ -CockroachDB attempts to automatically unset `schema_locked` before performing a schema change and reapply it when done. However, certain schema changes (such as `ALTER TABLE ... SET LOCALITY`) cannot automatically unset it. For these cases, you must manually unlock the table with `schema_locked = false`, complete the schema change, and then lock the table again with `schema_locked = true`. The changefeed will run as normal while `schema_locked` is unset, but it will not benefit from the performance optimization. +By default, CockroachDB attempts to automatically unset `schema_locked` before performing many schema changes and reapply it when done. To require manual unlocks for all DDL on schema-locked tables, set [`sql.schema.auto_unlock.enabled`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-auto-unlock-enabled) to `false`. Some schema changes, such as `ALTER TABLE ... SET LOCALITY`, cannot automatically unset `schema_locked` even when automatic unlocking is enabled. For these cases, you must manually unlock the table with `schema_locked = false`, complete the schema change, and then lock the table again with `schema_locked = true`. The changefeed will run as normal while `schema_locked` is unset, but it will not benefit from the performance optimization. {% include_cached copy-clipboard.html %} ~~~ sql ALTER TABLE watched_table SET (schema_locked = false); -~~~ \ No newline at end of file +~~~ diff --git a/src/current/_includes/v26.2/misc/table-storage-parameters.md b/src/current/_includes/v26.2/misc/table-storage-parameters.md index c4c07ad4f59..89f8059dde9 100644 --- a/src/current/_includes/v26.2/misc/table-storage-parameters.md +++ b/src/current/_includes/v26.2/misc/table-storage-parameters.md @@ -2,7 +2,7 @@ |----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------| | `exclude_data_from_backup` | Exclude the data in this table from any future backups. | Boolean | `false` | | `infer_rbr_region_col_using_constraint` | For [`REGIONAL BY ROW`]({% link {{ page.version.version }}/table-localities.md %}#regional-by-row-tables) tables, automatically populate the hidden `crdb_region` column on `INSERT`, `UPDATE`, and `UPSERT` by looking up the region of the referenced parent row. Set this parameter to the name of a [foreign key]({% link {{ page.version.version }}/foreign-key.md %}) constraint on the table that includes the `crdb_region` column. The foreign key cannot be dropped while the parameter is set. | String | `NULL` | -| `schema_locked` | Indicates that a [schema change]({% link {{ page.version.version }}/online-schema-changes.md %}) is not currently ongoing on this table. CockroachDB automatically unsets this parameter before performing a schema change and reapplies it when done. Enabling `schema_locked` can help [improve performance of changefeeds]({% link {{ page.version.version }}/create-changefeed.md %}#disallow-schema-changes-on-tables-to-improve-changefeed-performance) running on this table. | Boolean | `false` | +| `schema_locked` | Indicates that a [schema change]({% link {{ page.version.version }}/online-schema-changes.md %}) is not currently ongoing on this table. By default, CockroachDB attempts to automatically unset this parameter before performing many schema changes and reapplies it when done. To require manual unlocks for all DDL on schema-locked tables, set [`sql.schema.auto_unlock.enabled`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-auto-unlock-enabled) to `false`. Enabling `schema_locked` can help [improve performance of changefeeds]({% link {{ page.version.version }}/create-changefeed.md %}#disallow-schema-changes-on-tables-to-improve-changefeed-performance) running on this table. | Boolean | `false` | | `sql_stats_automatic_collection_enabled` | Enable automatic collection of [full]({% link {{ page.version.version }}/cost-based-optimizer.md %}#full-statistics) and [partial]({% link {{ page.version.version }}/cost-based-optimizer.md %}#partial-statistics) statistics for this table. | Boolean | `true` | | `sql_stats_automatic_collection_min_stale_rows` | Minimum number of stale rows in this table that will trigger a full statistics refresh. | Integer | 500 | | `sql_stats_automatic_collection_fraction_stale_rows` | Fraction of stale rows in this table that will trigger a full statistics refresh. | Float | 0.2 | diff --git a/src/current/v26.2/online-schema-changes.md b/src/current/v26.2/online-schema-changes.md index ac0b7a9a74c..f054439f71a 100644 --- a/src/current/v26.2/online-schema-changes.md +++ b/src/current/v26.2/online-schema-changes.md @@ -74,7 +74,7 @@ For advice about how to avoid running out of space during an online schema chang ### Improve changefeed performance with `schema_locked` -Set the [`schema_locked` table storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#storage-parameter-schema-locked) to `true` to indicate that a schema change is not currently ongoing on a table. CockroachDB automatically unsets this parameter before performing a schema change and reapplies it when done. Enabling `schema_locked` can help [improve performance of changefeeds]({% link {{ page.version.version }}/create-changefeed.md %}#disallow-schema-changes-on-tables-to-improve-changefeed-performance) running on the table, which can reduce commit-to-emit latency. +Set the [`schema_locked` table storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#storage-parameter-schema-locked) to `true` to indicate that a schema change is not currently ongoing on a table. By default, CockroachDB attempts to automatically unset this parameter before performing many schema changes and reapplies it when done. To require manual unlocks for all DDL on schema-locked tables, set [`sql.schema.auto_unlock.enabled`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-auto-unlock-enabled) to `false`. Some schema changes, such as `ALTER TABLE ... SET LOCALITY`, still require a manual unlock even when automatic unlocking is enabled. Enabling `schema_locked` can help [improve performance of changefeeds]({% link {{ page.version.version }}/create-changefeed.md %}#disallow-schema-changes-on-tables-to-improve-changefeed-performance) running on the table, which can reduce commit-to-emit latency. Use the [`create_table_with_schema_locked` session variable]({% link {{ page.version.version }}/set-vars.md %}#create_table_with_schema_locked) to set this storage parameter to `true` on every table created in the session. In v26.1 and later, it is enabled by default. diff --git a/src/current/v26.2/set-vars.md b/src/current/v26.2/set-vars.md index 878c7ba3cac..7bff2666690 100644 --- a/src/current/v26.2/set-vars.md +++ b/src/current/v26.2/set-vars.md @@ -135,6 +135,27 @@ SHOW search_path; (1 row) ~~~ +### Configure TCP keepalive session variables + +{% include_cached new-in.html version="v26.2" %} CockroachDB supports the PostgreSQL-compatible session variables `tcp_keepalives_idle`, `tcp_keepalives_interval`, `tcp_keepalives_count`, and `tcp_user_timeout`. A value of `0` uses the corresponding cluster setting: + +- `tcp_keepalives_idle`: [`server.sql_tcp_keep_alive.idle`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-idle) +- `tcp_keepalives_interval`: [`server.sql_tcp_keep_alive.interval`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-interval) +- `tcp_keepalives_count`: [`server.sql_tcp_keep_alive.count`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-count) +- `tcp_user_timeout`: [`server.sql_tcp_user.timeout`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-user-timeout) + +`tcp_keepalives_idle` and `tcp_keepalives_interval` are stored in seconds and can be set either as integer seconds or as duration strings, truncated to whole seconds. `tcp_keepalives_count` is an integer probe count. `tcp_user_timeout` is stored in milliseconds and can be set either as integer milliseconds or as duration strings, truncated to whole milliseconds. + +{% include_cached copy-clipboard.html %} +~~~ sql +SET tcp_keepalives_idle = 25; +SET tcp_keepalives_interval = 8; +SET tcp_keepalives_count = 4; +SET tcp_user_timeout = 15000; +~~~ + +You can also pass these values in a client connection string by appending `options=-c tcp_keepalives_idle=25 -c tcp_keepalives_interval=8 -c tcp_keepalives_count=4 -c tcp_user_timeout=15000`. + ### Reset a variable to its default value {{site.data.alerts.callout_success}} diff --git a/src/current/v26.2/sql-feature-support.md b/src/current/v26.2/sql-feature-support.md index df9fa0711d8..d0d4b8051d6 100644 --- a/src/current/v26.2/sql-feature-support.md +++ b/src/current/v26.2/sql-feature-support.md @@ -194,4 +194,5 @@ XML | ✗ | Standard | XML data can be stored as `BYTES`, but we do not offer XM Triggers | Partial | Standard | [Triggers documentation]({% link {{ page.version.version }}/triggers.md %}) Row-level TTL | ✓ | Common Extension | Automatically delete expired rows. For more information, see [Batch-delete expired data with Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}). User-defined functions | Partial | Standard | [User-Defined Functions documentation]({% link {{ page.version.version }}/user-defined-functions.md %}) + New in v26.2: `CREATE EXTENSION "fuzzystrmatch"` | ✓ | Common Extension | Provides PostgreSQL-compatible fuzzy string matching functions including `soundex()`, `difference()`, `levenshtein()`, `metaphone()`, [`dmetaphone()`]({% link {{ page.version.version }}/functions-and-operators.md %}#dmetaphone), [`dmetaphone_alt()`]({% link {{ page.version.version }}/functions-and-operators.md %}#dmetaphone_alt), and [`daitch_mokotoff()`]({% link {{ page.version.version }}/functions-and-operators.md %}#daitch_mokotoff). These functions are available without running `CREATE EXTENSION "fuzzystrmatch"`. CockroachDB does not have full support for `CREATE EXTENSION`. [GitHub issue tracking `CREATE EXTENSION` support](https://github.com/cockroachdb/cockroach/issues/74777). `CREATE EXTENSION "uuid-ossp"` | ✓ | Common Extension | Provides access to several additional [UUID generation functions]({% link {{ page.version.version }}/functions-and-operators.md %}#id-generation-functions). Note that these UUID functions are available without typing `CREATE EXTENSION "uuid-ossp"`. CockroachDB does not have full support for `CREATE EXTENSION`. [GitHub issue tracking `CREATE EXTENSION` support](https://github.com/cockroachdb/cockroach/issues/74777). From cd80c618945cec6f716387275780766d94eba4b0 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 16 Apr 2026 14:54:08 -0400 Subject: [PATCH 2/3] Move TCP keepalive session vars into shared include --- .../_includes/v26.2/misc/session-vars.md | 4 ++++ src/current/v26.2/set-vars.md | 21 ------------------- 2 files changed, 4 insertions(+), 21 deletions(-) diff --git a/src/current/_includes/v26.2/misc/session-vars.md b/src/current/_includes/v26.2/misc/session-vars.md index 1e78e7b1cf5..69a33b434dc 100644 --- a/src/current/_includes/v26.2/misc/session-vars.md +++ b/src/current/_includes/v26.2/misc/session-vars.md @@ -82,6 +82,10 @@ | `sql_safe_updates` | If `true`, the following potentially unsafe SQL statements are disallowed: [`DROP DATABASE`]({% link {{ page.version.version }}/drop-database.md %}) of a non-empty database and all dependent objects; [`DELETE`]({% link {{ page.version.version }}/delete.md %}) and [`UPDATE`]({% link {{ page.version.version }}/update.md %}) without a `WHERE` clause, unless a [`LIMIT`]({% link {{ page.version.version }}/limit-offset.md %}) clause is included; [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) and [`SELECT ... FOR SHARE`]({% link {{ page.version.version }}/select-for-update.md %}) without a `WHERE` or [`LIMIT`]({% link {{ page.version.version }}/limit-offset.md %}) clause; [`ALTER TABLE ... DROP COLUMN`]({% link {{ page.version.version }}/alter-table.md %}#drop-column); and converting an existing table to [`REGIONAL BY ROW`]({% link {{ page.version.version }}/alter-table.md %}#set-the-table-locality-to-regional-by-row) using [`ALTER TABLE ... LOCALITY`]({% link {{ page.version.version }}/alter-table.md %}#regional-by-row), unless a [region column]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) has already been added to the table.
For more details, refer to [Allow potentially unsafe SQL statements]({% link {{ page.version.version }}/cockroach-sql.md %}#allow-potentially-unsafe-sql-statements). | `true` for interactive sessions from the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}),
`false` for sessions from other clients | Yes | Yes | | `statement_timeout` | The amount of time a statement can run before being stopped.
This value can be an `int` (e.g., `10`) and will be interpreted as milliseconds. It can also be an interval or string argument, where the string can be parsed as a valid interval (e.g., `'4s'`).
A value of `0` turns it off. | The value set by the `sql.defaults.statement_timeout` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) (`0s`, by default). | Yes | Yes | | `stub_catalog_tables` | If `off`, querying an unimplemented, empty [`pg_catalog`]({% link {{ page.version.version }}/pg-catalog.md %}) table will result in an error, as is the case in v20.2 and earlier. If `on`, querying an unimplemented, empty `pg_catalog` table simply returns no rows. | `on` | Yes | Yes | +| New in v26.2: `tcp_keepalives_count` | The number of TCP keepalive probes sent before an idle connection is considered lost. `0` uses the [`server.sql_tcp_keep_alive.count`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-count) cluster setting. | `0` | Yes | Yes | +| New in v26.2: `tcp_keepalives_idle` | The idle time before TCP keepalive probes are sent. `0` uses the [`server.sql_tcp_keep_alive.idle`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-idle) cluster setting. Stored in seconds; can be set as integer seconds or duration strings, truncated to whole seconds. | `0` | Yes | Yes | +| New in v26.2: `tcp_keepalives_interval` | The time between TCP keepalive probes. `0` uses the [`server.sql_tcp_keep_alive.interval`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-interval) cluster setting. Stored in seconds; can be set as integer seconds or duration strings, truncated to whole seconds. | `0` | Yes | Yes | +| New in v26.2: `tcp_user_timeout` | The TCP user timeout for unacknowledged data. `0` uses the [`server.sql_tcp_user.timeout`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-user-timeout) cluster setting. Stored in milliseconds; can be set as integer milliseconds or duration strings, truncated to whole milliseconds. | `0` | Yes | Yes | | `timezone` | The default time zone for the current session. | `UTC` | Yes | Yes | | `tracing` | The trace recording state. | `off` | Yes | Yes | | `transaction_isolation` | The isolation level at which the transaction executes ([`SERIALIZABLE`]({% link {{ page.version.version }}/demo-serializable.md %}) or [`READ COMMITTED`]({% link {{ page.version.version }}/read-committed.md %})). See [Isolation levels]({% link {{ page.version.version }}/transactions.md %}#isolation-levels). | `SERIALIZABLE` | Yes | Yes | diff --git a/src/current/v26.2/set-vars.md b/src/current/v26.2/set-vars.md index 7bff2666690..878c7ba3cac 100644 --- a/src/current/v26.2/set-vars.md +++ b/src/current/v26.2/set-vars.md @@ -135,27 +135,6 @@ SHOW search_path; (1 row) ~~~ -### Configure TCP keepalive session variables - -{% include_cached new-in.html version="v26.2" %} CockroachDB supports the PostgreSQL-compatible session variables `tcp_keepalives_idle`, `tcp_keepalives_interval`, `tcp_keepalives_count`, and `tcp_user_timeout`. A value of `0` uses the corresponding cluster setting: - -- `tcp_keepalives_idle`: [`server.sql_tcp_keep_alive.idle`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-idle) -- `tcp_keepalives_interval`: [`server.sql_tcp_keep_alive.interval`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-interval) -- `tcp_keepalives_count`: [`server.sql_tcp_keep_alive.count`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-keep-alive-count) -- `tcp_user_timeout`: [`server.sql_tcp_user.timeout`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-sql-tcp-user-timeout) - -`tcp_keepalives_idle` and `tcp_keepalives_interval` are stored in seconds and can be set either as integer seconds or as duration strings, truncated to whole seconds. `tcp_keepalives_count` is an integer probe count. `tcp_user_timeout` is stored in milliseconds and can be set either as integer milliseconds or as duration strings, truncated to whole milliseconds. - -{% include_cached copy-clipboard.html %} -~~~ sql -SET tcp_keepalives_idle = 25; -SET tcp_keepalives_interval = 8; -SET tcp_keepalives_count = 4; -SET tcp_user_timeout = 15000; -~~~ - -You can also pass these values in a client connection string by appending `options=-c tcp_keepalives_idle=25 -c tcp_keepalives_interval=8 -c tcp_keepalives_count=4 -c tcp_user_timeout=15000`. - ### Reset a variable to its default value {{site.data.alerts.callout_success}} From 6ff368c369a9c10ec9e9d441b5df0017fdc5f541 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 16 Apr 2026 14:55:36 -0400 Subject: [PATCH 3/3] Fix grammar plurality nit --- src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md b/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md index 08016be41d2..a82e8d72578 100644 --- a/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md +++ b/src/current/_includes/v26.2/cdc/cdc-schema-locked-example.md @@ -7,7 +7,7 @@ Enable `schema_locked` on the watched table with the [`ALTER TABLE`]({% link {{ ALTER TABLE watched_table SET (schema_locked = true); ~~~ -By default, CockroachDB attempts to automatically unset `schema_locked` before performing many schema changes and reapply it when done. To require manual unlocks for all DDL on schema-locked tables, set [`sql.schema.auto_unlock.enabled`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-auto-unlock-enabled) to `false`. Some schema changes, such as `ALTER TABLE ... SET LOCALITY`, cannot automatically unset `schema_locked` even when automatic unlocking is enabled. For these cases, you must manually unlock the table with `schema_locked = false`, complete the schema change, and then lock the table again with `schema_locked = true`. The changefeed will run as normal while `schema_locked` is unset, but it will not benefit from the performance optimization. +By default, CockroachDB attempts to automatically unset `schema_locked` before performing many schema changes and reapplies it when done. To require manual unlocks for all DDL on schema-locked tables, set [`sql.schema.auto_unlock.enabled`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-schema-auto-unlock-enabled) to `false`. Some schema changes, such as `ALTER TABLE ... SET LOCALITY`, cannot automatically unset `schema_locked` even when automatic unlocking is enabled. For these cases, you must manually unlock the table with `schema_locked = false`, complete the schema change, and then lock the table again with `schema_locked = true`. The changefeed will run as normal while `schema_locked` is unset, but it will not benefit from the performance optimization. {% include_cached copy-clipboard.html %} ~~~ sql