Skip to content

Update the Compatibility changes of release-8.5.4 (#22233) #22316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ti-chi-bot merged 2 commits into from
Jan 13, 2026
Merged

Update the Compatibility changes of release-8.5.4 (#22233) #22316

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51fe1a5
Update the Compatibility changes of release-8.5.4 (#22233)
Frank945946 Jan 13, 2026
aec80e2
Update releases/release-8.5.4.md
hfxsd Jan 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 19 additions & 16 deletions releases/release-8.5.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,28 +61,31 @@

## 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) |

Check warning on line 83 in releases/release-8.5.4.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Ambiguous] Consider using a clearer word than 'a large number of' because it may cause confusion.

Raw Output:
{"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'a large number of' because it may cause confusion.", "location": {"path": "releases/release-8.5.4.md", "range": {"start": {"line": 83, "column": 308}}}, "severity": "INFO"}
| 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 | <ul><li>[`region-compact-check-interval`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-check-interval)</li><li>[`region-compact-check-step`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-check-step)</li><li>[`region-compact-min-tombstones`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-min-tombstones)</li><li>[`region-compact-tombstones-percent`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-tombstones-percent)</li><li>[`region-compact-min-redundant-rows`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-min-redundant-rows-new-in-v710)</li><li>[`region-compact-redundant-rows-percent`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-redundant-rows-percent-new-in-v710)</li></ul> | 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) |

Check failure on line 86 in releases/release-8.5.4.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Units] Put a nonbreaking space between the number and the unit in '01d'.

Raw Output:
{"message": "[PingCAP.Units] Put a nonbreaking space between the number and the unit in '01d'.", "location": {"path": "releases/release-8.5.4.md", "range": {"start": {"line": 86, "column": 1148}}}, "severity": "ERROR"}
| TiKV | [`gc.auto-compaction`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#gcauto-compaction) configuration group: <ul><li>[`gc.auto-compaction.check-interval`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#check-interval-new-in-v757-and-v854)</li><li>[`gc.auto-compaction.tombstone-num-threshold`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#tombstone-num-threshold-new-in-v757-and-v854)</li><li>[`gc.auto-compaction.tombstone-percent-threshold`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#tombstone-percent-threshold-new-in-v757-and-v854)</li><li>[`gc.auto-compaction.redundant-rows-threshold`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#redundant-rows-threshold-new-in-v757-and-v854)</li><li>[`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)</li><li>[`gc.auto-compaction.bottommost-level-force`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#bottommost-level-force-new-in-v757-and-v854) </li></ul>| Newly added | This configuration group controls the automatic compaction behavior. [#18727](https://github.com/tikv/tikv/issues/18727) [@v01dstar](https://github.com/v01dstar) |

Check failure on line 87 in releases/release-8.5.4.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Units] Put a nonbreaking space between the number and the unit in '01d'.

Raw Output:
{"message": "[PingCAP.Units] Put a nonbreaking space between the number and the unit in '01d'.", "location": {"path": "releases/release-8.5.4.md", "range": {"start": {"line": 87, "column": 1250}}}, "severity": "ERROR"}
| 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

Expand Down
Loading