What's New in v21.1

Docker image

To download the Docker image (Intel-only):

docker pull cockroachdb/cockroach-unstable:v21.1.0-alpha.2

Changelog

View a detailed changelog on GitHub: v21.1.0-alpha.1...v21.1.0-alpha.2

Backward-incompatible changes

• The payload fields for certain event types in system.eventlog have been changed and/or renamed. Note that the payloads in system.eventlog were an undocumented, reserved feature so no guarantee was made about cross-version compatibility to this point. The list of changes includes (but is not limited to):
  • TargetID has been renamed to NodeID for node_join.
  • TargetID has been renamed to TargetNodeID for node_decommissioning / node_decommissioned / node_recommissioned.
  • NewDatabaseName has been renamed to NewDatabaseParent for convert_to_schema.
  • grant_privilege and revoke_privilege have been removed; they are replaced by change_database_privilege, change_schema_privilege, change_type_privilege, and change_table_privilege. Each event only reports a change for one user/role, so the Grantees field was renamed to Grantee.
  • Each drop_role event now pertains to a single user/role. #57737
• The connection and authentication logging enabled by the cluster settings server.auth_log.sql_connections.enabled and server.auth_log.sql_sessions.enabled was previously using a text format which was hard to parse and integrate with external monitoring tools. This has been changed to use the standard notable event mechanism, with standardized payloads. The output format is now structured; see the generated reference documentation for details about the supported event types and payloads. #57839
• The logging format for SQL audit, execution, and query logs has changed from a crude space-delimited format to JSON. To opt out of this new behavior and restore the pre-v21.1 logging format, you can set the cluster setting sql.log.unstructured_entries.enabled to true. #59110

Security updates

• The entropy of the auto-generated user account password for cockroach demo shell has been lowered, to ensure that the passwords are short and easy to copy over. This makes the password easy to brute-force and thus removes any remaining protection there may have been to the confidentiality of demo sessions. (The reason why a password remains, as opposed to no password whatsoever, is to prevent accidental misuse of the HTTP service by other applications running on the same machine.) Since the required shortness erases any pretense of security, the algorithm has been simplified to remove usage of a cryptographic PRNG altogether. #58305
• When using a SQL proxy, by default CockroachDB only knows about the network address of the proxy. That peer address is then used for logging, authentication rules, etc. This is undesirable, as security logging and authentication rules need to operate on the actual (final) client address instead. CockroachDB can now be configured to solve this problem (conf mechanism detailed below). When so configured, a SQL proxy can inform the CockroachDB server of the real address of the client via a server status parameter called crdb:remote_addr. The value must be the IP address of the client, followed by a colon, followed by the port number, using the standard Go syntax (e.g., 11.22.33.44:5566 for IPv4, [11:22::33]:4455 for IPv6). When provided, this value overrides the SQL proxy's address for logging and authentication purposes. In any case, the original peer address is also logged alongside the client address (overridden or not), via the new logging tag peer. Security considerations:
  • Enabling this feature allows the peer to spoof its address with regard to authentication and thus bypass authentication rules that would otherwise apply to its address, which can introduce a serious security vulnerability if the peer is not trusted. This is why this feature is not enabled by default, and must only be enabled when using a trusted SQL proxy.
  • This feature should only be used with SQL proxies which actively scrub a crdb:remote_addr parameter received by a remote client, and replaces it by its own. If the proxy mistakenly forwards the parameter as provided by the client, it opens the door to the aforementioned security vulnerability.
  • Care must be taken in host-based authentication (HBA) rules:
  • TLS client cert validation, if requested by a rule, is still performed using the certificate presented by the proxy, not that presented by the client. This means that this new feature is not sufficient to forward TLS client cert authentication through a proxy. (If TLS client cert authentication is required, it must be performed by the proxy directly.)
  • The protocol field (first column) continues to apply to the connection type between CockroachDB and the proxy, not between the proxy and the client. Only the 4th column (the CIDR pattern) is matched against the proxy-provided remote address override. Therefore, it is not possible to apply different rules to different client address when proxying TCP connections via a unix socket, because HBA rules for unix connections do not use the address column. Also when proxying client SSL connections via a non-SSL proxy connection, or proxying client non-SSL connections via a SSL proxy connection, care must be taken to configure address-based rule matching using the proper connection type. A reliable way to bypass this complexity is to only use the host connection type which applies equally to SSL and non-SSL connections. As of this implementation, the feature is enabled using the non-documented environment variable COCKROACH_TRUST_CLIENT_PROVIDED_SQL_REMOTE_ADDR. The use of an environment variable is a stop-gap so that this feature can be used in CockroachCloud SQL pods, which do not have access to cluster settings. The environment variable will be eventually removed and replaced by another mechanism. #58381
• Added ability to set region-specific callback URLs in the OIDC config. The server.oidc_authentication.redirect_url cluster setting can now accept JSON as an alternative to the basic URL string setting. If a JSON value is set, it must contain a redirect_url key that maps to an object with key-value pairs where the key is a region matching an existing locality setting and the value is a callback URL. #57519

General changes

• CockroachDB now runs fewer threads in parallel if running inside a container with a CPU limit. #57390
• Upgraded the CockroachDB binary to Go 1.15.6. #57713
• The new cluster setting server.eventlog.enabled controls whether notable events are also written to the table system.eventlog. Its default value is true. Changing this cluster setting can help recovering partial cluster availability when the system.eventlog table becomes unavailable. Note that even when false, notable events are still propagated to the logging system, where they can be redirected to files or other log sinks. #57879
• Moved RBAC resources in Kubernetes manifests to rbac.authorization.k8s.io/v1. #55065
• Cluster version upgrades, as initiated by SET CLUSTER SETTING version = <major>-<minor>, now perform internal maintenance duties that will increase the time that it takes for the command to complete. This delay is proportional to the amount of data currently stored in the cluster. The cluster will also experience a small amount of additional load during this period while the upgrade is being finalized. These changes expand upon our original prototype in #57445. #58088
• Upgraded to v3.9.2 of protobuf to consume new changes for Bazel. #58891
• Increased the default value of sql.tablecache.lease.refresh_limit to 500 in order to accommodate larger schemas without encountering RETRY_COMMIT_DEADLINE_EXCEEDED errors and generally higher latency. #59319

Enterprise edition changes

• CockroachDB now permits partitioning by user-defined types such as enums. #57327

SQL language changes

