v23.1.5

[szphie]

Breaking changes to 22.2:

https://www.cockroachlabs.com/docs/releases/v23.1#v23-1-0-backward-incompatible-changes

TL;DR:

• big changes to CDC, changefeeds, storage ranges

Full changes:

• Schema names in the search_path session variable now respect case and must be delimited with double quotation marks. Previously, if a search_path was specified in the connection string parameters, it would be treated case insensitive by default.
• Replaced the cdc_prev() function in favor of a cdc_prev tuple. This is an incompatible change that may break changefeeds that use the previous cdc_prev() function. #85177
• SHOW RANGES FOR TABLE now includes rows for all indexes that support the table. Prior to this change, SHOW RANGES FOR TABLE foo was an alias for SHOW RANGES FOR INDEX foo@primary. This was causing confusion, as it would miss data for secondary indexes. It is still possible to filter to just the primary index using SHOW RANGES FOR INDEX foo@primary. The statement output now also includes the index name. #93545
• CockroachDB now supports sharing storage ranges across multiple indexes/tables. This behavior is not enabled by default in v23.1, but will be enabled by default in a future release. When the behavior is enabled, there will no longer be a guarantee that there is at most one SQL object (e.g., table/index/sequence/materialized view) per storage range. As a result, the columns table_id, database_name, schema_name, table_name and index_name in crdb_internal.ranges and .ranges_no_leases will become meaningless, since a range will no longer be attributed to a single table/index. In v23.1, the default behavior of SHOW RANGES is retained, but you should consider setting the sql.show_ranges_deprecated_behavior.enabled cluster setting to false. This will have the following effects that will become the defaults in a future release:
  • The aforementioned columns in the crdb_internal virtual tables will be removed. Existing code can use the updated output of the SHOW RANGES statement instead, optionally using WITH KEYS to expose the raw start/end
  • SHOW RANGES FROM DATABASE continues to report one row per range, but stops returning the database / schema / table / index name.
  • SHOW RANGES FROM TABLE continues to report one row per range, but stops returning the index name. Suggested replacements:
    • Instead of: SELECT range_id FROM crdb_internal.ranges WHERE table_name = 'x', use: SELECT range_id FROM [SHOW RANGES FROM TABLE x]
    • Instead of SELECT range_id FROM crdb_internal.ranges WHERE table_name = $1 OR table_id = $2 (variable / unpredictable table name or ID), use: SELECT range_id FROM [SHOW RANGES FROM CURRENT_CATALOG WITH TABLES] WHERE table_name = $1 OR table_id = $2
    • Instead of SELECT start_key FROM crdb_internal.ranges WHERE table_name = 'x', use: SELECT raw_start_key FROM [SHOW RANGES FROM TABLE x WITH KEYS]
    • Instead of SELECT start_key FROM crdb_internal.ranges WHERE table_name = $1 OR table_id = $2 (unpredictable / variable table name or ID), use: SELECT raw_start_key FROM [SHOW RANGES FROM CURRENT_CATALOG WITH TABLES, KEYS] WHERE table_name = $1 OR table_id = $2 #93644
• When the cluster setting sql.show_ranges_deprecated_behavior.enabled is set to false (recommended in v23.1), the format of the columns start_key and end_key for SHOW RANGES FROM DATABASE and SHOW RANGES FROM TABLE have been extended to include which table/index the key belongs to. This is necessary because a range can now contain data from more than one table/index. #93644
• When the cluster setting sql.show_ranges_deprecated_behavior.enabled is set to false (recommended in v23.1), the output of SHOW RANGES no longer includes range_size, range_size_mb, lease_holder, or lease_holder_localities by default. This ensures that SHOW RANGES remains fast in the common case. Use the new option WITH DETAILS to include these columns. #93644
• The format of the columns start_key and end_key for SHOW RANGE ... FOR ROW has been changed to be consistent with the output of SHOW RANGES FROM INDEX. #93644
• If a SQL database is created with a name that starts with cluster:... (e.g., CREATE DATABASE "cluster:foo", clients will no longer be able to connect to it directly via a pre-existing URL connection string. The URL will need to be modified in this case. For example:
  • Previously: postgres://servername/cluster:foo; now: postgres://servername/cluster:foo?options=-ccluster=system
    This syntax selects the tenant named system and then the database named cluster:foo inside it. When the -ccluster:system option is not specified, cluster:foo in the database name position is interpreted as a request to connect to a tenant named foo, which likely does not exist. Connections to databases whose name does not start with cluster: (the most common case) are not affected by this change. #92580
• Changefeeds using "preview" expressions (released in v23.1.0) and that access the previous state of the row using the cdc_prev() function will no longer work and will need to be recreated with new syntax. #94429
• Some of the transformations specific to changefeeds have been deprecated and replaced. These functions were released in limited access in v22.2. Deprecated changefeed transformations continue to function. Closely monitor changefeeds that are created during upgrade. While effort was made to maintain backward compatibility, the updated changefeed transformation may produce slightly different output, such as different column names. #96295
• Fixed a bug where, when server.identity_map.configuration was used, CockroachDB did not verify the client-provided username against the target mappings. Note that this means that the client must now provide a valid DB username. This requirement is compatible with PostgreSQL; it was not previously required by CockroachDB but it is now. This does not apply when identity maps are not in use. #94915
• Previously, the type of the replicas, voting_replicas,non_voting_replicas and learner_replicas in crdb_internal.ranges were overridden to INT2VECTOR causing incompatible indexing between .ranges and .ranges_no_leases. Now the types of those columns in the two tables are set to INT[]. #96287
• The output of the SHOW RANGES command for the crdb_internal.ranges and crdb_internal.ranges_no_leases tables has been updated, and the previous output is deprecated. To enable the new command output, set the sql.show_ranges_deprecated_behavior.enabled cluster setting to false. The new output will become default in v23.2. #99618
• Previously, if a user specified a search_path in the connection string parameters, it would always be treated as case sensitive. Now, in order to have the schema names in the search_path respect case, the user must include double quotes around the name. #101492
• The deprecated CLI command debug unsafe-remove-dead-replicas has been removed. Use debug recover instead. #89150