Skip to content

Remove mention of 'declarative' schema changer' #19443

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ During a major-version upgrade, certain features and performance improvements ma

- A cluster must have an [Enterprise license]({% link v25.1/licensing-faqs.md %}#set-a-license) or a [trial license]({% link v25.1/licensing-faqs.md %}#obtain-a-license) set before an upgrade to v25.1 can be finalized.
- Support for XA transactions, which allow CockroachDB to participate in distributed transactions with other resources (e.g. databases or message queues) using a two-phase commit protocol. [#129448](https://github.com/cockroachdb/cockroach/pull/129448)
- [`ALTER TABLE ... ALTER COLUMN TYPE`]({% link v25.1/alter-table.md %}#alter-column-data-types) is in [General Availability (GA)]({% link v25.1/cockroachdb-feature-availability.md %}#feature-availability-phases) and takes advantage of the logic in the [declarative schema changer]({% link v25.1/online-schema-changes.md %}#declarative-schema-changer).
- [`ALTER TABLE ... ALTER COLUMN TYPE`]({% link v25.1/alter-table.md %}#alter-column-data-types) is in [General Availability (GA)]({% link v25.1/cockroachdb-feature-availability.md %}#feature-availability-phases).
- Jobs system changes:
- `SHOW JOBS` is now based on a new mechanism for storing information about the progress and status of running jobs. [#139230](https://github.com/cockroachdb/cockroach/pull/139230)
- `ALTER JOB ... OWNER TO` can now be used to transfer ownership of a job between users/roles. [#138139](https://github.com/cockroachdb/cockroach/pull/138139)
Expand Down

This file was deleted.

2 changes: 1 addition & 1 deletion src/current/_includes/v25.1/misc/session-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@
| <a id="transaction-status"></a> `transaction_status` | The state of the current transaction. See [Transactions]({% link {{ page.version.version }}/transactions.md %}) for more details. | `NoTxn` | No | Yes |
| <a id="transaction-timeout"></a> `transaction_timeout` | Aborts an explicit [transaction]({% link {{ page.version.version }}/transactions.md %}) when it runs longer than the configured duration. Stored in milliseconds; can be expressed in milliseconds or as an [`INTERVAL`]({% link {{ page.version.version }}/interval.md %}). | `0` | Yes | Yes |
| <a id="troubleshooting_mode_enabled"></a> `troubleshooting_mode_enabled` | When enabled, avoid performing additional work on queries, such as collecting and emitting telemetry data. This session variable is particularly useful when the cluster is experiencing issues, unavailability, or failure. | `off` | Yes | Yes |
| <a id="use_declarative_schema_changer"></a> `use_declarative_schema_changer` | Whether to use the declarative schema changer for supported statements. See [Declarative schema changer]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer) for more details. | `on` | Yes | Yes |
| <a id="use_declarative_schema_changer"></a> `use_declarative_schema_changer` | Whether to use the declarative schema changer for supported statements. | `on` | Yes | Yes |
| <a id="vectorize"></a> `vectorize` | The vectorized execution engine mode. Options include `on` and `off`. For more details, see [Configure vectorized execution for CockroachDB]({% link {{ page.version.version }}/vectorized-execution.md %}#configure-vectorized-execution). | `on` | Yes | Yes |
| <a id="virtual_cluster_name"></a> `virtual_cluster_name` | The name of the virtual cluster that the SQL client is connected to. | Session-dependent | No | Yes |

Expand Down
2 changes: 1 addition & 1 deletion src/current/v25.1/changefeed-best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ The key areas to monitor when running changefeeds:

## Manage changefeeds and schema changes

When a schema change is issued that causes a column backfill, it can result in a changefeed emitting [duplicate messages]({% link {{ page.version.version }}/changefeed-messages.md %}#schema-changes-with-column-backfill) for an event. We recommend issuing schema changes **outside of explicit transactions** to make use of the declarative schema changer, which does not perform column backfill for the [schema changes it supports]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer). For more details on schema changes and column backfill generally, refer to the [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %}) page.
When a schema change is issued that causes a column backfill, it can result in a changefeed emitting [duplicate messages]({% link {{ page.version.version }}/changefeed-messages.md %}#schema-changes-with-column-backfill) for an event. We recommend issuing schema changes **outside of explicit transactions**. For more details on schema changes and column backfill generally, refer to the [Online Schema Changes]({% link {{ page.version.version }}/online-schema-changes.md %}) page.

You can also use the [`schema_change_events`]({% link {{ page.version.version }}/create-changefeed.md %}#schema-change-events) and [`schema_change_policy`]({% link {{ page.version.version }}/create-changefeed.md %}#schema-change-policy) options to define a schema change type and an associated policy that will modify how the changefeed behaves under the schema change.

Expand Down
8 changes: 2 additions & 6 deletions src/current/v25.1/changefeed-messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -422,7 +422,7 @@ The `min_checkpoint_frequency` option controls how often nodes flush their progr

## Schema Changes

In v22.1, CockroachDB introduced the [declarative schema changer]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer). When schema changes happen that use the declarative schema changer by default, changefeeds will **not** emit duplicate records for the table that is being altered. It will only emit a copy of the table using the new schema. Refer to [Schema changes with column backfill](#schema-changes-with-column-backfill) for examples of this.
For some schema changes, changefeeds will **not** emit duplicate records for the table that is being altered. Instead, the changefeed will only emit a copy of the table using the new schema. Refer to [Schema changes with column backfill](#schema-changes-with-column-backfill) for examples of this.

### Avro schema changes

Expand All @@ -438,10 +438,6 @@ Schema validation tools should ignore the `__crdb__` field. This is an internal

When schema changes with column backfill (e.g., adding a column with a default, adding a [stored computed column]({% link {{ page.version.version }}/computed-columns.md %}), adding a `NOT NULL` column, dropping a column) are made to watched rows, CockroachDB emits a copy of the table using the new schema.

{{site.data.alerts.callout_info}}
Schema changes that do **not** use the declarative schema changer by default will trigger a changefeed to emit a copy of the table being altered as well as a copy of the table using the new schema. For a list of supported schema changes, refer to the [Declarative schema changer]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer) section.
{{site.data.alerts.end}}

The following example demonstrates the messages you will receive after creating a changefeed and then applying a schema change to the watched table:

{% include_cached copy-clipboard.html %}
Expand Down Expand Up @@ -488,7 +484,7 @@ After the schema change, the changefeed will emit a copy of the table with the n
[3] {"id": 3, "likes_treats": true, "name": "Ernie"}
~~~

If the schema change does **not** use the declarative schema changer by default, the changefeed will emit a copy of the altered table and a copy of the table using the new schema:
For some schema changes, the changefeed will emit a copy of the altered table and a copy of the table using the new schema:

~~~json
[1] {"id": 1, "name": "Petee H"}
Expand Down
2 changes: 0 additions & 2 deletions src/current/v25.1/drop-database.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ The `DROP DATABASE` [statement]({% link {{ page.version.version }}/sql-statement

{% include {{ page.version.version }}/misc/schema-change-stmt-note.md %}

{% include {{ page.version.version }}/misc/declarative-schema-changer-note.md %}

## Required privileges

The user must have the `DROP` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the database and on all tables in the database.
Expand Down
2 changes: 0 additions & 2 deletions src/current/v25.1/drop-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ The `DROP SCHEMA` [statement]({% link {{ page.version.version }}/sql-statements.

{% include {{ page.version.version }}/misc/schema-change-stmt-note.md %}

{% include {{ page.version.version }}/misc/declarative-schema-changer-note.md %}

## Required privileges

The user must have the `DROP` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the schema and on all tables in the schema. If the user is the owner of the schema, `DROP` privileges are not necessary.
Expand Down
2 changes: 0 additions & 2 deletions src/current/v25.1/drop-table.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ The `DROP TABLE` [statement]({% link {{ page.version.version }}/sql-statements.m

{% include {{ page.version.version }}/misc/schema-change-stmt-note.md %}

{% include {{ page.version.version }}/misc/declarative-schema-changer-note.md %}

## Required privileges

The user must have the `DROP` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the specified table(s). If `CASCADE` is used, the user must have the privileges required to drop each dependent object as well.
Expand Down
2 changes: 0 additions & 2 deletions src/current/v25.1/drop-type.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ The `DROP TYPE` [statement]({% link {{ page.version.version }}/sql-statements.md

{% include {{ page.version.version }}/misc/schema-change-stmt-note.md %}

{% include {{ page.version.version }}/misc/declarative-schema-changer-note.md %}

## Synopsis

<div>
Expand Down
4 changes: 0 additions & 4 deletions src/current/v25.1/known-limitations.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,10 +217,6 @@ See: https://go.crdb.dev/issue-v/42508/v24.2

{% include {{ page.version.version }}/known-limitations/schema-changes-between-prepared-statements.md %}

#### Declarative schema changer does not track rows in `system.privileges`

The [declarative schema changer]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer) does not track rows in the `system.privileges` table, which prevents the declarative schema changer from successfully running the [`DROP OWNED BY`]({% link {{ page.version.version }}/drop-owned-by.md %}) statement. [#88149](https://github.com/cockroachdb/cockroach/issues/88149)

#### New values generated by `DEFAULT` expressions during `ALTER TABLE ADD COLUMN`

When executing an [`ALTER TABLE ADD COLUMN`]({% link {{ page.version.version }}/alter-table.md %}#add-column) statement with a [`DEFAULT`]({% link {{ page.version.version }}/default-value.md %}) expression, new values generated:
Expand Down
29 changes: 0 additions & 29 deletions src/current/v25.1/online-schema-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,35 +62,6 @@ If a schema change fails, the schema change job will be cleaned up automatically

For advice about how to avoid running out of space during an online schema change, refer to [Estimate your storage capacity before performing online schema changes](#estimate-your-storage-capacity-before-performing-online-schema-changes).

## Declarative schema changer

CockroachDB only guarantees atomicity for schema changes within single statement transactions, either implicit transactions or in an explicit transaction with a single schema change statement. The declarative schema changer is the next iteration of how schema changes will be performed in CockroachDB. By planning schema change operations in a more principled manner, the declarative schema changer will ultimately make transactional schema changes possible. You can identify jobs that are using the declarative schema changer by running [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %}) and finding jobs with a `job_type` of `NEW SCHEMA CHANGE`.

The following statements use the declarative schema changer by default:

- [`DROP DATABASE`]({% link {{ page.version.version }}/drop-database.md %})
- [`DROP SCHEMA`]({% link {{ page.version.version }}/drop-schema.md %})
- [`DROP TABLE`]({% link {{ page.version.version }}/drop-table.md %})
- [`DROP TYPE`]({% link {{ page.version.version }}/drop-type.md %})
- [`CREATE FUNCTION`]({% link {{ page.version.version }}/create-function.md %})
- [`DROP FUNCTION`]({% link {{ page.version.version }}/drop-function.md %})
- [`ALTER TABLE ... ADD CONSTRAINT ... CHECK`]({% link {{ page.version.version }}/alter-table.md %}#add-constraint)
- [`ALTER TABLE ... ADD CONSTRAINT ... CHECK ... NOT VALID`]({% link {{ page.version.version }}/alter-table.md %}#add-constraint)
- [`ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY`]({% link {{ page.version.version }}/alter-table.md %}#add-constraint)
- [`ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY ... NOT VALID`]({% link {{ page.version.version }}/alter-table.md %}#add-constraint)
- [`ALTER TABLE ... VALIDATE CONSTRAINT`]({% link {{ page.version.version }}/alter-table.md %}#drop-constraint)
- [`ALTER TABLE ... DROP CONSTRAINT`]({% link {{ page.version.version }}/alter-table.md %}#validate-constraint)
- [`ALTER TABLE ... ALTER COLUMN TYPE`]({% link {{ page.version.version }}/alter-table.md %}#alter-column-data-types)
- [`CREATE SEQUENCE`]({% link {{page.version.version}}/create-sequence.md %})

Until all schema change statements are moved to use the declarative schema changer you can enable and disable the declarative schema changer for supported statements using the `sql.defaults.use_declarative_schema_changer` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-defaults-use-declarative-schema-changer) and the `use_declarative_schema_changer` [session variable]({% link {{ page.version.version }}/set-vars.md %}#use_declarative_schema_changer).

{{site.data.alerts.callout_danger}}
Declarative schema changer statements and legacy schema changer statements operating on the same objects cannot exist within the same transaction. Either split the transaction into multiple transactions, or disable the cluster setting or session variable.
{{site.data.alerts.end}}

{% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %}

## Best practices for online schema changes

### Estimate your storage capacity before performing online schema changes
Expand Down
2 changes: 1 addition & 1 deletion src/current/v25.1/show-jobs.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ The following fields are returned for each job:
Field | Description
------|------------
`job_id` | A unique ID to identify each job. This value is used if you want to control jobs (i.e., [pause]({% link {{ page.version.version }}/pause-job.md %}), [resume]({% link {{ page.version.version }}/resume-job.md %}), or [cancel]({% link {{ page.version.version }}/cancel-job.md %}) it).
`job_type` | The type of job: [`SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`NEW SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}#declarative-schema-changer), [`KEY VISUALIZER`]({% link {{ page.version.version }}/ui-key-visualizer.md %}), [`MIGRATION`]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#overview), [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), [`IMPORT`]({% link {{ page.version.version }}/import-into.md %}), [`CHANGEFEED`](#show-changefeed-jobs), [`CREATE STATS`]({% link {{ page.version.version }}/create-statistics.md %}), [`ROW LEVEL TTL`]({% link {{ page.version.version }}/row-level-ttl.md %}), [`REPLICATION STREAM INGESTION`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}), `REPLICATION STREAM PRODUCER`([physical cluster replication]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}) or [logical data replication]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %})), [`LOGICAL REPLICATION`]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %}). <br><br>For job types of automatic jobs, see [Show automatic jobs](#show-automatic-jobs).
`job_type` | The type of job: [`SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`NEW SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`KEY VISUALIZER`]({% link {{ page.version.version }}/ui-key-visualizer.md %}), [`MIGRATION`]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#overview), [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), [`IMPORT`]({% link {{ page.version.version }}/import-into.md %}), [`CHANGEFEED`](#show-changefeed-jobs), [`CREATE STATS`]({% link {{ page.version.version }}/create-statistics.md %}), [`ROW LEVEL TTL`]({% link {{ page.version.version }}/row-level-ttl.md %}), [`REPLICATION STREAM INGESTION`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}), `REPLICATION STREAM PRODUCER`([physical cluster replication]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}) or [logical data replication]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %})), [`LOGICAL REPLICATION`]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %}). <br><br>For job types of automatic jobs, see [Show automatic jobs](#show-automatic-jobs).
`description` | The statement that started the job, or a textual description of the job. When you run `SHOW JOBS`, the `description` field is limited to 100 characters. To view the full description for a job, run `SHOW JOB {job ID}`.
`statement` | When `description` is a textual description of the job, the statement that started the job is returned in this column. Currently, this field is populated only for the automatic table statistics jobs.
`user_name` | The name of the [user]({% link {{ page.version.version }}/security-reference/authorization.md %}#create-and-manage-users) who started the job.
Expand Down
Loading