Merge branch 'master' into 23.1-GA-RNs

_config_base.yml

@@ -138,12 +138,12 @@ release_info:
     start_time: 2022-10-13 17:45:03.909127 +0000 UTC
     version: v21.2.17
   v22.1:
-    build_time: 2023-04-24 00:00:00 (go1.19)
+    build_time: 2023-05-12 00:00:00 (go1.19)
     crdb_branch_name: release-22.1
     docker_image: cockroachdb/cockroach
-    name: v22.1.19
-    start_time: 2023-04-24 14:56:42.617860 +0000 UTC
-    version: v22.1.19
+    name: v22.1.20
+    start_time: 2023-05-10 12:58:20.269520 +0000 UTC
+    version: v22.1.20
   v22.2:
     build_time: 2023-05-08 00:00:00 (go1.19)
     crdb_branch_name: release-22.2

_data/releases.yml

@@ -4333,4 +4333,25 @@
     docker_image: cockroachdb/cockroach
     docker_arm: true
   source: true
-  previous_release: v23.1.0-rc.2
+  previous_release: v23.1.0-rc.2
+
+- release_name: v22.1.20
+  major_version: v22.1
+  release_date: '2023-05-12'
+  release_type: Production
+  go_version: go1.19
+  sha: c091e9bdfdff6fd6888a2c514b78e57abbb6119d
+  has_sql_only: true
+  has_sha256sum: true
+  mac:
+    mac_arm: false
+  windows: true
+  linux:
+    linux_arm: false
+    linux_intel_fips: false
+    linux_arm_fips: false
+  docker:
+    docker_image: cockroachdb/cockroach
+    docker_arm: false
+  source: true
+  previous_release: v22.1.19

_includes/releases/cloud/2023-05-10.md

@@ -0,0 +1,5 @@
+## May 10, 2023
+
+<h3> Security updates </h3>
+
+- [Egress Perimeter Controls](/docs/cockroachcloud/egress-perimeter-controls.html), which allow you to restrict egress from a {{ site.data.products.dedicated }} cluster to a list of specified external destinations, are now generally available for {{ site.data.products.dedicated }} advanced clusters.

_includes/releases/v22.1/v22.1.20.md

