Skip to content

Commit dd116b4

Browse files
committed
Update schema changes docs with schema_locked info
Fixes DOC-15240 NB. These changes are applied to v25.4 and v26.1
1 parent 684da8c commit dd116b4

4 files changed

Lines changed: 16 additions & 0 deletions

File tree

src/current/v25.4/changefeed-best-practices.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ You can also use the [`schema_change_events`]({% link {{ page.version.version }}
5757

5858
## Lock the schema on changefeed watched tables
5959

60+
To apply `schema_locked` automatically to new tables, set the [`create_table_with_schema_locked` session variable]({% link {{ page.version.version }}/set-vars.md %}#create_table_with_schema_locked).
61+
6062
{% include {{ page.version.version }}/cdc/cdc-schema-locked-example.md %}
6163

6264
## See also

src/current/v25.4/online-schema-changes.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,12 @@ For advice about how to avoid running out of space during an online schema chang
6666

6767
## Best practices for online schema changes
6868

69+
### Improve changefeed performance with `schema_locked`
70+
71+
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.
72+
73+
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.
74+
6975
### Estimate your storage capacity before performing online schema changes
7076

7177
Some schema change operations, like adding or dropping columns or altering primary keys, will temporarily increase a cluster's storage consumption. Specifically, these operations may temporarily require up to three times more storage space for the range size while the schema change is being applied, and this may cause the cluster to run out of storage space or fail to apply the schema change.

src/current/v26.1/changefeed-best-practices.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ You can also use the [`schema_change_events`]({% link {{ page.version.version }}
5757

5858
## Lock the schema on changefeed watched tables
5959

60+
To apply `schema_locked` automatically to new tables, set the [`create_table_with_schema_locked` session variable]({% link {{ page.version.version }}/set-vars.md %}#create_table_with_schema_locked). In CockroachDB v26.1 and later, it defaults to `on`.
61+
6062
{% include {{ page.version.version }}/cdc/cdc-schema-locked-example.md %}
6163

6264
## See also

src/current/v26.1/online-schema-changes.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,12 @@ For advice about how to avoid running out of space during an online schema chang
6666

6767
## Best practices for online schema changes
6868

69+
### Improve changefeed performance with `schema_locked`
70+
71+
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.
72+
73+
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.
74+
6975
### Estimate your storage capacity before performing online schema changes
7076

7177
Some schema change operations, like adding or dropping columns or altering primary keys, will temporarily increase a cluster's storage consumption. Specifically, these operations may temporarily require up to three times more storage space for the range size while the schema change is being applied, and this may cause the cluster to run out of storage space or fail to apply the schema change.

0 commit comments

Comments
 (0)