cockroachdb · rafiss · Dec 12, 2025 · Dec 11, 2025
diff --git a/src/current/_includes/releases/v25.3/v25.3.0-beta.1.md b/src/current/_includes/releases/v25.3/v25.3.0-beta.1.md
@@ -29,8 +29,6 @@ Release Date: July 2, 2025
   [#148242][#148242]
 - Restore will now re-attempt `AdminSplit` KV requests instead of immediately failing and pausing the job.
   [#148484][#148484]
-- To improve changefeed performance, the session variable `create_table_with_schema_locked` is enabled by default. This means all new tables are created with the `schema_locked` storage parameter. This setting must be explicitly unset for explicit transactions or for schema changes that do not support automatic disabling (e.g., `ALTER TABLE ... SET LOCALITY`).
- [#148839][#148839]
 
 <h3 id="v25-3-0-beta-1-bug-fixes">Bug fixes</h3>
 

diff --git a/src/current/_includes/releases/v25.4/v25.4.0-alpha.1.md b/src/current/_includes/releases/v25.4/v25.4.0-alpha.1.md
@@ -68,7 +68,6 @@ Release Date: September 17, 2025
 - CockroachDB spatial libraries now rely on GEOS 3.13 instead of GEOS 3.12. [#151186][#151186]
 - Reduced the maximum backoff for changefeed retries from 10 minutes to 1 minute, which results in faster recovery from transient errors. [#146448][#146448]
 - Added `changefeed.sink_backpressure_nanos` metric to track time spent waiting for quota when emitting to the sink. [#150666][#150666]
-- To improve changefeed performance, the session variable `create_table_with_schema_locked` is enabled by default. This means all new tables are created with the `schema_locked` storage parameter. This setting must be explicitly unset for explicit transactions or for schema changes that do not support automatic disabling (e.g., `ALTER TABLE ... SET LOCALITY`). [#148576][#148576]
 - The download phase of restore operations now will retry downloads before giving up, when faced with an error. [#148821][#148821]
 - Fixed a memory accounting issue in the client certificate cache that caused multiple allocations to be reported for the same certificate. The cache now accurately tracks memory usage and includes a safeguard to prevent it from negatively affecting SQL operations. [#151041][#151041]
 - Fixed a rare bug in restore where an object storage error on restore start could cause restore to report success without creating the restored tables or databases. [#151148][#151148]

diff --git a/src/current/_includes/releases/v26.1/v26.1.0-alpha.1.md b/src/current/_includes/releases/v26.1/v26.1.0-alpha.1.md
@@ -9,6 +9,7 @@ Release Date: December 4, 2025
 - Docker images now use UBI 10 as the base image. [#153990][#153990]
 - The changefeed bulk
   delivery setting was made optional. [#154870][#154870]
+- To improve changefeed performance, the session variable `create_table_with_schema_locked` is enabled by default. This means all new tables are created with the `schema_locked` storage parameter. `schema_locked` must be explicitly unset for explicit transactions or for schema changes that do not support automatic disabling (e.g., `ALTER TABLE ... SET LOCALITY`).
 
 <h3 id="v26-1-0-alpha-1-sql-language-changes">SQL language changes</h3>
 

diff --git a/src/current/_includes/v25.3/cdc/cdc-schema-locked-example.md b/src/current/_includes/v25.3/cdc/cdc-schema-locked-example.md
@@ -1,4 +1,4 @@
-Use the `schema_locked` [storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}) to disallow [schema changes]({% link {{ page.version.version }}/online-schema-changes.md %}) on a watched table, which allows the changefeed to take a fast path that avoids checking if there are schema changes that could require synchronization between [changefeed aggregators]({% link {{ page.version.version }}/how-does-a-changefeed-work.md %}). This helps to decrease the latency between a write committing to a table and it emitting to the [changefeed's sink]({% link {{ page.version.version }}/changefeed-sinks.md %}). Enabling `schema_locked` 
+Use the `schema_locked` [storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}) to indicate that a [schema change]({% link {{ page.version.version }}/online-schema-changes.md %}) is not currently ongoing on a watched table. This allows the changefeed to take a fast path that avoids checking if there are schema changes that could require synchronization between [changefeed aggregators]({% link {{ page.version.version }}/how-does-a-changefeed-work.md %}). This helps to decrease the latency between a write committing to a table and it emitting to the [changefeed's sink]({% link {{ page.version.version }}/changefeed-sinks.md %}).
 
 Enable `schema_locked` on the watched table with the [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}) statement:
 
@@ -7,7 +7,7 @@ Enable `schema_locked` on the watched table with the [`ALTER TABLE`]({% link {{
 ALTER TABLE watched_table SET (schema_locked = true);
 ~~~
 
-While `schema_locked` is enabled on a table, attempted schema changes on the table will be rejected and an error returned. If you need to run a schema change on the locked table, 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 = false`, but it will not benefit from the performance optimization.
+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.
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql

diff --git a/src/current/_includes/v25.3/misc/session-vars.md b/src/current/_includes/v25.3/misc/session-vars.md
@@ -9,7 +9,7 @@
 | <a id="copy-transaction-quality-of-service"></a> `copy_transaction_quality_of_service` | The default quality of service for [`COPY`]({% link {{ page.version.version }}/copy.md %}) statements in the current session. The supported options are `regular`, `critical`, and `background`. See [Set quality of service level]({% link {{ page.version.version }}/admission-control.md %}#copy-qos). | `background` | Yes | Yes |
 | <a id="cost-scans-with-default-col-size"></a> `cost_scans_with_default_col_size` | Whether to prevent the optimizer from considering column size when costing plans. | `false` | Yes | Yes |
 | <a id="crdb-version"></a> `crdb_version` | The version of CockroachDB. | <code>CockroachDB OSS <i>version</i></code> | No | Yes |
-| <span class="version-tag">New in v25.3:</span> <a id="create_table_with_schema_locked"></a> `create_table_with_schema_locked` | When enabled, ensures that all tables created during a [session]({% link {{ page.version.version }}/show-sessions.md %}) enable the [`schema_locked` storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#storage-parameter-schema-locked), which disallows schema changes. | `off` | Yes | Yes |
+| <span class="version-tag">New in v25.3:</span> <a id="create_table_with_schema_locked"></a> `create_table_with_schema_locked` | When enabled, ensures that all tables created during a [session]({% link {{ page.version.version }}/show-sessions.md %}) enable the [`schema_locked` storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#storage-parameter-schema-locked), which improves [changefeed]({% link {{ page.version.version }}/change-data-capture-overview.md %}) performance by indicating that a schema change is not currently ongoing. | `off` | Yes | Yes |
 | <a id="database"></a> `database` | The [current database]({% link {{ page.version.version }}/sql-name-resolution.md %}#current-database). | Database in connection string, or empty if not specified. | Yes | Yes |
 | <a id="datestyle"></a> `datestyle` | The input string format for [`DATE`]({% link {{ page.version.version }}/date.md %}) and [`TIMESTAMP`]({% link {{ page.version.version }}/timestamp.md %}) values. Accepted values include `ISO,MDY`, `ISO,DMY`, and `ISO,YMD`. | The value set by the `sql.defaults.datestyle` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) (`ISO,MDY`, by default). | Yes | Yes |
 | <a id="default-int-size"></a> `default_int_size` | The size, in bytes, of an [`INT`]({% link {{ page.version.version }}/int.md %}) type. | `8` | Yes | Yes |

diff --git a/src/current/_includes/v25.3/misc/table-storage-parameters.md b/src/current/_includes/v25.3/misc/table-storage-parameters.md
@@ -1,7 +1,7 @@
 |                         Parameter name                         |                                                                                                                                                                                                                                                Description                                                                                                                                                                                                                                                | Data type | Default value |
 |----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------|
 | `exclude_data_from_backup`                                     | Exclude the data in this table from any future backups.                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Boolean   | `false`       |
-| <a name="storage-parameter-schema-locked"></a> `schema_locked` | Disallow [schema changes]({% link {{ page.version.version }}/online-schema-changes.md %}) on this table. 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`       |
+| <a name="storage-parameter-schema-locked"></a> `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`       |
 | `sql_stats_automatic_collection_enabled`                       | Enable [automatic statistics collection]({% link {{ page.version.version }}/cost-based-optimizer.md %}#enable-and-disable-automatic-statistics-collection-for-tables) for this table.                                                                                                                                                                                                                                                                                                                     | Boolean   | `true`        |
 | `sql_stats_automatic_collection_min_stale_rows`                | Minimum number of stale rows in this table that will trigger a statistics refresh.                                                                                                                                                                                                                                                                                                                                                                                                                        | Integer   | 500           |
 | `sql_stats_automatic_collection_fraction_stale_rows`           | Fraction of stale rows in this table that will trigger a statistics refresh.                                                                                                                                                                                                                                                                                                                                                                                                                              | Float     | 0.2           |

diff --git a/src/current/_includes/v25.4/cdc/cdc-schema-locked-example.md b/src/current/_includes/v25.4/cdc/cdc-schema-locked-example.md
@@ -1,4 +1,4 @@
-Use the `schema_locked` [storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}) to disallow [schema changes]({% link {{ page.version.version }}/online-schema-changes.md %}) on a watched table, which allows the changefeed to take a fast path that avoids checking if there are schema changes that could require synchronization between [changefeed aggregators]({% link {{ page.version.version }}/how-does-a-changefeed-work.md %}). This helps to decrease the latency between a write committing to a table and it emitting to the [changefeed's sink]({% link {{ page.version.version }}/changefeed-sinks.md %}). Enabling `schema_locked` 
+Use the `schema_locked` [storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}) to indicate that a [schema change]({% link {{ page.version.version }}/online-schema-changes.md %}) is not currently ongoing on a watched table. This allows the changefeed to take a fast path that avoids checking if there are schema changes that could require synchronization between [changefeed aggregators]({% link {{ page.version.version }}/how-does-a-changefeed-work.md %}). This helps to decrease the latency between a write committing to a table and it emitting to the [changefeed's sink]({% link {{ page.version.version }}/changefeed-sinks.md %}).
 
 Enable `schema_locked` on the watched table with the [`ALTER TABLE`]({% link {{ page.version.version }}/alter-table.md %}) statement:
 
@@ -7,7 +7,7 @@ Enable `schema_locked` on the watched table with the [`ALTER TABLE`]({% link {{
 ALTER TABLE watched_table SET (schema_locked = true);
 ~~~
 
-While `schema_locked` is enabled on a table, attempted schema changes on the table will be rejected and an error returned. If you need to run a schema change on the locked table, 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 = false`, but it will not benefit from the performance optimization.
+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.
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql

diff --git a/src/current/_includes/v25.4/misc/session-vars.md b/src/current/_includes/v25.4/misc/session-vars.md
@@ -10,7 +10,7 @@
 | <a id="copy-transaction-quality-of-service"></a> `copy_transaction_quality_of_service` | The default quality of service for [`COPY`]({% link {{ page.version.version }}/copy.md %}) statements in the current session. The supported options are `regular`, `critical`, and `background`. See [Set quality of service level]({% link {{ page.version.version }}/admission-control.md %}#copy-qos). | `background` | Yes | Yes |
 | <a id="cost-scans-with-default-col-size"></a> `cost_scans_with_default_col_size` | Whether to prevent the optimizer from considering column size when costing plans. | `false` | Yes | Yes |
 | <a id="crdb-version"></a> `crdb_version` | The version of CockroachDB. | <code>CockroachDB OSS <i>version</i></code> | No | Yes |
-| <a id="create_table_with_schema_locked"></a> `create_table_with_schema_locked` | When enabled, ensures that all tables created during a [session]({% link {{ page.version.version }}/show-sessions.md %}) enable the [`schema_locked` storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#storage-parameter-schema-locked), which disallows schema changes. | `off` | Yes | Yes |
+| <a id="create_table_with_schema_locked"></a> `create_table_with_schema_locked` | When enabled, ensures that all tables created during a [session]({% link {{ page.version.version }}/show-sessions.md %}) enable the [`schema_locked` storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#storage-parameter-schema-locked), which improves [changefeed]({% link {{ page.version.version }}/change-data-capture-overview.md %}) performance by indicating that a schema change is not currently ongoing. | `off` | Yes | Yes |
 | <a id="database"></a> `database` | The [current database]({% link {{ page.version.version }}/sql-name-resolution.md %}#current-database). | Database in connection string, or empty if not specified. | Yes | Yes |
 | <a id="datestyle"></a> `datestyle` | The input string format for [`DATE`]({% link {{ page.version.version }}/date.md %}) and [`TIMESTAMP`]({% link {{ page.version.version }}/timestamp.md %}) values. Accepted values include `ISO,MDY`, `ISO,DMY`, and `ISO,YMD`. | The value set by the `sql.defaults.datestyle` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) (`ISO,MDY`, by default). | Yes | Yes |
 | <a id="default-int-size"></a> `default_int_size` | The size, in bytes, of an [`INT`]({% link {{ page.version.version }}/int.md %}) type. | `8` | Yes | Yes |