release-23.1: sql: backward-compatibility for SHOW RANGES / crdb_internal.ranges #99618
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![blathers-crl[bot]](https://avatars.githubusercontent.com/in/59700?s=60&v=4){kind=small}
This change introduces a new stage during planning, which upon encountering a planning error adds additional user-facing hints to the error payload. We will be able to extend this over time to make suggestions on how to enhance a query to avoid error. As an example application, this change enhances errors about now-removed columns in `crdb_internal.ranges`, `ranges_no_leases` and the output of `SHOW RANGES`. For example: ``` demo@127.0.0.1:26257/movr> select lease_holder from [show ranges from table users]; ERROR: column "lease_holder" does not exist SQLSTATE: 42703 HINT: To list lease holder and range size details, consider SHOW RANGES WITH DETAILS. -- There are more SHOW RANGES options. Refer to the online documentation or execute 'SHOW RANGES ??' for details. ``` ``` demo@127.0.0.1:26257/movr> select database_name,table_name from crdb_internal.ranges; ERROR: column "database_name" does not exist SQLSTATE: 42703 DETAIL: SELECT database_name, table_name FROM crdb_internal.ranges HINT: To list all ranges across all databases and display the database name, consider SHOW CLUSTER RANGES WITH TABLES. -- There are more SHOW RANGES options. Refer to the online documentation or execute 'SHOW RANGES ??' for details. ``` Release note: None
…eases}`
TLDR: the pre-v23.1 behavior of SHOW RANGES and
`crdb_internal.ranges{_no_leases}` is made available conditional on a
new cluster setting `sql.show_ranges_deprecated_behavior.enabled`.
It is set to true by default in v23.1, however any use of the feature
will prompt a SQL notice with the following message:
```
NOTICE: attention! the pre-23.1 behavior of SHOW RANGES and crdb_internal.ranges{,_no_leases} is deprecated!
HINT: Consider enabling the new functionality by setting 'sql.show_ranges_deprecated_behavior.enabled' to 'false'.
The new SHOW RANGES statement has more options. Refer to the online
documentation or execute 'SHOW RANGES ??' for details.
```
The deprecated behavior is also disabled in the test suite and in
`cockroach demo`, i.e. the tests continue to exercise the new
behavior.
cf. doc for new package `deprecatedshowranges`:
```
// Package deprecatedshowranges exists to smoothen the transition
// between the pre-v23.1 semantics of SHOW RANGES and
// crdb_internal.ranges{_no_leases}, and the new semantics introduced
// in v23.1.
//
// The pre-v23.1 semantics are deprecated as of v23.1. At the end of
// the deprecation cycle (hopefully for v23.2) we expect to delete
// this package entirely and all the other code in the SQL layer that
// hangs off the EnableDeprecatedBehavior() conditional defined below.
//
// The mechanism to control the behavior is as follows:
//
// - In any case, an operator can override the behavior using an env
// var, "COCKROACH_FORCE_DEPRECATED_SHOW_RANGE_BEHAVIOR".
// If set (to a boolean), the value of the env var is used in
// all cases.
// We use this env var to force the _new_ behavior through out
// test suite, regardless of the other conditions. This allows
// us to avoid maintaining two sets of outputs in tests.
//
// - If the env var is not set, the cluster setting
// `sql.show_ranges_deprecated_behavior.enabled` is used. It
// defaults to true in v23.1 (the "smoothening" part).
//
// - If the deprecated behavior is chosen by any of the above
// mechanisms, and _the range coalescing cluster setting_ is set
// to true, a loud warning will be reported in various places.
// This will nudge users who wish to opt into range coalescing
// to adapt their use of the range inspection accordingly.
```
Release note (backward-incompatible change): The pre-v23.1 output
produced by `SHOW RANGES`, `crdb_internal.ranges`,
`crdb_internal.ranges_no_leases` is deprecated. The new interface and
functionality for `SHOW RANGES` can be enabled by changing the cluster
setting `sql.show_ranges_deprecated_behavior.enabled` to `false`. It
will become default in v23.2.
blathers-crl
bot
force-pushed
the
blathers/backport-release-23.1-98979
branch
from
b970815
to
ff48287
Compare
blathers-crl
bot
force-pushed
the
blathers/backport-release-23.1-98979
branch
from
84e5fb0
to
89d69ef
Compare
blathers-crl
bot
requested review from
herkolategan and
renatolabs
and removed request for
a team
blathers-crl
bot
force-pushed
the
blathers/backport-release-23.1-98979
branch
from
ff48287
to
e5ab27c
Compare
|
Thanks for opening a backport. Please check the backport criteria before merging:
If some of the basic criteria cannot be satisfied, ensure that the exceptional criteria are satisfied within.
Add a brief release justification to the body of your PR to justify this backport. Some other things to consider:
|
blathers-crl
bot
added
blathers-backport
|
This change is |
knz
requested review from
fqazi and
nvanbenschoten
and removed request for
a team,
herkolategan,
renatolabs,
cucaroach,
fqazi and
irfansharif
nvanbenschoten
approved these changes
Mar 28, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Backport 2/2 commits from #98979 on behalf of @knz.
/cc @cockroachdb/release
Requested by @mwang1026 and @nvanbenschoten .
Fixes #97861.
Fixes #99073.
Needed for #98820.
Epic: CRDB-24928
See the individual commits for details; exceprt from the 2nd commit:
TLDR: the pre-v23.1 behavior of SHOW RANGES and
crdb_internal.ranges{_no_leases}is made available conditional on anew cluster setting
sql.show_ranges_deprecated_behavior.enabled.It is set to true by default in v23.1, however any use of the feature
will prompt a SQL notice with the following message:
The deprecated behavior is also disabled in the test suite and by default in
cockroach demo, i.e. the tests continue to exercise the newbehavior.
Release note (backward-incompatible change): The pre-v23.1 output
produced by
SHOW RANGES,crdb_internal.ranges,crdb_internal.ranges_no_leasesis deprecated. The new interface andfunctionality for
SHWO RANGEScan be enabled by changing the clustersetting
sql.show_ranges_deprecated_behavior.enabledtofalse. Itwill become default in v23.2.
Release justification: prevents regression, introduces a deprecation notice