Add SQL grammar anchors to make linkcheck pass

src/current/_includes/releases/v24.1/v24.1.0-alpha.5.md

@@ -6,72 +6,64 @@ Release Date: April 1, 2024
 
 <h3 id="v24-1-0-alpha-5-{{-site.data.products.enterprise-}}-edition-changes">{{ site.data.products.enterprise }} edition changes</h3>
 
-- [Changefeeds]({% link v24.1/change-data-capture-overview.md %}) now default to evenly distributing their work across all replicas, including followers, regardless of leaseholder placement. To disable this behavior, set the [cluster setting]({% link v24.1/cluster-settings.md %}) `changefeed.balanced_distribution.enabled` to `false`. If disabled, changefeed planning reverts to its previous behavior for distributing work. [#120077][#120077]
-- When [physical cluster replication]({% link v24.1/physical-cluster-replication-overview.md %}) is enabled, the output of the `SHOW VIRTUAL CLUSTER ... WITH REPLICATION STATUS` command now displays replication lag. [#120782][#120782]
-- When [physical cluster replication]({% link v24.1/physical-cluster-replication-overview.md %}) is enabled, the output of the `SHOW VIRTUAL CLUSTER WITH REPLICATION STATUS to 1` command has changed:
-    - The output no longer displays `replication_job_id` or `service_mode` return fields.
-    - The `data_state` field has been renamed to `status`.
-    - The fields that are displayed are now ordered as follows: `retained_time`, `replicated_time`, `replication_lag`, `cutover_time`, `status`. [#120782][#120782]
+- Changefeeds now use the BulkOracle for planning, which distributes work evenly across all replica in the locality filter, including followers if enabled. This is enabled by default with the cluster setting `changefeed.balanced_distribution.enabled`. If disabled, changefeed planning reverts to its previous bin packing oracle. [#120077][#120077]
 
 <h3 id="v24-1-0-alpha-5-sql-language-changes">SQL language changes</h3>
 
-- You can now specify a condition for the [PL/pgSQL statements]({% link v24.1/plpgsql.md %}) `EXIT` and `CONTINUE`. [#120686][#120686]
-- A [stored procedure]({% link v24.1/stored-procedures.md %}) can now invoke another stored procedure using a [`CALL` statement]({% link v24.1/call.md %}). [#120674][#120674]
-- You can now use a [`SET TRANSACTION`]({% link v24.1/set-transaction.md %}) statement within a [PL/pgSQL stored procedure]({% link v24.1/plpgsql.md %}) to configure the transaction isolation level, timestamp, or priority, or to set the transaction to read-only. A `SET TRANSACTION` statement must immediately follow a `COMMIT` or `ROLLBACK`, with no other statements or block boundaries between them. [#120456][#120456]
-- The new [session variable]({% link v24.1/session-variables.md %}) `optimizer_use_virtual_computed_column_stats`, when enabled, configures the [cost-based optimizer]({% link v24.1/cost-based-optimizer.md %}) to use [table statistics]({% link v24.1/show-statistics.md %}) on virtual computed columns. [#120668][#120668]
-- An [identity column]({% link v24.1/create-table.md %}#identity-columns) can now drop the `IDENTITY` constraint and related sequence using the following SQL statement:
-
-    {% include_cached copy-clipboard.html %}
-    ~~~ sql
-    ALTER TABLE {table_name} ALTER COLUMN {column_name} DROP IDENTITY [IF EXISTS];
-    ~~~
-
-    `IF EXISTS` is optional, and skips the command if the column is not an identity column.  [#119263][#119263]
-
-- A shared lock that is acquired explicitly using [`SELECT FOR SHARE`]({% link v24.1/select-for-update.md %}) or implicitly by a [read-committed transaction]({% link v24.1/read-committed.md %}), can now be re-acquired with higher strength by either using a [`SELECT FOR UPDATE`]({% link v24.1/select-for-update.md %}) statement or by writing to the key. [#119671][#119671]
-- [Stored procedures]({% link v24.1/stored-procedures.md %}) now support `OUT` and `INOUT` parameter classes. [#120851][#120851]
-- The [PL/pgSQL]({% link v24.1/plpgsql.md %}) `EXIT` and `CONTINUE` statements can now use labels to specify which loop or block is the target. [#120733][#120733]
+- It is now possible to specify a condition for the PL/pgSQL statemenets `EXIT` and `CONTINUE`. [#120686][#120686]
+- Stored procedures can now invoke other stored procedures via `CALL` statements. [#120674][#120674]
+- PL/pgSQL stored procedures now allow usage of the `SET TRANSACTION` statement. This allows setting the transaction isolation level, timestamp, or priority, as well as setting the transaction to read-only. `SET TRANSACTION` statements must immediately follow a `COMMIT` or `ROLLBACK`, without interruption by other statements or block boundaries. [#120456][#120456]
+- Add new session variable `optimizer_use_virtual_computed_column_stats`. When this variable is enabled, the optimizer will make use of table statistics on virtual computed columns. [#120668][#120668]
+- Identity Columns can drop the Identity constraint and related sequence by running: -'ALTER TABLE t ALTER COLUMN c DROP IDENTITY'.  Option 'IF EXISTS' can be added to skip the command if the column in not an identity: -'ALTER TABLE t ALTER COLUMN c DROP IDENTITY [ IF EXISTS ]'. [#119263][#119263]
+- Shared locks (acquired using SELECT FOR SHARE or implicitly by read committed transactions) can now be re-acquired with higher strength (using SELECT FOR UPDATE or by writing to the key). [#119671][#119671]
+- Users will see the following changes in their generated statement fingerprints from sql stats: - lists with only literals/placeholders and similar subexpressions are shortened to their first item followed by "__more__", e.g. - constants and placeholders are all replaced with the same character, an underscore `_` ``` SELECT * FROM foo WHERE f IN (1, $1, 1+2) -> SELECT * FROM foo WHERE f IN (_, __more__) ``` [#120507][#120507]
+- OUT and INOUT parameter classes are now supported in stored procedures. [#120851][#120851]
+- SHOW VIRTUAL CLUSTER ... WITH REPLICATION STATUS now displays the PCR replication lag. [#120782][#120782]
+- This patch refactors the output of SHOW VC WITH REPLICATION STATUS to 1) remove the replication_job_id, service_mode return fields; 2) reorder to following columns to: retained_time, replicated_time, replication_lag, cutover_time; 3) rename the data_state field status and moves to the last return column. [#120782][#120782]
+- The PL/pgSQL `EXIT` and `CONTINUE` statements can now specify which loop or block is the target via labels. [#120733][#120733]
 
 <h3 id="v24-1-0-alpha-5-operational-changes">Operational changes</h3>
 
-- You can now enable asynchronous buffering of `file-group` [log sinks]({% link v24.1/configure-logs.md %}) using the `buffering` [configuration options]({% link v24.1/configure-logs.md %}#log-buffering-for-network-sinks) either by default or to an individual `file-group`. The `buffering` configuration option is incompatible with the `buffered-writes` configuration option. To try the `buffering` option, you must set `buffered-writes: false`. Cockroach Labs recommends setting `max-staleness` to `1s` and `flush-trigger-size` to `256KiB`. [#120428][#120428]
-- A minimum [Raft scheduler]({% link v24.1/architecture/replication-layer.md %}#raft) concurrency is now enforced per store so that nodes with many stores do not spread workers too thin. This helps to avoid high scheduler latency across replicas on a store when load is imbalanced. [#120162][#120162]
-- The new [metrics]({% link v24.1/metrics.md %}) `kv.split.estimated_stats` and `kv.split.total_bytes_estimates` track the number of splits that produce [MVCC]({% link v24.1/architecture/storage-layer.md %}#mvcc) statistic estimates and the total bytes of estimates produced. [#119894][#119894]
-- The new [cluster setting]({% link v24.1/cluster-settings.md %}) `storage.sstable.compression_algorithm` configures the compression algorithm used when compressing sstable blocks. [#120784][#120784]
-- The new [cluster setting]({% link v24.1/cluster-settings.md %}) `kv.dist_sender.proxy.enabled`, which is enabled by default, causes proxy requests to be routed through a follower replica when the leaseholder is unavailable. [#117340][#117340]
-- The new startup flag `--wal-failover` allows you to explicitly set the path for WAL failover of a single-store node. [#120783][#120783]
-- Cluster virtualization is now enabled using either of the new startup flags `--virtualized` or `--virtualized-empty` instead of the `--config-profile` flag. [#120813][#120813]
-- The following metrics, which track the SQL statistics subsystem's task to flush in-memory statistics to persisted storage, are now more consistent with other metrics used in the subsystem.
-    - `sql.stats.flushes.successful`: Number of times SQL statistics have been flushed successfully to persistent storage.
-    - `sql.stats.flushes.failed`: Number of attempted SQL statistics flushes that failed with errors.
-    - `sql.stats.flush.latency`: The latency of attempted SQL statistics flushes to persistent storage, including both successes and failures. [#120709][#120709]
-- The following new [metrics]({% link v24.1/metrics.md %}) track the number and outcome of proxy requests when `kv.dist_sender.proxy.enabled` is set to `true`:
-    - `distsender.rpc.proxy.sent`
-    - `distsender.rpc.proxy.err`
-    - `distsender.rpc.proxy.forward.sent`
-    - `distsender.rpc.proxy.forward.err`
-
-  Cockroach Labs recommends monitoring and alerting on `distsender.rpc.proxy.sent`, because it indicates a possible network partition. [#120239][#120239]
-- The `provisioned-rate` field of a node's store specification can no longer be used to add constraints for the disk name or bandwidth. By default, bandwidth is constrained according to the [cluster setting]({% link v24.1/cluster-settings.md %}) `kv.store.admission.provisioned_bandwidth`. To override this setting for a specific node, the storage specification must contain `provisioned-rate=bandwidth={bandwidth-bytes/s}`. [#120895][#120895]
-- Removal of the [cluster setting]({% link v24.1/cluster-settings.md %}) `kv.rangefeed.scheduler.enabled`, which was announced in [v24.1.0-alpha.1](https://www.cockroachlabs.com/docs/releases/v24.1.html#v24-1-0-alpha-1), has been reverted, and the cluster setting is reinstated. [#121164][#121164]
+- Users have the ability to update their log configuration to enable asynchronous buffering of `file-group` log sinks via the `buffering` [configuration options](https://www.cockroachlabs.com/docs/stable/configure-logs#log-buffering-for-network-sinks).  The `buffering` configuration can be applied to `file-defaults` or individual `file-groups` as needed.  Note however that `buffering` and `buffered-writes` are incompatible for the time being. If you'd like to try the `buffering` option on a file log sink, it's necessary to explicitly set `buffered-writes: false`. For example: ``` file-defaults:   buffered-writes: false   buffering:     max-staleness: 1s     flush-trigger-size: 256KiB     max-buffer-size: 50MiB ``` We recommend a `max-staleness: 1s` and `flush-trigger-size: 256KiB` when using this feature with file log sinks. [#120428][#120428]
+- Metrics used to track the SQL stats subsystem's task that flushes in-memory stats to persisted storage have been reworked slightly to be more consistent with other metrics used in the subsystem. The metrics are:  - `sql.stats.flushes.successful`: Number of times SQL Stats are flushed    successfully to persistent storage - `sql.stats.flushes.failed`: Number of attempted SQL Stats flushes that    failed with errors - `sql.stats.flush.latency`: The latency of SQL Stats flushes to    persistent storage. Includes failed flush attempts [#120709][#120709]
+- A minimum Raft scheduler concurrency is now enforced per store so that nodes with many stores do not spread workers too thin. This avoids high scheduler latency across replicas on a store when load is imbalanced. [#120162][#120162]
+- Two new metrics (kv.split.estimated_stats and kv.split.total_bytes_estimates) added to track the number of splits that produce MVCC stats estimates, and the total bytes of estimates produced. [#119894][#119894]
+- Add `storage.sstable.compression_algorithm` cluster setting that configures the compression algorithm to use when compressing sstable blocks. [#120784][#120784]
+- This PR adds an additional setting kv.dist_sender.proxy.enabled which is defaulted to true. When it is enabled, proxy requests will be routed through a follower replica when the leaseholder is unavailable. [#117340][#117340]
+- Adds an additional option to the new (in 24.1) --wal-failover CLI flag allowing an operator to specify an explicit path for WAL failover for single-store nodes. [#120783][#120783]
+- Cluster virtualization is now configured at cluster startup via flags (--virtualized or --virtualized-empty) passed to `cocroach init` rather than via the previously available --config-profile flag passed to `cockroach start`. [#120813][#120813]
+- Adds four new metrics: distsender.rpc.proxy.sent, distsender.rpc.proxy.err, distsender.rpc.proxy.forward.sent, distsender.rpc.proxy.forward.err to track the number and outcome of proxy requests. Operators should monitor and alert on `distsender.rpc.proxy.sent` as it indicates there is likely a network partition in the system. [#120239][#120239]
+- The provisioned-rate field, if specified, should no longer accept a disk-name or an optional bandwidth field. To use the disk bandwidth constraint the store-spec must contain provisioned-rate=bandwidth=<bandwidth-bytes/s>, otherwise the cluster setting kv.store.admission.provisioned_bandwidth will be used. [#120895][#120895]
 
 <h3 id="v24-1-0-alpha-5-db-console-changes">DB Console changes</h3>
 
-- In generated statement fingerprints in the DB Console [**Statements** page]({% link v24.1/ui-statements-page.md %}), lists with only literals or placeholders or similar subexpressions are shortened to their first item followed by "__more__". [#120507][#120507]
+- Adds two new graphs to the network page. [#120239][#120239]
 
 <h3 id="v24-1-0-alpha-5-bug-fixes">Bug fixes</h3>
 
-- Fixed a bug introduced in v23.2 that could cause a [PL/pgSQL]({% link v24.1/plpgsql.md %}) routine to return incorrect results when the routine included:
-    1. At least one parameter.
-    1. An `IF` statement with one leak-proof branch and one branch with side effects. [#120451][#120451]
-- Fixed a rare bug where a `BACKUP` command issued shortly after an [`ALTER TABLE {table_name} SET (exclude_data_from_backup = true)`]({% link v24.1/take-full-and-incremental-backups.md %}#exclude-a-tables-data-from-backups) could exclude data from an unrelated table from the backup. [#120188][#120188]
-- Fixed a behavior where a memory exhaustion error during a schema change was treated as a permanent failure and reverted. Such schema changes are now retried instead of reverted. [#120806][#120806]
-- Fixed a bug where the `attname` for a dropped column was not correctly padded with 8 `.` characters to be compatible with PostgreSQL. [#120861][#120861]
+- Fixed a bug introduced in v23.2 that could cause a PL/pgSQL routine to return incorrect results when there was at least one parameter, and an `IF` statement with one leak-proof branch, and one branch with side effects. [#120451][#120451]
+- Fix a rare condition in which a BACKUP taken shortly after ALTER TABLE <TABLE> SET (exclude_data_from_backup = true) could result in data from an unrelated table being excluded from a backup. [#120188][#120188]
+- Memory exhaustion errors which can occur during schema changes are no longer considered to be permanent failures. These schema changes will now be retried rather than reverted.  Fixes: #120807 [#120806][#120806]
+- Attname for dropped columns is now properly padded with 8 '.' to match PG. [#120861][#120861]
 
 <h3 id="v24-1-0-alpha-5-performance-improvements">Performance improvements</h3>
 
-- Splits no longer hold latches for time proportional to the range size while computing MVCC statistics. Instead, MVCC statistics are pre-computed before the critical section of the split. As a side effect, the resulting statistics are no longer 100% accurate because they may correctly distribute writes concurrent with the split. To mitigate against this potential inaccuracy, and to prevent the statistics from drifting after successive splits, the existing stored statistics are re-computed and corrected if needed during the non-critical section of the split. [#119894][#119894]
-- The [cost-based optimizer]({% link v24.1/cost-based-optimizer.md %}) now generates more efficient query plans for some queries with `OFFSET` clauses. [#121160][#121160]
+- Splits no longer hold latches for time proportional to the range size while computing MVCC stats. Instead, MVCC stats are pre-computed before the critical section of the split. As a side effect, the resulting stats are no longer 100% accurate because they may correctly distribute writes concurrent with the split. To mitigate this, and to prevent the stats from drifting after successive splits, the existing stored stats are re-computed and corrected (if needed) as part of the non-critical section of the split. [#119894][#119894]
+- The optimizer now generates more efficient query plans for some queries with `OFFSET` clauses. [#121160][#121160]
+
+<h3 id="v24-1-0-alpha-5-miscellaneous">Miscellaneous</h3>
+
+<h4 id="v24-1-0-alpha-5-changes-without-release-note-annotation">Changes without release note annotation</h4>
+
+- [#121164][#121164] [d8f53d532][d8f53d532] Revert "rangefeed: unconditionally use rangefeed scheduler" (Erik Grinaker <[email protected]>)
+- [#121164][#121164] [8eb7ca994][8eb7ca994] Revert "rangefeed: unconditionally use rangefeed scheduler" (Erik Grinaker <[email protected]>)
+- [#121164][#121164] [40f4dc382][40f4dc382] Revert "rangefeed: unconditionally use rangefeed scheduler" (Erik Grinaker <[email protected]>)
+- [#121023][#121023] [688d6abf4][688d6abf4] roachtest: add disk-stalled/wal-failover/among-stores test (Jackson Owens <[email protected]>)
+- [#120846][#120846] [ae8043c90][ae8043c90] sql/catalog: TestKVWriterMatchesIEWriter fails intermittently (Faizan Qazi <[email protected]>)
+
+<h3 id="v24-1-0-alpha-5-doc-updates">Doc updates</h3>
+
+{% comment %}Docs team: Please add these manually.{% endcomment %}
 
 <div class="release-note-contributors" markdown="1">
 
@@ -81,6 +73,10 @@ This release includes 157 merged PRs by 44 authors.
 We would like to thank the following contributors from the CockroachDB community:
 
 - Andrew Delph
+- David Hartunian (first-time contributor, CockroachDB team member)
+- Jasmine Sun
+- Kevin Cao (first-time contributor, CockroachDB team member)
+- Rachael Harding (first-time contributor, CockroachDB team member)
 
 </div>
 
@@ -113,3 +109,8 @@ We would like to thank the following contributors from the CockroachDB community
 [#121023]: https://github.com/cockroachdb/cockroach/pull/121023
 [#121160]: https://github.com/cockroachdb/cockroach/pull/121160
 [#121164]: https://github.com/cockroachdb/cockroach/pull/121164
+[40f4dc382]: https://github.com/cockroachdb/cockroach/commit/40f4dc382
+[688d6abf4]: https://github.com/cockroachdb/cockroach/commit/688d6abf4
+[8eb7ca994]: https://github.com/cockroachdb/cockroach/commit/8eb7ca994
+[ae8043c90]: https://github.com/cockroachdb/cockroach/commit/ae8043c90
+[d8f53d532]: https://github.com/cockroachdb/cockroach/commit/d8f53d532