Skip to content

Update the Compatibility changes of release-8.5.4 #22233

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

Open
Frank945946 wants to merge 2 commits into
base: master
Choose a base branch
from
+21 −14
Open

Update the Compatibility changes of release-8.5.4 #22233

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9cb4634
Update the Compatibility changes of release-8.5.4
Frank945946 Dec 24, 2025
22fb72a
Update release-8.5.4.md
Frank945946 Dec 24, 2025
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: 21 additions & 14 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,26 +61,33 @@

## Compatibility changes

### System variables
## Highlights

- 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, this release includes **default value changes and behavior adjustments** for several system variables and configuration parameters that require attention.
- Most changes are **safe for general upgrades**, but **clusters with customized performance tuning, TiFlash, or TiKV compaction settings should review this section carefully**.
- Some legacy configuration items are **deprecated and no longer recommended**, and you should **migrate to the new configuration groups**.

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

- Add the following system variables:
| Variable | Type | Default Value | Description | PR | Contributor |
|--------|------|---------------|-------------|----|-------------|
| [`tidb_mpp_store_fail_ttl`](https://docs.pingcap.com/tidb/v8.5/system-variables/#tidb_mpp_store_fail_ttl) | Default Value Change | `0` | Default value changed from `60s` → `0s`. TiDB no longer waits 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) | Behavior Change | `leader` | 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) | New | `OFF` | Controls whether to decorrelate subqueries in the `SELECT` list. | [#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) | New | `OFF` | Controls whether to rewrite `EXISTS` subqueries. | [#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) | New | `OFF` | When enabled, `ADD INDEX` collects statistics during DDL, allowing immediate optimizer usage. May increase DDL time on large tables. | [#57948](https://github.com/pingcap/tidb/issues/57948) | [@terry1purcell](https://github.com/terry1purcell), [@AilinKid](https://github.com/AilinKid) |

- [`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)
## Configuration Parameters
Comment on lines +64 to +80
Copy link

@gemini-code-assist gemini-code-assist bot Dec 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

The heading levels and casing should be adjusted for consistency and to follow the style guide. Highlights, System Variables, and Configuration Parameters should be level-3 headings under Compatibility changes. Also, headings should use sentence case.

As per the style guide:

  • Heading Hierarchy (Line 39): Use proper heading hierarchy. These sections are subsections of 'Compatibility changes' and should be level 3 (###).
  • Sentence Case (Line 32): Use sentence case for headings (e.g., ## Configure the cluster). 'System Variables' and 'Configuration Parameters' should be 'System variables' and 'Configuration parameters'.
Suggested change
## Highlights
- 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, this release includes **default value changes and behavior adjustments** for several system variables and configuration parameters that require attention.
- Most changes are **safe for general upgrades**, but **clusters with customized performance tuning, TiFlash, or TiKV compaction settings should review this section carefully**.
- Some legacy configuration items are **deprecated and no longer recommended**, and you should **migrate to the new configuration groups**.
- 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)
## System Variables
- Add the following system variables:
| Variable | Type | Default Value | Description | PR | Contributor |
|--------|------|---------------|-------------|----|-------------|
| [`tidb_mpp_store_fail_ttl`](https://docs.pingcap.com/tidb/v8.5/system-variables/#tidb_mpp_store_fail_ttl) | Default Value Change | `0` | Default value changed from `60s` → `0s`. TiDB no longer waits 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) | Behavior Change | `leader` | 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) | New | `OFF` | Controls whether to decorrelate subqueries in the `SELECT` list. | [#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) | New | `OFF` | Controls whether to rewrite `EXISTS` subqueries. | [#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) | New | `OFF` | When enabled, `ADD INDEX` collects statistics during DDL, allowing immediate optimizer usage. May increase DDL time on large tables. | [#57948](https://github.com/pingcap/tidb/issues/57948) | [@terry1purcell](https://github.com/terry1purcell), [@AilinKid](https://github.com/AilinKid) |
- [`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)
## Configuration Parameters
### Highlights
- Newly created v8.5.3 clusters can be smoothly upgraded to v8.5.4. However, this release includes **default value changes and behavior adjustments** for several system variables and configuration parameters that require attention.
- Most changes are **safe for general upgrades**, but **clusters with customized performance tuning, TiFlash, or TiKV compaction settings should review this section carefully**.
- Some legacy configuration items are **deprecated and no longer recommended**, and you should **migrate to the new configuration groups**.
### System variables
| Variable | Type | Default Value | Description | PR | Contributor |
|--------|------|---------------|-------------|----|-------------|
| [`tidb_mpp_store_fail_ttl`](https://docs.pingcap.com/tidb/v8.5/system-variables/#tidb_mpp_store_fail_ttl) | Default Value Change | `0` | Default value changed from `60s` → `0s`. TiDB no longer waits 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) | Behavior Change | `leader` | 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) | New | `OFF` | Controls whether to decorrelate subqueries in the `SELECT` list. | [#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) | New | `OFF` | Controls whether to rewrite `EXISTS` subqueries. | [#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) | New | `OFF` | When enabled, `ADD INDEX` collects statistics during DDL, allowing immediate optimizer usage. May increase DDL time on large tables. | [#57948](https://github.com/pingcap/tidb/issues/57948) | [@terry1purcell](https://github.com/terry1purcell), [@AilinKid](https://github.com/AilinKid) |
### Configuration parameters
References
  1. Use proper heading hierarchy (no jumping from ## to ####). (link)
  2. Use sentence case for headings (e.g., ## Configure the cluster). (link)


### Configuration parameters
| Configuration Parameter | Type | Default Value | Description | PR | Contributor |
|-------------------------|------|---------------|-------------|----|-------------|
| [`max-manifest-file-size`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#max-manifest-file-size) | Default Value Change | `256 MiB` | Increases the default value of `rocksdb.max-manifest-file-size` from `128 MiB` → `256 MiB`. This may affect users who rely on the previous default value. | [#18889](https://github.com/tikv/tikv/issues/18889) | [@glorv](https://github.com/glorv) |
| [`grpc-raft-conn-num`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#grpc-raft-conn-num) | Default Value Change | CPU core num / 8 | The default value is updated to `MAX(1, MIN(4, CPU core num / 8))`. When the number of CPU cores is ≥ 32, the maximum default number of connections is capped at 4. | [#18806](https://github.com/tikv/tikv/issues/18806) | [@LykxSassinator](https://github.com/LykxSassinator) |
| [`grpc-concurrency`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#grpc-concurrency) | Default Value Change | `grpc-raft-conn-num * 3 + 2` | The default value is calculated as `grpc_raft_conn_num * 3 + 2`. | [#18806](https://github.com/tikv/tikv/issues/18806) | [@LykxSassinator](https://github.com/LykxSassinator) |
| [`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), [`region-compact-redundant-rows-percent`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file#region-compact-redundant-rows-percent-new-in-v710) | Deprecated | – | Deprecated and replaced by the [`gc.auto-compaction`](https://docs.pingcap.com/tidb/v8.5/tikv-configuration-file/#gcauto-compaction) configuration group for automatic compaction control. | [#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": 1065}}}, "severity": "ERROR"}

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.EnDash] Use an em dash ('—') instead of en dash ('–').

Raw Output:
{"message": "[PingCAP.EnDash] Use an em dash ('—') instead of en dash ('–').", "location": {"path": "releases/release-8.5.4.md", "range": {"start": {"line": 87, "column": 815}}}, "severity": "ERROR"}
| [`gc.auto-compaction.check-interval`](https://docs.pingcap.com/tidb/stable/tikv-configuration-file/#check-interval-new-in-v757), [`gc.auto-compaction.tombstone-num-threshold`](https://docs.pingcap.com/tidb/stable/tikv-configuration-file/#tombstone-num-threshold-new-in-v757), [`gc.auto-compaction.tombstone-percent-threshold`](https://docs.pingcap.com/tidb/stable/tikv-configuration-file/#tombstone-percent-threshold-new-in-v757), [`gc.auto-compaction.redundant-rows-threshold`](https://docs.pingcap.com/tidb/stable/tikv-configuration-file/#redundant-rows-threshold-new-in-v757), [`gc.auto-compaction.redundant-rows-percent-threshold`](https://docs.pingcap.com/tidb/stable/tikv-configuration-file/#redundant-rows-percent-threshold-new-in-v757), [`gc.auto-compaction.bottommost-level-force`](https://docs.pingcap.com/tidb/stable/tikv-configuration-file/#bottommost-level-force-new-in-v757) | New | – | New configuration group to control automatic compaction behavior. | [#18727](https://github.com/tikv/tikv/issues/18727) | [@v01dstar](https://github.com/v01dstar) |

Check failure on line 88 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": 88, "column": 1029}}}, "severity": "ERROR"}

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

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.EnDash] Use an em dash ('—') instead of en dash ('–').

Raw Output:
{"message": "[PingCAP.EnDash] Use an em dash ('—') instead of en dash ('–').", "location": {"path": "releases/release-8.5.4.md", "range": {"start": {"line": 88, "column": 900}}}, "severity": "ERROR"}
| [`flash.graceful_wait_shutdown_timeout`](https://docs.pingcap.com/tidb/v8.5/tiflash-configuration#graceful_wait_shutdown_timeout-new-in-v854) | New | `600` | Maximum wait time (seconds) for TiFlash graceful shutdown. TiFlash continues running unfinished MPP tasks but rejects new ones. Shuts down immediately if all tasks finish; otherwise, it is forcibly shut down after the timeout. | [#10266](https://github.com/tiflash/issues/10266) | [@gengliqi](https://github.com/gengliqi) |

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

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

### MySQL compatibility

Expand Down
Loading