• Added a new built-in method to calculate Voronoi polygons. #56496
• Added a new built-in method to calculate Voronoi lines. #56496
• Previously, timezones had to be entered in the same case as they were stored on the system. Now, timezone names can be case-insensitive provided they match well-known zone names according to Go's time/tzdata package. #57250
• Added LOCALITY REGIONAL BY TABLE IN PRIMARY REGION syntax for configuring table locality. #57275
• The default value for vectorize_row_count_threshold setting has been decreased from 1000 to 0, meaning that, by default, CockroachDB will always use the vectorized engine for all supported queries regardless of the row estimate (unless vectorize=off is set). #55713
• Added the ability to CREATE TABLE with LOCALITY set. #57419
• EXPLAIN and EXPLAIN ANALYZE now show counts and durations in a more user-friendly way. #57420
• EXPORT can now be used by non-admin users with SELECT privilege on the table being exported, unless the destination URI requires admin privileges. #57380
• CREATE DATABASE ... WITH [PRIMARY] REGIONS now modifies the zone configurations with the settings as set by the multiregion configuration. #57244
• SHOW [BACKUP] is no longer admin-only. It depends on the URI construct and the credentials specified in the SHOW [BACKUP] query. #57412
• built-in aggregate function regr_avgx is now supported. #57295
• Added support for running IMPORT in a mixed-version cluster. #57382
• Introduced SHOW REGIONS FROM ALL DATABASES, which shows region metadata for each database in the table. #57500
• Added collations table to the information_schema. The collations table contains the collations available in the current database. #57609
• Added collation_character_set_applicability table to the information_schema. #57609
• LOCALITY directives on CREATE TABLE are now persisted onto the database. #57513
• Multi-region defined table localities now display on the SHOW CREATE TABLE command. #57513
• Arrays in pg_catalog tables now are displayed in a format that matches PostgreSQL. #56980
• The SET TRACING local option (to only trace messages issued by the local node) was removed. #57567
• Several SHOW commands have been adjusted to enforce a particular ordering of the output rows. #57644
• Implemented regr_avgy built-in aggregation function. #57583
• crdb_internal.tables and SHOW TABLES now show locality data on the tables. #57653
• CREATE TABLE ... LOCALITY ... statements now modify the zone configurations to be in line with the desired locality. #57654
• Added sql.trace.stmt.enable_thresold. Similar to sql.trace.txn.enable_threshold, this logs a trace of any statements that take longer than the specified duration. This new setting allows for more granularity than the transaction threshold since it applies to individual statements and does not include overhead such as communication with a SQL client. #57733
• Added a session setting experimental_enable_unique_without_index_constraints and cluster default sql.defaults.experimental_enable_unique_without_index_constraints.enabled to enable the use of UNIQUE WITHOUT INDEX syntax. The default value of both settings is false since this feature is not yet fully supported. Use of UNIQUE WITHOUT INDEX also depends on all nodes being upgraded to the cluster version UniqueWithoutIndexConstraints. #57666
• Implemented built-in function levenshtein. #56843
• Added table-view dependency information in pg_depend to improve compatibility with PostgreSQL. #57240
• The cluster event logging system has been modernized. In particular, the schema of the entries for the info column in system.eventlog has been stabilized. #57737
• The targetID and reportingID columns in system.eventlog are now deprecated. Their values, for relevant event types, can be found as fields inside the info column instead. #57737
• Added the soundex() and difference() built-in functions. #57615
• New EXPLAIN ANALYZE (DISTSQL) output format. EXPLAIN ANALYZE (DISTSQL) now only works as a top-level statement (it can no longer be part of a bigger query). #57804
• Added built-in function ST_OrientedEnvelope to calculate the mimimum-area rotated rectangle. #57697
• A new default_transaction_use_follower_reads session variable is now supported, which configures SQL transactions to perform stale reads from follower replicas. #57851
• Both ALTER TABLE OWNER and REASSIGN OWNED BY now report structured notable events about the ownership changes. Note that REASSIGN OWNED BY currently also reports an alter_table_owner for views and sequences that were implicitly reassigned, even though CockroachDB does not yet support the ALTER VIEW OWNER / ALTER SEQUENCE OWNER statements. #57969
• EXPLAIN (DISTSQL) has a new output schema and format. #57954
• Added an overload to crdb_internal.pb_to_json to suppress populating default values in fields. #58087
• IMPORT INTO for CSV now supports nextval as a default expression of a non-targeted column. #56473
• The EXPLAIN output for foreign key checks is now labeled constraint-check rather than fk-check. This change is in preparation for adding support for unique constraint checks, which will use the same label. #58053
• The error message for unique constraint violations now matches the error used by PostgreSQL. For example, the new error message looks like this: ERROR: duplicate key value violates unique constraint "primary" DETAIL: Key (k)=(1) already exists. #58053
• EXPLAIN ANALYZE diagrams now contain "network hops" information on streams. #58078
• Added support for the IF NOT EXISTS prefix to CREATE TYPE statements. #58173
• Added a session_variables table to the information_schema. The session_variables table exposes the session variables. #57837
• Indexing into scalar JSON values using an integer index is now properly supported. #58359
• The crdb_internal.cluster_id method now returns the ID of the underlying KV cluster in multi-tenant scenarios rather than the Nil UUID. The ClusterID is needed for logging and metrics for SQL tenants. #58317
• SHOW STATEMENTS is now an alias of SHOW QUERIES. The new syntax is preferred by the SQL parser. #58072
• Implemented the gateway_region built-in, which returns the region of the connection's current node. #58423
• BACKUP and RESTORE now use the block-level checksums embedded in their data files instead of collecting / verifying more expensive file-level SHA512 checksums. #58487
• Multi-tenant clusters will now send anonymous usage information to the central CockroachDB registration server. #58399
• Added support for ALTER DATABASE ... ADD REGION. #58233
• Multiple SHOW ZONE CONFIGURATION statements that previously used FOR can now also use FROM (e.g., SHOW ZONE CONFIGURATION FOR RANGE). This change standardizes the use of FROM for SHOW ZONE CONFIGURATION. #58740
• Implemented SHOW REGIONS, which shows a list of regions along with the databases associated with them. #57618
• Added ALTER DATABASE ... PRIMARY REGION. #58725
• Columns implicitly added from hash-sharded indexes will no longer display on pg_index and pg_indexes. #58749
• Added a new implicit column to crdb_internal.index_columns, which signifies whether the column is implicitly added onto the index through PARTITION BY with an implicit column or a hash-sharded index. #58749
• CockroachDB now omits implicit columns or hash-sharded index columns from automatically generated index names. #58898
• Implemented PARTITION ALL BY syntax for CREATE TABLE, which automatically partitions the table, and all indexes, with the same partitioning scheme. #58748
• PARTITION ALL BY tables now display correctly on SHOW CREATE TABLE. #58928
• Creating a table and changing its schema within a transaction no longer schedules a schema change job. #58888
• Implemented geo built-in function ST_GeneratePoints. #58288
• Hash aggregation can now spill to disk when it exhausts its memory limit when executed via the vectorized engine. #57817
• Implemented ALTER DATABASE ... SURVIVE REGION/ZONE FAILURE. #58937
• CREATE INDEX will now inherit PARTITION BY clauses from PARTITION ALL BY tables. #58988
• Implemented the geometry-based built-in functions ST_LineSubstring({geometry,float8,float8}). #58125
• Implemented REGIONAL BY ROW logic on CREATE TABLE. This is gated behind the experimental session variable experimental_enable_implicit_column_partitioning. #58987
• Added support for ALTER VIEW / SEQUENCE OWNER TO commands. #59049
• Casts to type unknown[] are no longer accepted in CockroachDB. Any such casts will fail to parse and return the error ERROR: type "unknown[]" does not exist. This is consistent with PostgreSQL's behavior. #59136
• Implemented REGIONAL BY ROW AS ..., which allows a column of type crdb_internal_region to be used as a column for REGIONAL BY ROW multi-region properties. #59121
• Enabled altering of table locality for tables that are REGIONAL BY TABLE to REGIONAL BY TABLE (but in a different region). #59144
• PARTITION ALL BY statements will now apply for tables when using ALTER PRIMARY KEY. #59178
• Implemented the geometry built-in function ST_ShiftLongitude, which is useful for plotting data on a Pacific-centred map. #59234
• Implemented ALTER TABLE ... SET LOCALITY GLOBAL for tables starting as REGIONAL BY ROW. #59256
• Improved the error message when people use set search_path incorrectly, or with a schema that legitimately has a comma in its name. #53974
• Creation of interleaved tables and indexes is now disabled by default. They can be re-enabled temporarily by running SET CLUSTER SETTING sql.defaults.interleaved_tables.enabled=true. #59248
• CockroachDB now uses a structured logging format for the SQL audit, execution, and query logs. See the generated reference documentation for details. Of note, audit and execution logs now also include information about whether a query plan contains full index scans. Previously, this information was only included in the slow query log. #59110
• CREATE INDEX on REGIONAL BY ROW tables will now correctly include the implicit partitioning and inherit the correct zone configurations. #59223
• Made a minor improvement to EXPLAIN output for "render" node. #59313
• EXPLAIN ANALYZE now defaults to the new EXPLAIN ANALYZE (PLAN), which shows a text representation of the logical plan, annotated with execution statistics. #57337

Command-line changes