@@ -0,0 +1,34 @@
+## v22.1.20
+
+Release Date: May 12, 2023
+
+{% include releases/release-downloads-docker-image.md release=include.release %}
+
+<h3 id="v22-1-20-bug-fixes">Bug fixes</h3>
+
+- Fixed a rare bug where [replica rebalancing](../v22.1/architecture/replication-layer.html) during write heavy workloads could cause keys to be deleted unexpectedly from a [local store](../v22.1/cockroach-start.html#flags-store). [#102190][#102190]
+- Fixed a bug introduced in v22.1.19, v22.2.8, and pre-release versions of 23.1 that could cause queries to return spurious insufficient [privilege](../v22.1/security-reference/authorization.html#privileges) errors. For the bug to occur, two databases would need to have duplicate tables, each with a [foreign key](../v22.1/foreign-key.html) reference to another table. The error would then occur if the same SQL string was executed against both databases concurrently by users that have privileges over only one of the tables. [#102653][#102653]
+- Fixed a bug where a [backup](../v22.1/backup-and-restore-overview.html) with a key's [revision history](../v22.1/take-backups-with-revision-history-and-restore-from-a-point-in-time.html) split across multiple [SST files](../v22.1/architecture/storage-layer.html#ssts) may not have correctly restored the proper revision of the key. [#102372][#102372]
+- Fixed a bug present since v21.1 that allowed values to be inserted into an [`ARRAY`](../v22.1/array.html)-type column that did not conform to the inner-type of the array. For example, it was possible to insert `ARRAY['foo']` into a column of type `CHAR(1)[]`. This could cause incorrect results when querying the table. The [`INSERT`](../v22.1/insert.html) now errors, which is expected. [#102811][#102811]
+- Fixed a bug where [backup and restore](../v22.1/backup-and-restore-overview.html) would panic if the target is a synthetic public [schema](../v22.1/schema-design-overview.html), such as `system.public`. [#102783][#102783]
+- Fixed an issue since v20.2.0 where running [`SHOW HISTOGRAM`](../v22.1/show-columns.html) to see the histogram for an [`ENUM`](../v22.1/enum.html)-type column would panic and crash the cockroach process. [#102829][#102829]
+
+<h3 id="v22-1-20-sql-language-changes">SQL language changes</h3>
+
+- Added two views to the [`crdb_internal`](../v22.1/crdb-internal.html) catalog: `crdb_internal.statement_statistics_persisted`, which surfaces data in the persisted `system.statement_statistics` table, and `crdb_internal.transaction_statistics_persisted`, which surfaces the `system.transaction_statistics` table. [#99272][#99272]
+
+<div class="release-note-contributors" markdown="1">
+
+<h3 id="v22-1-20-contributors">Contributors</h3>
+
+This release includes 13 merged PRs by 14 authors.
+
+</div>
+
+[#102190]: https://github.com/cockroachdb/cockroach/pull/102190
+[#102372]: https://github.com/cockroachdb/cockroach/pull/102372
+[#102653]: https://github.com/cockroachdb/cockroach/pull/102653
+[#102783]: https://github.com/cockroachdb/cockroach/pull/102783
+[#102811]: https://github.com/cockroachdb/cockroach/pull/102811
+[#102829]: https://github.com/cockroachdb/cockroach/pull/102829
+[#99272]: https://github.com/cockroachdb/cockroach/pull/99272

_includes/v22.2/misc/note-egress-perimeter-cdc-backup.md

@@ -1,3 +1,3 @@
 {{site.data.alerts.callout_info}}
-We recommend enabling Egress Perimeter Controls on {{ site.data.products.dedicated }} clusters to mitigate the risk of data exfiltration when accessing external resources, such as cloud storage for change data capture or backup and restore operations. See [Egress Perimeter Controls for CockroachDB Dedicated (Preview)](../cockroachcloud/egress-perimeter-controls.html) for detail and setup instructions.
-{{site.data.alerts.end}}
+Cockroach Labs recommends enabling Egress Perimeter Controls on {{ site.data.products.dedicated }} clusters to mitigate the risk of data exfiltration when accessing external resources, such as cloud storage for change data capture or backup and restore operations. See [Egress Perimeter Controls](../cockroachcloud/egress-perimeter-controls.html) for detail and setup instructions.
+{{site.data.alerts.end}}

_includes/v23.1/cdc/metrics-labels.md

@@ -1,9 +1,8 @@
-To measure metrics per changefeed, define a "metrics label" to which one or multiple changefeed(s) will increment each [changefeed metric](monitor-and-debug-changefeeds.html#metrics). Metrics label information is sent with time-series metrics to `http://{host}:{http-port}/_status/vars`, viewable via the [Prometheus endpoint](monitoring-and-alerting.html#prometheus-endpoint). An aggregated metric of all changefeeds is also measured.
+To measure metrics per changefeed, you can define a "metrics label" for one or multiple changefeed(s). The changefeed(s) will increment each [changefeed metric](monitor-and-debug-changefeeds.html#metrics). Metrics label information is sent with time-series metrics to `http://{host}:{http-port}/_status/vars`, viewable via the [Prometheus endpoint](monitoring-and-alerting.html#prometheus-endpoint). An aggregated metric of all changefeeds is also measured.
 
 It is necessary to consider the following when applying metrics labels to changefeeds:
 
-- Metrics labels are **not** available in {{ site.data.products.db }}.
-- The `COCKROACH_EXPERIMENTAL_ENABLE_PER_CHANGEFEED_METRICS` [environment variable](cockroach-commands.html#environment-variables) must be specified to use this feature.
+- Metrics labels are **not** available in {{ site.data.products.serverless }}.
 - The `server.child_metrics.enabled` [cluster setting](cluster-settings.html) must be set to `true` before using the `metrics_label` option.
 - Metrics label information is sent to the `_status/vars` endpoint, but will **not** show up in [`debug.zip`](cockroach-debug-zip.html) or the [DB Console](ui-overview.html).
 - Introducing labels to isolate a changefeed's metrics can increase cardinality significantly. There is a limit of 1024 unique labels in place to prevent cardinality explosion. That is, when labels are applied to high-cardinality data (data with a higher number of unique values), each changefeed with a label then results in more metrics data to multiply together, which will grow over time. This will have an impact on performance as the metric-series data per changefeed quickly populates against its label.

_includes/v23.1/client-transaction-retry.md

@@ -1,3 +1,3 @@
 {{site.data.alerts.callout_info}}
-With the default `SERIALIZABLE` [isolation level](transactions.html#isolation-levels), CockroachDB may require the client to [retry a transaction](transactions.html#transaction-retries) in case of read/write [contention]({{ link_prefix }}performance-best-practices-overview.html#understanding-and-avoiding-transaction-contention). CockroachDB provides a [generic retry function](transactions.html#client-side-intervention) that runs inside a transaction and retries it as needed. The code sample below shows how it is used.
+With the default `SERIALIZABLE` [isolation level](transactions.html#isolation-levels), CockroachDB may require the client to [retry a transaction](transactions.html#transaction-retries) in case of read/write [contention]({{ link_prefix }}performance-best-practices-overview.html#understanding-and-avoiding-transaction-contention). CockroachDB provides a [generic retry function](transaction-retry-error-reference.html#client-side-retry-handling) that runs inside a transaction and retries it as needed. The code sample below shows how it is used.
 {{site.data.alerts.end}}

_includes/v23.1/metric-names.md

@@ -8,8 +8,8 @@ Name | Description
 `capacity.reserved` | Capacity reserved for snapshots
 `capacity.used` | Used storage capacity
 `capacity` | Total storage capacity
-`changefeed.failures` | Total number of changefeed jobs which have failed
-`changefeed.running` | Number of currently running changefeeds, including sinkless
+`changefeed.failures` | Total number of [changefeed jobs](show-jobs.html#show-changefeed-jobs) which have failed.
+`changefeed.running` | Number of currently running changefeeds, including sinkless.
 `clock-offset.meannanos` | Mean clock offset with other nodes in nanoseconds
 `clock-offset.stddevnanos` | Std dev clock offset with other nodes in nanoseconds
 `cluster.preserve-downgrade-option.last-updated` | Unix timestamp of last updated time for cluster.preserve_downgrade_option
@@ -39,6 +39,10 @@ Name | Description
 `intentage` | Cumulative age of intents in seconds
 `intentbytes` | Number of bytes in intent KV pairs
 `intentcount` | Count of intent keys
+`jobs.changefeed.expired_pts_records` | Number of expired [protected timestamp](architecture/storage-layer.html#protected-timestamps) records owned by [changefeed jobs](show-jobs.html#show-changefeed-jobs).
+`jobs.{job_type}.currently_paused` | Number of `{job_type}` [jobs](show-jobs.html) currently considered paused. See the [`/_status/vars`](monitoring-and-alerting.html#prometheus-endpoint) endpoint for all job types.
+`jobs.{job_type}.protected_age_sec` | The age of the oldest [protected timestamp](architecture/storage-layer.html#protected-timestamps) record protecting `{job_type}` [jobs](show-jobs.html). See the [`/_status/vars`](monitoring-and-alerting.html#prometheus-endpoint) endpoint for all job types.
+`jobs.{job_type}.protected_record_count` | Number of [protected timestamp](architecture/storage-layer.html#protected-timestamps) records held by `{job_type}` [jobs](show-jobs.html). See the [`/_status/vars`](monitoring-and-alerting.html#prometheus-endpoint) endpoint for all job types.
 `jobs.row_level_ttl.num_active_spans` | Number of active spans the TTL job is deleting from
 `jobs.row_level_ttl.span_total_duration` | Duration for processing a span during row level TTL
 `keybytes` | Number of bytes taken up by keys
@@ -222,6 +226,8 @@ Name | Description
 `round-trip-latency` | Distribution of round-trip latencies with other nodes in nanoseconds
 `security.certificate.expiration.ca` | Expiration timestamp in seconds since Unix epoch for the CA certificate. 0 means no certificate or error.
 `security.certificate.expiration.node` | Expiration timestamp in seconds since Unix epoch for the node certificate. 0 means no certificate or error.
+`schedules.BACKUP.protected_age_sec` | The age of the oldest [protected timestamp](architecture/storage-layer.html#protected-timestamps) record protected by `BACKUP` schedules.
+`schedules.BACKUP.protected_record_count` | Number of [protected timestamp](architecture/storage-layer.html#protected-timestamps) records held by `BACKUP` schedules.
 `sql.bytesin` | Number of sql bytes received
 `sql.bytesout` | Number of sql bytes sent
 `sql.conns` | Number of active sql connections

_includes/v23.1/misc/database-terms.md

@@ -4,7 +4,7 @@
 The requirement that a transaction must change affected data only in allowed ways. CockroachDB uses "consistency" in both the sense of [ACID semantics](https://en.wikipedia.org/wiki/ACID) and the [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem), albeit less formally than either definition.
 
 ### Isolation
-The  degree to which a transaction may be affected by other transactions running at the same time. CockroachDB provides the [`SERIALIZABLE`](https://en.wikipedia.org/wiki/Serializability) isolation level, which is the highest possible and guarantees that every committed transaction has the same result as if each transaction were run one at a time.
+The degree to which a transaction may be affected by other transactions running at the same time. CockroachDB provides the [`SERIALIZABLE`](https://en.wikipedia.org/wiki/Serializability) isolation level, which is the highest possible and guarantees that every committed transaction has the same result as if each transaction were run one at a time.
 
 ### Consensus
 <a name="architecture-overview-consensus"></a> The process of reaching agreement on whether a transaction is committed or aborted. CockroachDB uses the [Raft consensus protocol](#architecture-raft). In CockroachDB, when a range receives a write, a quorum of nodes containing replicas of the range acknowledge the write. This means your data is safely stored and a majority of nodes agree on the database's current state, even if some of the nodes are offline.
@@ -17,8 +17,13 @@ The process of creating and distributing copies of data, as well as ensuring tha
 ### Transaction
 A set of operations performed on a database that satisfy the requirements of [ACID semantics](https://en.wikipedia.org/wiki/ACID). This is a crucial feature for a consistent system to ensure developers can trust the data in their database. For more information about how transactions work in CockroachDB, see [Transaction Layer](transaction-layer.html).
 
-### Contention
-<a name="architecture-overview-contention"></a> A state of conflict that occurs when a [transaction](../transactions.html) is unable to complete due to another concurrent or recent transaction attempting to write to the same data. When CockroachDB experiences transaction contention, it will [automatically attempt to retry the failed transaction](../transactions.html#automatic-retries) without involving the client (i.e., silently). If the automatic retry is not possible or fails, a [transaction retry error](../transaction-retry-error-reference.html) is emitted to the client. The client application can be configured to [retry the transaction](../transaction-retry-error-reference.html#client-side-retry-handling) after receiving such an error, and to [minimize transaction retry errors](../transaction-retry-error-reference.html#minimize-transaction-retry-errors) in the first place where possible.
+### Transaction contention
+<a name="architecture-overview-contention"></a> A [state of conflict](../performance-best-practices-overview.html#transaction-contention) that occurs when: 
+
+- A [transaction](../transactions.html) is unable to complete due to another concurrent or recent transaction attempting to write to the same data. This is also called *lock contention*.
+- A transaction is [automatically retried](../transactions.html#automatic-retries) because it could not be placed into a [serializable ordering](../demo-serializable.html) among all of the currently executing transactions. If the automatic retry is not possible or fails, a [*transaction retry error*](../transaction-retry-error-reference.html) is emitted to the client, requiring the client application to [retry the transaction](../transaction-retry-error-reference.html#client-side-retry-handling).
+
+Steps should be taken to [reduce transaction contention](../performance-best-practices-overview.html#reduce-transaction-contention) in the first place.
 
 ### Multi-active availability
 A consensus-based notion of high availability that lets each node in the cluster handle reads and writes for a subset of the stored data (on a per-range basis). This is in contrast to _active-passive replication_, in which the active node receives 100% of request traffic, and _active-active_ replication, in which all nodes accept requests but typically cannot guarantee that reads are both up-to-date and fast.

_includes/v23.1/misc/note-egress-perimeter-cdc-backup.md

@@ -1,3 +1,3 @@
 {{site.data.alerts.callout_info}}
-We recommend enabling Egress Perimeter Controls on {{ site.data.products.dedicated }} clusters to mitigate the risk of data exfiltration when accessing external resources, such as cloud storage for change data capture or backup and restore operations. See [Egress Perimeter Controls for CockroachDB Dedicated (Preview)](../cockroachcloud/egress-perimeter-controls.html) for detail and setup instructions.
-{{site.data.alerts.end}}
+Cockroach Labs recommends enabling Egress Perimeter Controls on {{ site.data.products.dedicated }} clusters to mitigate the risk of data exfiltration when accessing external resources, such as cloud storage for change data capture or backup and restore operations. See [Egress Perimeter Controls](../cockroachcloud/egress-perimeter-controls.html) for detail and setup instructions.
+{{site.data.alerts.end}}