diff --git a/releases/release-8.5.4.md b/releases/release-8.5.4.md index c50e3d3a706a8..6b74293f4c0b7 100644 --- a/releases/release-8.5.4.md +++ b/releases/release-8.5.4.md @@ -61,28 +61,31 @@ Quick access: [Quick start](https://docs.pingcap.com/tidb/v8.5/quick-start-with- ## Compatibility changes -### System variables - -- Change the default value of the [`tidb_mpp_store_fail_ttl`](https://docs.pingcap.com/tidb/v8.5/system-variables/#tidb_mpp_store_fail_ttl) system variable from `60s` to `0s`. This means TiDB no longer needs to wait before sending queries to newly started TiFlash nodes, as delays are no longer necessary to prevent query failures. [#61826](https://github.com/pingcap/tidb/issues/61826) @[gengliqi](https://github.com/gengliqi) +Newly created v8.5.3 clusters can be smoothly upgraded to v8.5.4. However, v8.5.4 introduces several **default value changes and behavior adjustments** for system variables and configuration parameters. Before upgrading, pay attention to the following: -- Starting from v8.5.4, the [`tidb_replica_read`](https://docs.pingcap.com/tidb/v8.5/system-variables/#tidb_replica_read-new-in-v40) system variable only takes effect on read-only SQL statements. This change improves data read safety and reduces overlaps with other features. [#62856](https://github.com/pingcap/tidb/issues/62856) @[you06](https://github.com/you06) +- Most changes are safe for routine upgrades. However, if your cluster has undergone performance tuning, such as customized TiFlash and TiKV compaction configurations, read this section carefully. +- Some legacy TiKV configuration items are deprecated in v8.5.4 and no longer recommended. As a replacement, it is recommended that you use the new TiKV configuration group provided in this section. -- Add the following system variables: +### System variables - - [`tidb_opt_enable_no_decorrelate_in_select`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_opt_enable_no_decorrelate_in_select-new-in-v854): controls whether to decorrelate subqueries in the `SELECT` list. The default value is `OFF`. [#51116](https://github.com/pingcap/tidb/issues/51116) @[terry1purcell](https://github.com/terry1purcell) - - [`tidb_opt_enable_semi_join_rewrite`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_opt_enable_semi_join_rewrite-new-in-v854): controls whether to rewrite `EXISTS` subqueries. The default value is `OFF`. [#44850](https://github.com/pingcap/tidb/issues/44850) @[terry1purcell](https://github.com/terry1purcell) - - [`tidb_stats_update_during_ddl`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_stats_update_during_ddl-new-in-v854): controls whether to enable the embedded Analyze for DDL. The default value is `OFF`. [#57948](https://github.com/pingcap/tidb/issues/57948) @[terry1purcell](https://github.com/terry1purcell) @[AilinKid](https://github.com/AilinKid) +| Variable | Change type | Description | +|---------|------|-------------| +| [`tidb_mpp_store_fail_ttl`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_mpp_store_fail_ttl) | Modified | Changes the default value from `60s` to `0s`. This means TiDB no longer needs to wait before sending queries to newly started TiFlash nodes, as delays are no longer necessary to prevent query failures. [#61826](https://github.com/pingcap/tidb/issues/61826) [@gengliqi](https://github.com/gengliqi) | +| [`tidb_replica_read`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_replica_read-new-in-v40) | Modified | Starting from v8.5.4, this variable only takes effect on read-only SQL statements. This improves data read safety and reduces overlaps with other features. [#62856](https://github.com/pingcap/tidb/issues/62856) [@you06](https://github.com/you06) | +| [`tidb_opt_enable_no_decorrelate_in_select`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_opt_enable_no_decorrelate_in_select-new-in-v854) | Newly added | Controls whether to decorrelate subqueries in the `SELECT` list. The default value is `OFF`. [#51116](https://github.com/pingcap/tidb/issues/51116) [@terry1purcell](https://github.com/terry1purcell) | +| [`tidb_opt_enable_semi_join_rewrite`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_opt_enable_semi_join_rewrite-new-in-v854) | Newly added | Controls whether to rewrite `EXISTS` subqueries. The default value is `OFF`. [#44850](https://github.com/pingcap/tidb/issues/44850) [@terry1purcell](https://github.com/terry1purcell) | +| [`tidb_stats_update_during_ddl`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_stats_update_during_ddl-new-in-v854) | Newly added | Controls whether to enable [`ANALYZE` Embedded in DDL Statements](https://docs.pingcap.com/tidb/v8.5/ddl_embedded_analyze). The default value is `OFF`. When it is enabled, the `ADD INDEX` DDL statement collects statistics for the new index during execution, allowing the optimizer to use the index immediately after it is added. Note that enabling this variable might increase DDL execution time when adding indexes to large tables. [#57948](https://github.com/pingcap/tidb/issues/57948) [@terry1purcell](https://github.com/terry1purcell) [@AilinKid](https://github.com/AilinKid) | ### Configuration parameters -- Deprecate the following TiKV configuration items and replace them with the new [`gc.auto-compaction`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file/#gcauto-compaction) configuration group, which controls automatic compaction behavior. [#18727](https://github.com/tikv/tikv/issues/18727) @[v01dstar](https://github.com/v01dstar) - - - Deprecated configuration items: [`region-compact-check-interval`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-check-interval), [`region-compact-check-step`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-check-step), [`region-compact-min-tombstones`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-min-tombstones), [`region-compact-tombstones-percent`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-tombstones-percent), [`region-compact-min-redundant-rows`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-min-redundant-rows-new-in-v710), and [`region-compact-redundant-rows-percent`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-redundant-rows-percent-new-in-v710). - - New configuration items: [`gc.auto-compaction.check-interval`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#check-interval-new-in-v757-and-v854), [`gc.auto-compaction.tombstone-num-threshold`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#tombstone-num-threshold-new-in-v757-and-v854), [`gc.auto-compaction.tombstone-percent-threshold`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#tombstone-percent-threshold-new-in-v757-and-v854), [`gc.auto-compaction.redundant-rows-threshold`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#redundant-rows-threshold-new-in-v757-and-v854), [`gc.auto-compaction.redundant-rows-percent-threshold`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#redundant-rows-percent-threshold-new-in-v757-and-v854), and [`gc.auto-compaction.bottommost-level-force`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#bottommost-level-force-new-in-v757-and-v854). - -- Modify the default value of the TiKV configuration item [`max-manifest-file-size`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#max-manifest-file-size) from `128MiB` to `256MiB` to avoid frequent manifest file compactions that could affect overall performance when a single TiKV node contains a large number of SST files. [#18996](https://github.com/tikv/tikv/issues/18996) @[glorv](https://github.com/glorv) - -- Add a TiFlash configuration item [`flash.graceful_wait_shutdown_timeout`](https://docs.pingcap.com/tidb/v8.5/tiflash-configuration#graceful_wait_shutdown_timeout-new-in-v854), which controls the maximum wait time when shutting down a TiFlash server. The default value is `600` seconds. During this period, TiFlash continues running unfinished MPP tasks but does not accept new ones. If all running MPP tasks finish before this timeout, TiFlash shuts down immediately; otherwise, it is forcibly shut down after the wait time expires. [#10266](https://github.com/pingcap/tiflash/issues/10266) @[gengliqi](https://github.com/gengliqi) +| Configuration file or component | Configuration parameter | Change type | Description | +|--------------------------------|--------------------------|------|-------------| +| TiKV | [`rocksdb.max-manifest-file-size`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#max-manifest-file-size) | Modified | Changes the default value from `128MiB` to `256MiB` to avoid frequent manifest file compactions that could affect overall performance when a single TiKV node contains a large number of SST files. [#18889](https://github.com/tikv/tikv/issues/18889) [@glorv](https://github.com/glorv) | +| TiKV | [`server.grpc-raft-conn-num`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#grpc-raft-conn-num) | Modified | Changes the default value from `1` to `MAX(1, MIN(4, CPU cores / 8))`, which enables gRPC-related thread settings to adapt to the number of CPU cores. When the number of CPU cores equals or exceeds 32, the maximum default number of connections is 4. [#18806](https://github.com/tikv/tikv/issues/18806) [@LykxSassinator](https://github.com/LykxSassinator) | +| TiKV | [`server.grpc-concurrency`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#grpc-concurrency) | Modified | Changes the default value from `5` to `grpc-raft-conn-num * 3 + 2`, which enables gRPC-related thread settings to adapt to the number of CPU cores. [#18806](https://github.com/tikv/tikv/issues/18806) [@LykxSassinator](https://github.com/LykxSassinator) | +| TiKV | | Deprecated | These configuration items are replaced by the [`gc.auto-compaction`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#gcauto-compaction) configuration group, which controls the automatic compaction behavior. [#18727](https://github.com/tikv/tikv/issues/18727) [@v01dstar](https://github.com/v01dstar) | +| TiKV | [`gc.auto-compaction`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#gcauto-compaction) configuration group: | Newly added | This configuration group controls the automatic compaction behavior. [#18727](https://github.com/tikv/tikv/issues/18727) [@v01dstar](https://github.com/v01dstar) | +| TiFlash | [`flash.graceful_wait_shutdown_timeout`](https://docs.pingcap.com/tidb/v8.5/tiflash-configuration#graceful_wait_shutdown_timeout-new-in-v854) | Newly added | Controls the maximum wait time (in seconds) for a graceful TiFlash shutdown. The default value is `600`. When shutting down TiFlash, it continues executing unfinished MPP tasks but no longer accepts new MPP tasks. If all MPP tasks finish before the timeout, TiFlash shuts down immediately; otherwise, it is forcibly shut down after the timeout expires. [#10266](https://github.com/pingcap/tiflash/issues/10266) [@gengliqi](https://github.com/gengliqi) | ### MySQL compatibility