• The logging configuration can now be specified via the --log parameter. See the documentation for details. The flags --log-dir, --log-file-max-size, --log-file-verbosity, --log-group-max-size are now deprecated. #57134
• A new command cockroach debug check-log-config prints out the logging configuration that results from the provided combination of --store, --log, and other logging-related flags on the command line. #57134
• The events that were previously only stored in system.eventlog are now also directed unconditionally to an external logging channel using a JSON format. Refer to the configuration to see how to customize how events are directed to external sinks. Note that the exact external output format (and thus how to detect/parse the events from e.g., log files) is not yet stabilized and remains subject to change. #57737
• Notable events that pertain to SQL schema, user, and privilege changes are now sent on the new SQL_SCHEMA, USER_ADMIN, and PRIVILEGES logging channels. These can now be redirected to different sinks from the other log entries.
  • The SQL_SCHEMA channel is used to report changes to the SQL logical schema, excluding privilege and ownership changes (which are reported on the separate channel PRIVILEGES) and zone config changes (which go to OPS). This includes:
    • Database, schema, table, sequence, view, and type creation.
    • Adding, removing, and changing table columns.
    • Changing sequence parameters.
    • More generally, changes to the schema that affect the functional behavior of client apps using stored objects.
  • The USER_ADMIN channel is typically configured in "audit" mode, with event numbering and synchronous writes. It is used to report changes in users and roles, including:
    • Users added and dropped.
    • Changes to authentication credentials, including passwords, validity, etc.
    • Role grants and revocations.
    • Role option grants and revocations.
  • The PRIVILEGES channel is typically configured in "audit" mode, with event numbering and synchronous writes. It is used to report data authorization changes, including:
    • Privilege grants and revocations on database, objects, etc.
    • Object ownership changes. #51987
• Logging events that are relevant to cluster operators are now categorized under the new OPS and HEALTH logging channels. These can now be redirected separately from other logging events.
  • The OPS channel is used to report "point" operational events, initiated by user operators or automation:
    • Operator or system actions on server processes: process starts, stops, shutdowns, and crashes (if they can be logged). Each event includes any command-line parameters and the CockroachDB version.
    • Actions that impact the topology of a cluster: node additions, removals, decommissions, etc.
    • Cluster setting changes
    • Zone configuration changes.
  • The HEALTH channel is the channel used to report "background" operational events, initiated by CockroachDB for reporting on automatic processes:
    • Current resource usage, including critical resource usage.
    • Node-node connection events, including connection errors and gossip details.
    • Range and table leasing events.
    • Up- and down-replication.
    • Range unavailability. #57171
• Server terminations that are triggered when a node encounters an internal fatal error are now reported on the OPS logging channel. The exact text of the error is not reported on the OPS channel, however, as it may be complex (e.g., when there is a replica inconsistency); and the OPS channel is typically monitored by tools that just detect irregularities. The text of the message refers instead to the channel where the additional details can be found. #57171
• The notable events set_zone_config and remove_zone_config are now sent to the OPS logging channel. #57171
• Added a flag to cockroach debug decode-proto to suppress populating default values in fields. #58087
• When a SQL notable (structured) event is logged, the payload now attempts to include the session's application_name as field ApplicationName. This is intended for use when setting up event routing and filtering in external tools. #58130
• It is now possible to set the format parameter of any log sink, including file sinks, to json, json-compact, json-fluent, or json-fluent-compact to write entries as structured JSON. Refer to the generated reference documentation for details. #58126
• The DB Console URL printed by cockroach demo now automatically logs in the user when pasted into a web browser. #56740
• The URLs generated when cockroach demo starts have been made shorter and easier to copy/paste by shortening the generated password. #58305
• When using the JSON output formats for log entries, the server identifiers are now reported as part of each payload once known (either cluster ID + node ID in single-tenant or KV servers, or tenant ID + SQL instance ID in multi-tenant SQL servers). #58128
• Fixed cockroach demo --global from crashing with didn't get expected magic bytes header. #58466
• Previously, for certain log files, CockroachDB would both flush individual writes (i.e., propagate them from within the cockroach process to the OS) and also synchronize writes (i.e., ask the OS to confirm the log data was written to disk). Per-write synchronization was found to be unnecessary and possibly detrimental to performance and operating cost, so it was removed. Now, the log data continues to be flushed, as before, and CockroachDB only requests synchronization periodically (every 30s). #58995
• The parameter sync-writes for file sink configurations has been removed. (This is not a backward-incompatible change because the configuration feature is new in v21.1.) #58995
• The parameter buffered-writes for file sink configurations has been added. It is set to true (writes are buffered) by default and set to false (i.e., avoid buffering and flush every log entry) when the auditable flag is requested. #58995
• The default output format for file-group and stderr sinks has been changed to crdb-v2. This new format is non-ambiguous and makes it possible to reliably parse log files. Refer to the format's documentation for details. Additionally, it prevents single log lines from exceeding a large size; this problem is inherent to the crdb-v1 format and can prevent cockroach debug zip from retrieving v1 log files. The new format has also been designed so that existing log file analyzers for the crdb-v1 format can read entries written the new format. However, this conversion may be imperfect. Refer to the new format's documentation for details. In case of incompatibility, users can force the previous format by using format: crdb-v1 in their logging configuration. #59087

API endpoint changes

• The notable event create_statistics is only reported when the cluster setting sql.stats.post_events.enabled is enabled. This fact is now also reported in the event log reference documentation. #57877
• The Timestamp field of structured notable events is now numeric, and encodes a number of nanoseconds since the Unix epoch. #58070
• The Health API now checks that the SQL server is ready to accept clients when a readiness check is requested. #59350

DB Console changes

• Minor style changes to represent new branding palette. #57130
• Changed the default per-page value on the Transactions page to 20; minor style updates. #57824
• Added a timeseries graph indicating statement denials due to feature flags on the SQL Dashboard of DB Console. #57533
• Updated labels on the Hardware Dashboard to be more accurate. #57224
• Updated the link back to Statements from Statement Details so that it will always link to the Statements list instead of invoking the "back" action on the browser. #57975
• On the Sessions page, every age label has been replaced with duration and every txn label has been replaced with transaction. The actual metrics remain unchanged. #58616
• Renamed the CPUs metric column to vCPUs in the Node List on the Cluster Overview page. #58495
• Added Open SQL Transactions to the SQL Dashboard and renamed SQL Queries to SQL Statements. Removed references to "Distributed SQL Queries" when metrics really are discussing all SQL queries. #57477

Bug fixes

• Fixed a bug in RESTORE where some unusual range boundaries in interleaved tables caused an error. #58219
• Previously, CockroachDB would encounter an internal error when performing a JSONB - String operation via the vectorized execution engine. This has been fixed. The bug was introduced in v20.2.0. #57349
• Previously, in rare situations, an automated replication change could result in a loss of quorum. This was possible when a cluster had down nodes and a simultaneous change in replication factor. Note that a change in the replication factor can occur automatically if the cluster is comprised of fewer than five available nodes. Experimentally the likelihood of encountering this issue, even under contrived conditions, was small. #56735
• Fixed an internal error when using aggregates and window functions in an ORDER BY for a UNION or VALUES clause. #57498
• DROP TYPE and certain other statements that work over SQL scalar types now properly support type names containing special characters. #57354
• Fixed a performance regression introduced in v20.2 to reading virtual tables which introspect the schema. #57542
• Removed system.jobs full table scan that is expensive in the face of many completed jobs. #57587
• In v20.2.0 we mistakenly permitted users with the admin role to drop tables in the system database. This commit revokes that privilege. #57568
• Previously, users could not perform a cluster restore from old backup chains (incrementals on top of fulls) when using the BACKUP INTO syntax. #57656
• Fixed a bug that could cause IMPORT to incorrectly read files stored on Google Cloud if uploaded using its compression option (gsutil -Z). #57745
• Fixed a bug where ST_MakeLine and ST_Collect did not respect ordering when used over a window clause. #57724
• Fixed a bug where schema change jobs to add foreign keys to existing tables, via ALTER TABLE, could sometimes not be successfully reverted (either due to being canceled or having failed). #57598
• Fixed a bug where concurrent addition of a foreign key constraint and drop of a unique index could cause the foreign key constraint to be added with no unique constraint on the referenced columns. #57598
• Adding a primary key constraint to a table without a primary key no longer ignores the name specified for the primary key. #57146
• Previously, when displaying replica counts during the decommissioning process, we were overcounting the replicas displayed for r1. This is no longer the case. #57812
• Fixed a bug whereby tables in schemas other than public would not be displayed when running SHOW TABLES FROM <db>. #57749
• Fixed a bug where canceled queries reading from virtual tables could cause a crashing panic. #57828
• Fixed an assertion error caused by some DDL statements used in conjunction with common table expressions (WITH). #57927
• Previously, SHOW GRANTS ON DATABASE did not include privileges that were granted on a database. Now it does. The SHOW GRANTS ON DATABASE output no longer includes a column for schema_name, as these grants are not specific to any schema. #56866
• The information_schema.schema_privileges table now includes the correct schema-level privileges for non-user-defined schemas. Previously, all of these schemas were omitted from the table. #56866
• The has_schema_privilege built-in function now works on user-defined schemas when checking for the USAGE privilege. #56866
• The ST_FrechetDistance built-in function no longer causes a SIGFPE panic for very small values of densifyFrac (e.g., 1e-20), and returns an error instead. #57966
• CockroachDB now removes a node's status entry when the node is decommissioned, to prevent it from appearing in API calls and UIs, and prevent it from affecting node constraints such as localities and attributes for various operations. #56529
• Fixed a bug which caused type information to be omitted when decoding descriptors using either crdb_internal.pb_to_json or cockroach debug decode-proto. #58087
• Fixed a bug from v21.1.0-alpha.1 where the binary could crash if a running node lost its claim to a job while updating. #58161
• Fixed a bug where multiple invocations of AddGeometryColumn affecting the same table would result in only the last invocation applying. #56663
• Previously, CockroachDB could return non-deterministic output when querying the information_schema.statistics virtual table (internally used by SHOW INDEXES)—namely, the implicit columns of the secondary indexes could be in arbitrary order. This is now fixed, and the columns will be in the same order as they are in the primary index. #58191
• Fixed a column family 0 not found crash caused by explaining or gathering statement diagnostics on certain queries involving virtual tables. #58208
• Added a safeguard against crashes while running SHOW STATISTICS USING JSON, which is used internally for statement diagnostics and EXPLAIN ANALYZE (DEBUG). #58221
• Fixed a bug where prior schema changes on a table that failed and could not be fully reverted could prevent the table from being dropped. #57836
• Previously, CockroachDB could crash when performing a DELETE operation after an alteration of the primary key when in some cases. This is now fixed. The bug was introduced in v20.1. #58153
• Fixed a bug that could cause incremental backups to a backup in a collection (i.e., BACKUP INTO ... IN ...) on some cloud storage providers to ignore existing incremental backups previously appended to that destination and instead backup incrementally from the base backup in that destination. #58292
• Fixed an internal panic when using the SHOW STATISTICS USING JSON statement on a table containing ENUM types. #58251
• A memory leak in the optimizer has been fixed. The leak could have caused unbounded growth of memory usage for a session when planning queries on tables with partial indexes. #58306
• Fixed a bug where primary key changes on tables being watched by changefeeds would be silently ignored. #58140
• The pg_catalog metadata tables were using the CHAR data type for single-byte character columns. Now they use the char data type, to match PostgreSQL. This resolves errors that would occur when using some drivers (like tokio-postgres for Rust) to access pg_catalog tables in the binary query format. #58084
• Prepared statements that include enums and use the binary format will no longer result in an error. #58043
• Fixed an internal error that could occur when executing prepared statements with placeholders that delete data from columns referenced by a foreign key with ON DELETE CASCADE. #58431
• Fixed a bug which caused errors when querying a table with a disjunctive filter (an OR expression) that is the same or similar to the predicate of one of the table's partial indexes. #58434
• Previously, in event log entries for ALTER TYPE and DROP TYPE statements, the TypeName field did not contain fully qualified names. #58257
• A CREATE TABLE statement with indexes with duplicate names will no longer result in an assertion failure. This bug was present since v20.2. #58433
• Previously, event logs were not capturing the qualified table names for COMMENT ON INDEX and COMMENT ON COLUMN commands. This PR changes the event logs to use the qualified table name. Tests were also added for these changes. #58472
• The has_${OBJECT}_privilege built-in methods such as has_schema_privilege now additionally check whether the roles of which a user is a direct or indirect member also have privileges on the object. Previously only one user was checked, which was incorrect. This bug has been present since v2.0 but became more prominent in v20.2 when role-based access control was made available in the core version of CockroachDB. #58254
• CockroachDB previously would return an internal error when attempting to execute a hash join on a JSON column via the vectorized engine. Now a more user-friendly error is returned. #57994
• Fixed a panic in protobuf decoding. #58716
• The user authentication flow no longer performs extraneous name lookups. This performance regression was present since v20.2. #58671
• CockroachDB could previously return an internal error when evaluating a binary expression between a Decimal and an Interval that required a cast to a Float when the value is out of range. A more user-friendly error is now returned instead. #58743
• Qualified table name for alter_table_owner event log. #58504
• Fixed a bug that caused errors when accessing a tuple column (tuple.column syntax) of a tuple that could be statically determined to be null. #58747
• The indoption column in pg_catalog.index is now populated correctly. #58947
• Previously, CockroachDB could encounter an internal error when executing queries with tuples containing null values and enums in a distributed setting. This is now fixed. #58894
• Fixed a nil pointer panic edge case in query setup code. #59002
• Non-ASCII characters in NAME results in cockroach sql / demo (e.g., in the results SHOW TABLES, SHOW CONSTRAINTS) are now displayed without being escaped to octal codes. #56630
• Garbage collection (GC) jobs now populate the running_status column for SHOW JOBS. This bug has been present since v20.1. #58612
• Previously, CockroachDB could encounter an internal error when executing queries with BYTES or STRING types via the vectorized engine in rare circumstances. This is now fixed. #59028
• Previously, the substring function on byte arrays would treat its input as unicode code points, which would cause the wrong bytes to be returned. Now it only operates on the raw bytes. #58265
• Previously, the substring(byte[]) functions were not able to interpret bytes that had the \ character since it was being treated as the beginning of an escape sequence. This is now fixed. #58265
• Fixed a bug in which some non-conflicting rows provided as input to an INSERT ... ON CONFLICT DO NOTHING statement could be discarded, and not inserted. This could happen in cases where the table had one or more unique indexes in addition to the primary index, and some of the rows in the input conflicted with existing values in one or more unique index. This scenario could cause the rows that did not conflict to be erroneously discarded. This has now been fixed. #59147
• Fixed an internal error that could occur when ARRAY[NULL] was used in a query due to incorrect typing. ARRAY[NULL] is now typed as string[] if the type cannot be otherwise inferred from the context. This is the same logic that PostgreSQL uses, thus improving compatibility in addition to fixing the internal error. #59136
• Fix a slow / hanging query that can be caused by using large max_decimal_digits on ST_AsGeoJSON. #59165
• Queries that attempt to retrieve just the key columns of a single system table row will no longer return erroneous values. #58659
• Fixed a bug in URL handling of HTTP external storage paths on Windows. #59216
• Previously, CockroachDB could crash when executing ALTER INDEX ... SPLIT/UNSPLIT AT when more values were provided than are explicitly specified in the index. This has been fixed. #59213
• Fixed a bug where multi-tenancy SQL pods would not successfully initialize the GEOS library. #59259
• Placeholder values are now included alongside statements in structured events. #59110
• Added qualification prefix for user-defined schema names in event logs. #58617
• Added qualification prefix for dropped views in event logs. #59058
• Parsing errors are no longer thrown when importing a pgdump file with array data. #58244
• Fixed a crash when creating backup schedules writing to GCS buckets. #57617
• CockroachDB now correctly exports schedules_BACKUP_* metrics as well as backup RPO metrics. #57488

Performance improvements

• Previously, CockroachDB when performing an unordered DISTINCT operation via the vectorized execution engine would buffer up all tuples from the input, which is a suboptimal behavior when the query has a LIMIT clause. This has now been fixed. This behavior was introduced in v20.1. Note that the row-by-row engine doesn't have this issue. #57579
• The query optimizer can use filters that constrain columns to multiple constant values to generate lookup joins. For example, a join filter x.a = y.a AND y.b IN (1, 2) can be used to generate a lookup join on table y assuming that it has an index on (a, b) or (b, a). #57690
• The query optimizer now explores plans with lookup joins on partitioned indexes, resulting in more efficient query plans in some cases. #57690
• Potentially improved performance for UPDATE statements where the table has computed columns that do not depend on updated columns. #58188
• CockroachDB now allows the storage engine to compact sstables based on reads, on read-heavy workloads. #58247
• Partial indexes with IS NOT NULL predicates can be used in cases where JOIN filters implicitly imply the predicate. This results in more efficient query plans for JOINs and foreign checks. #58204
• Queries that use a geospatial GIN index can now take advantage of vectorized execution for some parts of the query plan, resulting in improved performance. #58241
• Previously, indexed columns of partial indexes were always fetched for UPDATEs and UPSERTs. Now they are only fetched if they are required for maintaining the state of the index. If an UPDATE or UPSERT mutates columns that are neither indexed by a partial index nor referenced in a partial index predicate, they will no longer be fetched (assuming that they are not needed to maintain the state of other indexes, including the primary index). #58358
• UPDATE operations on tables with partial indexes no longer evaluate partial index predicate expressions when it is guaranteed that the operation will not alter the state of the partial index. In some cases, this can eliminate fetching the existing value of columns that are referenced in partial index predicates. #58358
• The sum_int aggregate function is now evaluated more efficiently in a distributed setting. #58345
• INSERT ... ON CONFLICT ... DO NOTHING statements now use anti-joins for detecting conflicts. This simplifies the query plan for these statements, which may result in more efficient execution. #58679
• Improved the accuracy of histogram calculations for the following types: string/uuid/inet family. Additionally, support for time/timetz histogram calculations was also added. This improves optimizer's estimates and results in better query plans in certain instances. #55797
• The optimizer now uses collected histogram statistics to better estimate the cost of JSON and ARRAY GIN index scans, which may lead to more efficient query plans. #59326

Build changes

• CockroachDB now builds on Ubuntu 20.10 and other distros using gcc-10. #58895

Doc updates

• The types of logging sinks available through configuration are now automatically documented. #59083
• The various output formats available for logging configurations are now documented. See the generated reference documentation for details. #58075
• The cluster event logging system has been standardized. Reference documentation is now available (auto-generated from source code); changes to non-reserved payloads will now be announced at least one release version in advance. The event types are organized into broad categories: SQL Logical Schema Changes, SQL Privilege Changes, SQL User Management, CLuster-level events and SQL Miscellaneous operations. #57737
• A report of the possible logging severities and channels is now automatically generated. #57134

v21.1.0-alpha.1

Release Date: December 8, 2020

Downloads

Full CockroachDB executable

Linux Intel Mac Intel
(Experimental) Mac ARM
(Experimental) Windows
(Experimental) Source

Warning:

CockroachDB executable for Windows is experimental and not suitable for production deployments. Windows 8 or higher is required.

Docker image

To download the Docker image (Intel-only):

docker pull cockroachdb/cockroach-unstable:v21.1.0-alpha.1

Backward-incompatible changes

• RocksDB can no longer be used as the storage engine. Passing in --storage-engine=rocksdb now returns an error. #55509
• Rows containing empty arrays in ARRAY columns are now contained in GIN indexes. This change is backward-incompatible because prior versions of CockroachDB will not be able to recognize and decode keys for empty arrays. Note that rows containing NULL values in an indexed column will still not be included in GIN indexes. #55970
• Concatenation between a non-null argument and a null argument is now typed as string concatenation, whereas it was previously typed as array concatenation. This means that the result of NULL || 1 will now be NULL instead of {1}. To preserve the old behavior, the null argument can be casted to an explicit type. #55611

General changes

• Added increased logging and metrics around slow disk operations. #54215
• CockroachDB now detects stalled disk operations better and crashes the process if a disk operation is taking longer than a minute. Added cluster settings to allow for tuning of this behavior. #55186
• Added some metrics surrounding schema changes. #54855
• Upgraded CockroachDB's version of Go to v1.15.4. #56363
• The timezone data is now built in to the CockroachDB binary, which is the fallback source of time if tzdata is not located by the default Go standard library. #56634
• Renamed instances of "Admin UI" to "DB Console" in the documentation of OIDC cluster settings. #56869
• Included tar in docker images. This allows users to use kubectl cp on 20.2.x containers. #57241

Enterprise edition changes

• It is no longer allowed to widen an incremental-backup chain with the inclusion of new complete empty DBs. #54329
• Added cluster settings to enable/ disable the BACKUP and RESTORE commands. Attempts to use these features while they are disabled returns an error indicating that the database administrator has disabled the feature. Example usage: SET CLUSTER SETTING feature.backup.enabled = FALSE; SET CLUSTER SETTING feature.backup.enabled = TRUE; SET CLUSTER SETTING feature.restore.enabled = FALSE; SET CLUSTER SETTING feature.restore.enabled = TRUE;. #56533
• Added cluster settings to enable/ disable the IMPORT, EXPORT, and changefeed commands. Attempts to use these features while they are disabled returns an error indicating that the database administrator has disabled the feature. Example usage: SET CLUSTER SETTING feature.import.enabled = FALSE; SET CLUSTER SETTING feature.import.enabled = TRUE; SET CLUSTER SETTING feature.export.enabled = FALSE; SET CLUSTER SETTING feature.export.enabled = TRUE; SET CLUSTER SETTING feature.changefeed.enabled = FALSE; SET CLUSTER SETTING feature.changefeed.enabled = TRUE;. #56872

SQL language changes

• Interleaved joins have been removed; merge joins are now planned in all cases when interleaved joins would have been planned previously. #54163
• It is now possible to create partial GIN indexes. The optimizer will choose to scan partial GIN indexes when the partial index predicate is implied and scanning the GIN index has the lowest estimated cost. #54376
• EXPLAIN ANALYZE diagrams now contain "bytes sent" information on streams. #54518
• Implemented the geometry built-in functions ST_Rotate({geometry, float8, geometry}). #54610
• Implemented the geometry built-in function ST_ClosestPoint(). #54843
• Implement the string built-in function unaccent(). #54628
• When enterprise features are not enabled, the follower_read_timestamp() function now returns (statement_time - 4.8s) instead of an error. #54951
• Added a new virtual table crdb_internal.invalid_descriptors, which runs validations on descriptors in the database context and reports any errors. #54017
• Implemented the built-in operator add jsonb_exists_any(jsonb, text[]). #55172
• Added the ability to optionally specify the PRIVILEGES keyword when issuing the GRANT ALL or REVOKE ALL statements, for Postgres compatibility. Previously, a statement like the following would fail with a syntax error: GRANT ALL PRIVILEGES ON DATABASE a TO user1;. #55304
• Implemented the built-in function pg_column_size(), which counts the amount of bytes stored by column. #55312
• Implemented the geometry built-in functions ST_Rotate({geometry, float8, float8, float8}). #55428
• Implemented the built-in function ST_MemSize(), which returns the memory space a geometry takes. #55416
• SHOW ENUMS now returns an array aggregation of enum values instead of having them separated by the | character. #55386
• Implemented the geometry built-in function ST_PointInsideCircle(). #55464
• Implement the geometry built-in function ST_LineFromEncodedPolyline(). #55429
• Implement the geometry built-in function ST_AsEncodedPolyline(). #55515
• Implement the geometry built-in function ST_LineLocatePoint(), which computes the fraction of the line segment that represents the location of the given point to the closest point on the original line. #55470
• Implemented the REASSIGN OWNED BY ... TO ... statement, which changes ownership of all database objects in the current database, owned by any roles in the first argument, to the new role in the second argument. #54594
• Implemented the geometry built-in function ST_MinimumBoundingRadius(), which returns a record containing the center point and radius of the smallest circle that can fully contain a geometry. #55532
• The vectorized engine now supports the JSONFetchValPath (#>) operator. #55570
• Added the ability to cast a string containing all integers into a given regtype, e.g., '1234'::regproc. #55607
• Potentially hazardous DROP COLUMN operations when sql_safe_updates is enabled now return a note and link to https://github.com/cockroachdb/cockroach/issues/46541. #55248
• Changed the SPLIT AT output to be consistent with the output from SHOW RANGES. #55543
• Implemented the geometry built-in function ST_MinimumBoundingCircle(), which returns polygon shape that approximates minimum bounding circle to contain geometry. #55567
• Added the constraint name to constraint errors, for increased wire-level Postgres compatibility. #55660
• Added support for using the syntax ... UNIQUE WITHOUT INDEX ... in CREATE TABLE and ALTER TABLE statements, both when defining columns and unique constraints. Although this syntax can now be parsed successfully, using this syntax currently returns an error: unique constraints without an index are not yet supported. #55700
• Add the built-in functions sha224() and sha384(). #55720
• Implemented SHOW REGIONS, which returns all of regions available in a cluster. #55831
• Implemented the geography built-in function ST_UnaryUnion() #55894
• Implemented ALTER TABLE ... SET LOCALITY/REGIONAL AFFINITY statements, which configure multi-region properties of given tables. These are subject to change. #55827
• All expressions in EXPLAIN output that operate on indexes now show the table name the index is declared on, rather than just an alias. If the query aliases the table, the alias is also shown. For example, a scan on table foo that is aliased as f was previously displayed as scan f. It is now displayed as scan foo [as=f]. #55641
• Changed the underlying type for the version cluster setting. Previously, it was of an internal type representing "state machine", but now it's simply "version". This has no operational implications, but the Type column in cockroach gen settings-list now shows "version" instead of "custom validation". #55994,#56546
• Removed the 201auto value for the vectorize session variable and the corresponding cluster setting. #55907
• Expanded the CREATE SCHEMA, DROP SCHEMA, ALTER SCHEMA, GRANT ... ON SCHEMA, REVOKE ... ON SCHEMA, and SHOW GRANTS ON SCHEMA statements to allow schema names prefixed with database names. #55647
• Added support for dollar-quoted strings with digit. #55958
• Added a new single-column output format for EXPLAIN and EXPLAIN (VERBOSE). #55866
• Creating multi-column GIN indexes is now allowed by setting the experimental_enable_mutlti_column_inverted_indexes session setting to true. At this time, these indexes are not fully supported and their behavior is undefined. Using this feature will likely result in errors. Do not enable this setting in a production database. #55993
• Constraints that have not been validated are now marked "NOT VALID" in the output of SHOW CREATE and SHOW CONSTRAINTS. #53485
• The NOT VALID option can now be provided for CHECK and FOREIGN KEY constraints listed as table constraints in CREATE TABLE statements. This option has no affect on the constraint created. It will not skip validation. #53485
• Added a pgcode (42704, undefined_object) to the error returned when attempting to drop an index by a table and index name that doesn't exist. #55417
• Added the WITH row_limit="{$num}" option for importing CSVs to allow users to do a quick test run on an import of $num rows. Example: IMPORT TABLE test ... CSV DATA ... WITH row_limit="3"; #56080
• Added the WITH row_limit="{$num}" option for importing DELIMITED/AVRO data to allow users to do a quick test run on an import of $num rows. Example: IMPORT TABLE test ... DELIMITED/AVRO DATA ... WITH row_limit="3"; #56135
• Added WITH row_limit="{$num}" option for importing bundle formats to allow users to do a quick test run on an import of $num rows. Example: IMPORT ... WITH row_limit="3";. #56587
• EXPLAIN ANALYZE diagrams now contain "network latency" information on streams. #55705
• Implemented the covar_pop() and covar_samp() aggregation functions. #55707
• Prevented column type modification of columns that are depended on by views. #56213
• Implemented the geometry built-in functions ST_TransScale({geometry,float8,float8,float8,float8}) #56198
• Implemented the geometry built-in function ST_Node(). #56183
• The concatenation operator || can now be used between strings and any other non-array types. #55611
• CockroachDB now returns a float instead of a decimal when at least one argument of an aggregate function is decimal. #56296
• Implemented the regr_intercept(), regr_r2(), and regr_slope() aggregation functions. #56296
• EXPLAIN ANALYZE diagrams now show "deserialization time" on streams instead of "io time". #56144
• Added a pgcode (42804, DatatypeMismatch) when adding a default value of the wrong type to a column. #56455
• Attempting to rename an undefined index now returns a pgcode.UndefinedObject (42704) error instead of an uncategorized error. #56455
• Implemented the regr_sxx(), regr_sxy(), and regr_syy() aggregation functions. #56585
• SHOW REGIONS has changed the column name for availability zones to "zones" from "availability_zones". #56344
• Introduced a pg_collation of "default". Strings now return the "default" collation OID in the pg_attribute table (this was previously en_US). The "default" collation is also visible on the pg_collation virtual table. #56598
• A table can now successfully be dropped in a transaction following other schema changes to the table in the same transaction. #56589
• Added a new variant of explain: EXPLAIN ANALYZE (PLAN). #56524
• SHOW REGIONS functionality is now deferred to SHOW REGIONS FROM CLUSTER. #56627
• It is now possible to hint to the optimizer that it should plan an inverted join by using the syntax ... INNER INVERTED JOIN ... or ... LEFT INVERTED JOIN .... If the hint is provided and it is possible to plan an inverted join, the optimizer will now plan an inverted join, even if it estimates that a different plan would have a lower cost. If the hint is provided but it is not possible to plan an inverted join because there is no GIN index on the right side table or the join condition is not a valid inverted join condition, the database will return an error. #55679
• Added the empty pg_catalog.pg_opclass table to improve compatibility with Postgres. #56653
• SURVIVE AVAILABILITY ZONE FAILURE is now SURVIVE ZONE FAILURE. #56837
• Added admin-only, crdb_internal functions to enable descriptor repair in dire circumstances. #55699
• Added support for an optional = character for SURVIVE, e.g., ALTER DATABASE d SURVIVE = ZONE FAILURE. #56881
• Introduced stubs for ALTER DATABASE ... PRIMARY REGION and CREATE TABLE ... PRIMARY REGION. #56883
• Dropping the primary index using DROP INDEX now returns a FeatureNotSupported error along with hints showing supported ways to drop primary indexes. #56858
• Renaming an index to a name that is already being used for another index will now return a pgcode.DuplicateRelation (42P07) error instead of an uncategorized error. #56681
• The relpersistence column in pg_catalog.pg_class now correctly displays t as the persistence status for temporary tables. #56827
• Added a deprecation notice to statements containing the INTERLEAVE IN PARENT clause. #56874
• SHOW DATABASES and crdb_internal.databases now display all regions as well as survival goals for a given database. #56880
• Adds a feature flag via cluster settings for the CREATE STATISTICS and ANALYZE feature. If a user attempts to use the command while disabled, an error indicating that the database administrator had disabled the feature is surfaced. Example usage: SET CLUSTER SETTING feature.stats.enabled = FALSE; SET CLUSTER SETITNG feature.stats.enabled = TRUE;. #57076
• CREATE DATABASE ... PRIMARY REGION is now stored on the database descriptor. #57038
• SHOW DATABASES and crdb_internal.databases now display the PRIMARY REGION set on the database descriptor as the primary_region column. #57038
• Added a feature flag via cluster settings for all schema change-related features. If a user attempts to use these features while they are disabled, an error indicating that the database administrator has disabled the feature is surfaced. Example usage: SET CLUSTER SETTING feature.schema_change.enabled = FALSE; SET CLUSTER SETTING feature.schema_change.enabled = TRUE;. #57040
• Changed pg_constraint column types for confkey and conkey to smallint[] to improve compatibility with Postgres. #56975
• The ALTER TABLE...SPLIT/UNSPLIT and ALTER INDEX...SPLIT/UNSPLIT commands are now gated by a schema change feature flag. If a user attempts to use these features while they are disabled, an error indicating that the system administrator has disabled the feature is surfaced. Example usage: SET CLUSTER SETTING feature.schema_change.enabled = FALSE SET CLUSTER SETTING feature.schema_change.enabled = TRUE;. #57142
• When creating a database with the regions clause specified, CockroachDB now creates a regions enum type automatically. #56628
• Implemented SHOW REGION FROM DATABASE and SHOW REGION FROM DATABASE db, which shows all regions for the given database, as well as whether that region is the primary region. #57106
• CREATE TABLE AS SELECT ... FROM ... AS OF SYSTEM TIME x is now supported. #55916
• Implemented the function regr_count(). #56822
• Added the character_sets table to the information_schema. #56953
• SHOW ENUMS is now extended to take an optional FROM clause. The user can specify either the schema name or both the database name and schema name separated by .. If a hierarchy is specified, the statement returns enums falling in that hierarchy rather than all of the enums in the current database. #57197
• The multi-region enum, created implicitly for all multi-region databases, can be introspected using the pg_catalog.pg_enum table. It is also displayed in SHOW ENUMS. #57197
• Implemented the geography built-in function ST_Subdivide(). #56898
• A pgcode.UndefinedColumn error is now returned when adding a unique constraint to one or more undefined columns. #57316
• The database name is now displayed in SHOW REGIONS FROM DATABASE. #57278
• Added SHOW SURVIVAL GOAL FROM DATABASE [database], which shows the survival goal for a multi-region database. #57278
• Added the uuid_generate_v4() built-in function. It works exactly like gen_random_uuid() but was added for compatibility with Postgres versions older than PG13. #57212

Command-line changes

• A debug.zip file now includes a script, hot-ranges.sh, which will summarize the hottest ranges in the cluster. #53547
• cockroach sql and cockroach demo now support the command-line parameter --file (shorthand -f) to read commands from a named file. The behavior is the same as if the file was redirected on the standard input; in particular, the processing stops at the first error encountered (which is different from interactive usage with a prompt). Note that it is not yet possible to combine -f with -e. #54741
• The large banner message "Replication has been disabled for this cluster ..." that was unconditionally emitted on the standard error stream for cockroach start-single-node has now become a simple log message at severity INFO. #54749
• cockroach demo now pre-creates a demo user account with a random password to discourage the user of root. The demo account is currently granted the admin role. #54749
• The CLI help text for --max-disk-temp-storage now properly reports the default value. #54853
• The help text displayed by \? in cockroach sql and cockroach demo now groups the recognized client-side commands into sections for easier reading. #54796
• The client-side command \show for the SQL shell is deprecated in favor of the new command \p. This prints the contents of the query buffer entered so far. #54796
• The new client-side command \r for the SQL shell erases the contents of the query buffer entered so far. This provides a convenient way to reset the input, for example, when the user gets themselves confused with string delimiters. #54796
• The SQL shell (cockroach sql, cockroach demo) now supports the client-side command \echo, like psql. This can be used, for example, to generate informational output when executing SQL scripts non-interactively. #54796
• The SQL shell (cockroach sql, cockroach demo) now support the \i and \ir client-side command which reads SQL file and evaluates its content in-place. \ir differs from \i in that the file name is resolved relative to the location of the script containing the \ir command. This makes \ir likely more desirable in the general case. Instances of \q inside a file included via \i/\ir stop evaluation of the file and resume evaluation of the file that included it. This feature is compatible with the identically named psql commands. It is meant to help compose complex initialization scripts from a library of standard components. For example, one could be defining each table and its initial contents in separate SQL files, and then use different super-files to include different tables depending on the desired final schema. #54796
• Removed the debug sstables command, superseded by the debug pebble lsm command. #54890
• Added the cockroach debug pebble db checkpoint debug command to easily create a checkpoint without using rocksdb. #55751
• Updated the --storage-engine help text to reflect RocksDB deletion. #55509
• Added support for \connect DATABASE and \c DATABASE. #55934
• Added an import CLI command that allows users to upload and import local dump files into a running cockroach cluster. PGDUMP and MYSQLDUMP formats are currently supported. #54896
• cockroach demo now allows for nodes to be added using the \demo client-side command. This works in both single node and multi-node configurations, for example, when started with --nodes int or --geo-partitioned-replicas. #56344

• Some specific situations now have dedicated exit status codes. The following codes are defined:

  Code	Description
  0	Process terminated without error.
  1	An unspecified error was encountered. Explanation should be present in the stderr or logging output.
  2	Go runtime error, or uncaught panic. Likely a bug in CockroachDB. Explanation may be present in logging output.
  3	Server process interrupted gracefully with Ctrl+C / SIGINT.
  4	Command-line flag error.
  5	A logging operation to the process' stderr stream failed (e.g., stderr has been closed). Some details may be present in the file output, if enabled.
  6	A logging operation to file has failed (e.g., log disk full, no inodes, permission issue, etc.). Some details may be present in the stderr stream.
  7	Server detected an internal error and triggered an emergency shutdown.
  8	Logging failed while processing an emergency shutdown.

  #56574

• cockroach demo now tries to use the same TCP port numbers for the SQL and HTTP servers on every invocation. This is meant to simplify documentation. These defaults can be overridden with the new (demo-specific) command line flags --sql-port and/or --http-port. #56737

• The SQL shell now accepts yes/no as boolean options for slash commands, following psql behavior. #56829

• A \x [on|off] command has been added to toggle the records display format, following psql behavior. #56829

• CockroachDB now prints a warning if the --locality flag does not contain a "region" tier. #57179

API endpoint changes

• Added a new prometheus metric called seconds_until_license_expiry that reports the number of seconds until the enterprise license on the cluster expires, a negative number if the expiration is in the past, or 0 if there is no license. #55565

DB Console changes

• Changed the view for tables without data on main pages. #54943
• Updated the design of the custom date range selector on the Cluster > Maps view and Metrics pages #54851
• The DB Console now shows messages provided by server instead of custom generic messages defined on the client side, for example, messages about permission restrictions to show pages for non-admin roles. #50869
• Added a new metric called raft.scheduler.latency, which monitors the latency for operations to be picked up and processed by the Raft scheduler. #56943
• Redesigned inline error alerts when a user has insufficient rights to see some resources. #50869
• Implemented a permission denied error for non-admin users on the Node Map and Events views. #50869
• Tables within user-defined schemas are now included in the Data Distribution page. #56388
• Creating, dropping, and altering roles or users now causes events to be logged and displayed. #55945
• If statement diagnostics are enabled for a statement, the bytes sent over the network are now shown. #55969
• ALTER DATABASE OWNER and CONVERT TO SCHEMA now cause events to be logged and displayed. #55891
• Changing schema objects now causes events to be logged and displayed. #55785
• Changing privileges (i.e., with GRANT or REVOKE) now causes events to be logged and displayed. #55612
• Renaming databases or tables now causes events to be logged and displayed. #55269
• Added descriptions for failed job on the Job Details page. #54268

Bug fixes

• Fixed the rpath and so names of libgeos.so and libgeos_c.so such that a dlopen to libgeos.so is not needed. #55129
• Made lease transfers during rebalancing adhere to the rate limit utilized in other lease transfer cases which eliminates unexpected lease oscillations when adding a new node. #54322
• CockroachDB now handles PostgreSQL "cancel" messages on TLS connections in the same way as when they are sent without TLS: the connection is closed, but no action takes place. No error is logged. As a reminder, PostgreSQL "cancel" messages are still unsupported in CockroachDB and client should still use CANCEL QUERY instead. #54618
• Cleared table statistics from job description in failed and canceled backup jobs. #54446
• Fixed an error message that referred to experimental_enable_hash_sharded_indexes as a cluster setting when it is in fact a session variable. #54960
• Fixed a nil pointer error that could occur at planning time for some spatial queries when a GIN index existed on a geometry or geography column. #55076
• Fixed SHOW ENUMS column names to have values instead of string_agg for column names, and owner for the owner itself. #55139
• Fixed SHOW TYPES to show the owner column instead of the value column. #55139
• Fixed a bug where empty enums did not show up for SHOW ENUMS or SHOW TYPES. #55143
• Fixed a bug where, on failure of CREATE TABLE AS or CREATE MATERIALIZED VIEW, tables would be left in an invalid non-public state until GC instead of being marked as dropped, possibly causing spurious validation failures. The bug was introduced in earlier 20.2 pre-releases. #55272
• Fixed a rare scenario in which a node would refuse to start after updating the binary. The log message would indicate: store [...], last used with cockroach version [...], is too old for running version [...] (which requires data from [...] or later). #55240
• Changefeeds defined on multiple tables will now only backfill affected tables after a schema change. #55135
• Fixed a bug where adding child tables or types to a schema being restored would cause those new child objects to become corrupted with no parent schema if the restore job had to be rolled back. #55157
• Fixed a bug where the seconds component of a zone offset of a TIMESTAMPTZ value was not displayed. #55071
• Fixed a bug where casts to regclass were not escaped, e.g., when the type or table name had " characters. #55607
• Fixed a bug where casts from string to regproc, regtype or regprocedure would not work if they contained " characters at the beginning or at the end. #55607
• Fixed a bug which could cause IMPORT, BACKUP, or RESTORE to experience an error when they occur concurrently to when the cluster sets its version to upgraded. #55524
• Fixed a rare crash during tracing when reading un-decodable data. #55783
• Prevented a crash, introduced in the 20.2 series, caused by range scans over virtual tables with virtual indexes. #56459
• In some cases CockroachDB, would attempt to transfer ranges to nodes in the process of being decommissioned or being shut down; this could cause disruption the moment the node did actually terminate. This bug has been fixed. It had been introduced some time before v2.0. #55808
• Fixed a bug causing queries sent to a freshly-restarted node to sometimes hang for a long time while the node catches up with replication. #55148
• Fixed typing of collated strings so that collation names are case-insensitive and hyphens/underscores are interchangeable. #56352
• Fixed internal errors related to very large LIMIT and/or OFFSET values. #56672
• Improved the accuracy of reported CPU usage when running in containers. #56461
• Fixed a bug which can lead to canceled schema change jobs ending in the failed rather than canceled state. #55513
• Prevented an opportunity for livelock in the jobs subsystem due to frequent updates to already finished jobs. #56855
• The LogFile reserved API, which was used by cockroach debug zip, could corrupt log entries. This has been fixed. #56901
• DELETE statements no longer have a chance of returning an incorrect number of deleted rows in transactions that will eventually need to restart due to contention. #56458
• Fixed a race condition in the tpcc workload with the --scatter flag where tables could be scattered multiple times or not at all. #56942
• Fixed a bug where reg* types were not parsed properly over pgwire, COPY or prepared statements. #56298
• Previously, casts and parsing of strings to types could allow an out-of-bounds value to be successfully used (e.g., SELECT -232321321312::int2) but fail with an out-of-bounds message when it is inserted into the table. This is now checked when the value is parsed or being casted to. #55095
• cockroach debug merge-logs --redact=true --redactable-output=false now properly removes redaction markers. #57121
• Fixed a bug related to validation of un-upgraded pre-19.2 inbound foreign keys. #57132
• Creating a materialized view that references a column with a NULL value no longer results in an error. #57139
• ST_GeomFromGeoJSON now sets the SRID to 4326, matching PostGIS 3.0 / RFC7946 behavior. #57152
• Fixed a bug that caused an "ambiguous column reference" error during foreign key cascading updates. This error was incorrectly produced when the child table's reference column name was equal to the concatenation of the parent's reference column name and "_new", and when the child table had a CHECK constraint, computed column, or partial index predicate expression that referenced the column. This bug was introduce in version 20.2. #57153
• Fixed a bug that caused errors or corrupted partial indexes of child tables in foreign key relationships with cascading UPDATEs and DELETEs. The corrupt partial indexes could result in incorrect query results. Any partial indexes on child tables of foreign key relationships with ON DELETE CASCADE or ON UPDATE CASCADE actions may be corrupt and should be dropped and re-created. This bug was introduce in version 20.2. #57100
• Second timezone offsets for TIMETZ now correctly display over the Postgres wire protocol; these were previously omitted. #57265
• SELECT FOR UPDATE now requires both SELECT and UPDATE privileges, instead of just UPDATE privileges. #57309
• Fixed a bug where users of an OSS build of CockroachDB would see "Page Not Found" when loading the DB Console. #56591

Performance improvements

• The optimizer can now deduce that certain variable arguments to functions must be non-null. This improves cardinality estimation for those variables and unlocks other types of optimizations. As a result, the optimizer may choose better query plans when a function is used as a filter predicate. #54558
• Improved the selectivity estimate for array contains predicates (e.g., arr @> ARRAY[1]) in the optimizer. This improves the optimizer's cardinality estimation for queries containing these predicates, and may result in better query plans in some cases. #54768
• Updated the cost model in the optimizer to make index joins more expensive and better reflect the reality of their cost. As a result, the optimizer will choose index joins less frequently, generally resulting in more efficient query plans. #54768
• The optimizer simplifies join expressions to only scan a single table when the join filter is a contradiction. A limitation, now removed, was preventing this simplification from occurring in some cases, leading to more efficient query plans in some cases. #54813
• Improved the efficiency of plans for the execution of left outer spatial joins. #55216
• The optimizer now considers partial indexes when exploring zigzag joins. This may lead to more efficient query plans for queries that (1) operate on tables with partial indexes and (2) have a filter that holds two columns, indexed by two indexes, constant. #55401
• The optimizer now attempts to split a query with a disjunctive filter (OR expression) into a UNION of index scans, where one or both of the scans is an unconstrained partial index scan. As a result, more efficient query plans may be generated for queries with disjunctive filters that operate on tables with partial indexes. #55915
• CSV imports should now be slightly faster. #55845
• Previously, all CHECK constraints defined on a table would be tested for every UPDATE to the table. Now, a check constraint will not be tested for validity when the values of columns it references are not being updated. The referenced columns are no longer fetched in cases where they were only fetched to test CHECK constraints. #56007
• Indexes on computed columns can now be utilized when filters reference the computed expression and not the computed column directly. #55867
• The query optimizer can now generate inverted zigzag joins over partial GIN indexes. This may lead to more efficient query plans when filtering by a column that is indexed by a partial GIN index. #56101
• They query optimizer can now plan zigzag joins on two partial indexes with the same predicate, leading to more efficient query plans in some cases. #56103
• The optimizer now converts inner joins with single-row values expressions into projections. This allows decorrelation of subqueries that only reference variables from the outer query, such as SELECT (SELECT value + 10) FROM table. #55961
• The optimizer may now plan an inverted join if two tables are joined on JSONB or ARRAY columns using a contains predicate (e.g., WHERE a @> b), and the first column has a GIN index. The inverted join will be chosen if the optimizer expects it to be more efficient than any alternative plan. For queries in which the only alternative is a cartesian product followed by a filter, the inverted join will likely result in a performance improvement. #55679
• The hybrid logical clock used to coordinate distributed operations now performs significantly better under high contention with many concurrent updates from remote nodes. #56708
• The Raft processing goroutine pool's size is now capped at 96. This was observed to prevent instability on large machines (32+ vCPU) in clusters with many ranges (50k+ per node). #56860
• Interactions between Raft heartbeats and the Raft goroutine pool scheduler are now more efficient and avoid excessive mutex contention. This was observed to prevent instability on large machines (32+ vCPU) in clusters with many ranges (50k+ per node). #56860
• The Raft scheduler now prioritizes the node liveness Range. This was observed to prevent instability on large machines (32+ vCPU) in clusters with many ranges (50k+ per node). #56860
• The optimizer now supports using a GIN index on JSONB or ARRAY columns for a wider variety of filter predicates. Previously, GIN index usage was only supported for simple predicates (e.g., WHERE a @> '{"foo": "bar"}'), but now more complicated predicates are supported by combining simple contains (@>) expressions with AND and OR (e.g., WHERE a @> '{"foo": "bar"}' OR a @> '{"foo": "baz"}'). A GIN index will be used if it is available on the filtered column and the optimizer expects it to be more efficient than any alternative plan. This may result in performance improvements for queries involving JSONB and ARRAU columns. #56732

Doc updates

• Updated several Hello World tutorials to use cockroach demo as the backend and an external repository for code samples, including Go with pgx and GORM, Java with JDBC and Hibernate, and Python with psycopg2, SQLAlchemy, and Django. #9025,#8991,
• Updated the Production Checklist to recommend disabling Linux memory swapping to avoid over-allocating memory. #8979

Contributors

This release includes 1040 merged PRs by 88 authors. We would like to thank the following contributors from the CockroachDB community:

• Adrian Popescu (first-time contributor)
• Alan Acosta (first-time contributor)
• ArjunM98 (first-time contributor)
• Artem Barger
• Azdim Zul Fahmi (first-time contributor)
• David Pacheco (first-time contributor)
• Erik Grinaker
• Gabriel Jaldon (first-time contributor)
• Jake Rote (first-time contributor)
• Joshua M. Clulow (first-time contributor)
• Marcin Knychała (first-time contributor)
• Max Neverov (first-time contributor)
• Miguel Novelo (first-time contributor)
• Ruixin Bao (first-time contributor)
• TAKAHASHI Yuto (first-time contributor)
• Tayo (first-time contributor)
• Tim Graham (first-time contributor)
• Tom Milligan (first-time contributor)
• Vaibhav
• alex-berger@gmx.ch (first-time contributor)
• alex.berger@nexiot.ch (first-time contributor)
• haseth (first-time contributor)
• hewei03 (first-time contributor)
• neeral
• xinyue (first-time contributor)

Was this helpful?