TiDB 8.5.4 Release Notes

Release date: November 27, 2025

TiDB version: 8.5.4

Quick access: Quick start | Production deployment

Features

• Support redistributing data of a specific table (experimental) #63260 @bufferflies

  PD automatically schedules data to be distributed as evenly as possible across all TiKV nodes in a cluster. However, this automatic scheduling focuses on the cluster as a whole. In some cases, even if the cluster-wide data distribution is balanced, the data of a specific table might still be unevenly distributed across TiKV nodes.

  Starting from v8.5.4, you can use the SHOW TABLE DISTRIBUTION statement to check how the data of a specific table is distributed across all TiKV nodes. If the data distribution is unbalanced, you can use the DISTRIBUTE TABLE statement to redistribute the table's data (experimental) to improve load balancing.

  Note that redistributing the data of a specific table is a one-time task with a timeout limit. If the distribution task is not completed before the timeout, it will automatically exit.

  For more information, see documentation.

• Support ANALYZE embedded in DDL statements #57948 @terry1purcell @AilinKid

  This feature applies to the following types of DDL statements:

  • DDL statements that create new indexes: ADD INDEX
  • DDL statements that reorganize existing indexes: MODIFY COLUMN and CHANGE COLUMN

  When this feature is enabled, TiDB automatically runs an ANALYZE (statistics collection) operation before the new or reorganized index becomes visible to users. This prevents inaccurate optimizer estimates and potential plan changes caused by temporarily unavailable statistics after index creation or reorganization.

  For more information, see documentation.

• Support creating global indexes on non-unique columns of partitioned tables #58650 @Defined2014 @mjonss

  Starting from v8.3.0, you can create global indexes on unique columns of partitioned tables in TiDB to improve query performance. However, creating global indexes on non-unique columns was not supported. Starting from v8.5.4, TiDB removes this restriction, enabling you to create global indexes on non-unique columns of partitioned tables, which enhances the usability of global indexes.

  For more information, see documentation.

• Support gracefully shutting down TiFlash #10266 @gengliqi

  When shutting down a TiFlash server, TiFlash now lets currently running MPP tasks continue for a configurable timeout duration, while rejecting new MPP task requests. The default timeout duration is 600 seconds, and you can adjust it using the flash.graceful_wait_shutdown_timeout configuration item.

  • If all running MPP tasks finish before the timeout duration expires, TiFlash shuts down immediately.
  • If there are still unfinished MPP tasks when the timeout duration expires, TiFlash shuts down forcibly.

  For more information, see documentation.

• Introduce a new TiCDC architecture option for improved performance, scalability, and stability #442 @CharlesCheung96

  This new architecture redesigns TiCDC core components and optimizes its data processing workflows, while maintaining compatibility with the configuration, usage, and APIs of the classic TiCDC architecture.

  When configured to use this new architecture, TiCDC achieves near-linear scalability and can replicate millions of tables with lower resource consumption. It also reduces changefeed latency and delivers more stable performance in scenarios with high write workloads, frequent DDL operations, and cluster scaling. Note that the new architecture currently has some initial limitations.

  To use the new architecture, set the TiCDC configuration item newarch to true.

  For more information, see documentation.

Compatibility changes

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:

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

System variables

Configuration parameters

MySQL compatibility

Starting from v8.5.4, TiDB aligns its behavior with MySQL when inserting data into a DECIMAL column: if the number of decimal places exceeds the column's defined scale, TiDB automatically truncates the extra digits and inserts the truncated data successfully, regardless of how many extra decimal places there are. In earlier TiDB versions, if the number of decimal places in the inserted DECIMAL value exceeded 72, the insertion fails and returns an error. For more information, see Connect to TiDB using JDBC.

Improvements

• TiDB

  • Support applying the semi_join_rewrite hint to Semi Joins in IN subqueries #58829 @qw4990
  • Optimize the estimation strategy when the tidb_opt_ordering_index_selectivity_ratio system variable takes effect #62817 @terry1purcell
  • Adjust the optimizer selection logic to make newly created indexes more likely to be chosen in certain scenarios #57948 @terry1purcell
  • Optimize the query estimation logic for columns with a small number of distinct values (NDV) #61792 @terry1purcell
  • Optimize the estimation strategy for Index Join queries that include LIMIT OFFSET #45077 @qw4990
  • Optimize the out-of-range estimation strategy when statistics are not collected in time #58068 @terry1purcell
  • Add the backoff metric to the Performance Overview > SQL Execute Time Overview panel in Grafana to facilitate debugging #61441 @dbsid
  • Add statement ID information to the audit log plugin #63525 @YangKeao

• TiKV

  • Change the log level of certain automatically recoverable errors in the BR module from ERROR to WARN to reduce unnecessary alerts #18493 @YuJuncen
  • Change the log level of certain TiKV errors from ERROR to WARN to reduce unnecessary alerts #18745 @exit-code-1
  • Split the GC check process in the Raft module into two phases to improve the efficiency of garbage collection for redundant MVCC versions in Regions #18695 @v01dstar
  • Calculate MVCC redundancy based on GC safe points and RocksDB statistics to improve the efficiency and accuracy of compaction #18697 @v01dstar
  • Change the GC handling logic for Region MVCC to be executed by GC worker threads, unifying the overall GC processing logic #18727 @v01dstar
  • Optimize the calculation method of the default gRPC thread pool size by making it dynamically calculated based on total CPU quota instead of a fixed value, avoiding performance bottlenecks caused by insufficient gRPC threads #18613 @LykxSassinator
  • Optimize the tail latency of async snapshot and write operations in environments with a large number of SST files #18743 @Connor1996

• PD

  • Reduce unnecessary error logs #9370 @bufferflies
  • Upgrade the Golang version from 1.23.0 to 1.23.12 and update related dependencies #9788 @JmPotato
  • Support scattering Regions at the table level to achieve balanced distribution across scatter-role and engine dimensions #8986 @bufferflies

• TiFlash

  • Skip unnecessary data reads to improve TableScan performance #9875 @gengliqi
  • Optimize TableScan performance on wide tables with many columns and sparse data (that is, lots of NULL or empty values) in TiFlash #10361 @JaySon-Huang
  • Reduce TiFlash CPU overhead caused by adding vector indexes in clusters with many tables #10357 @Lloyd-Pottiger
  • Minimize unnecessary log output when processing useless Raft commands to reduce log volume #10467 @JaySon-Huang
  • Improve TableScan performance on small partitioned tables in TiFlash #10487 @JaySon-Huang

• Tools

  • TiDB Data Migration (DM)

    • Support case-insensitive matching when retrieving the upstream GTID_MODE #12167 @OliverS929

Bug fixes

• TiDB

  • Fix the issue that the use index hint does not take effect when tidb_isolation_read_engines is set to tiflash #60869 @Lloyd-Pottiger
  • Fix the issue that max_execution_time does not take effect for SELECT FOR UPDATE statements #62960 @ekexium
  • Fix the issue that row count estimates across months or years can be significantly overestimated #50080 @terry1purcell
  • Fix the issue that the handling of Decimal types in prepared statements is inconsistent with MySQL #62602 @ChangRui-Ryan
  • Fix the issue that the short path in the TRUNCATE() function is incorrectly processed #57608 @xzhangxian1008
  • Fix the issue that spilled files might not be fully deleted when the Out Of Quota For Local Temporary Space error is triggered #63216 @xzhangxian1008
  • Fix the issue that queries using regular expressions against INFORMATION_SCHEMA tables might return incorrect results #62347 @River2000i
  • Fix the issue that TiDB does not return an error when it fails to get a timestamp from PD #58871 @joechenrh
  • Fix the issue that query results differ between the owner TiDB and non-owner TiDB instances during executing MODIFY COLUMN statements #60264 @tangenta
  • Fix the issue that ADMIN ALTER DDL JOBS statements display incorrect parameter values after dynamically modifying parameters #63201 @fzzf678
  • Fix the issue that the GC safe point does not advance when adding an index within a transaction #62424 @wjhuang2016
  • Fix the issue that ingesting excessively large SST files into L0 triggers flow control #63466 @CbcWestwolf
  • Fix the issue that global sorting is blocked when the CPU-to-memory ratio is 1:2 #60951 @wjhuang2016
  • Fix the issue that pending Distributed eXecution Framework (DXF) tasks cannot be canceled when the number of tasks exceeds 16 #63896 @D3Hunter
  • Fix the issue that after the DXF task is canceled, other tasks fail to exit #63927 @D3Hunter
  • Fix the issue that enabling the Apply operator concurrency (tidb_enable_parallel_apply = on) causes plan generation failure due to a missing clone implementation #59863 @hawkingrei
  • Fix the issue that using the ATAN2 function might produce incorrect results #60093 @guo-shaoge
  • Fix the issue that select 1 from dual cannot use the instance-level plan cache #63075 @time-and-fate
  • Fix the issue that changing the join order might cause the planner to fail #61715 @hawkingrei
  • Fix the issue that using the set_var hint with bindings prevents variables from being restored to their original settings #59822 @wddevries
  • Fix the issue that setting ONLY_FULL_GROUP_BY to a negative value causes validation failure #62617 @AilinKid
  • Fix the issue that the ONLY_FULL_GROUP_BY check is case-insensitive #62672 @AilinKid
  • Fix the issue that the DP join order algorithm might generate an incorrect plan #63353 @winoros
  • Fix the issue that rewriting an outer join to an inner join might produce incorrect results #61327 @hawkingrei
  • Fix the issue that executing certain queries might cause an internal panic #58600 @Defined2014
  • Fix the issue that the global index might read incorrect data during certain ALTER PARTITION operations #64084 @mjonss
  • Fix the issue that the global index might return incorrect results in some cases #61083 @Defined2014
  • Fix the issue that character_set_results truncates incorrect characters instead of replacing them #61085 @xhebox
  • Fix the issue that running ADD COLUMN and UPDATE statements concurrently might cause errors #60047 @L-maple
  • Fix the issue that Merge Join might omit filter conditions when calculating costs #62917 @qw4990

• PD

  • Fix the issue that the PD Client retry strategy is not initialized correctly #9013 @rleungx
  • Fix the issue that the TSO HTTP API /config and /members return incorrect results #9797 @lhy1024
  • Fix the incorrect error handling logic of TSO Follower Proxy #9188 @Tema
  • Fix the issue that splitting buckets still works even after bucket reporting is disabled #9726 @bufferflies
  • Fix the issue that the Resource Manager incorrectly allocates tokens, causing queries to be stuck #9455 @JmPotato
  • Fix the issue that Placement Rules do not take effect after PD leader switches #9602 @okJiang
  • Fix the issue that PD might fail to parse large numeric values in scientific notation, which consequently causes some TTL-related configurations to not take effect #9343 @lhy1024

• TiFlash

  • Fix the issue that queries might fail when queried columns contain a large number of NULL values #10340 @Lloyd-Pottiger
  • Fix the issue that TiFlash generates inflated statistics for RU consumption #10380 @JinheLin
  • Fix the issue that TiFlash might encounter OOM when slow queries exist under the disaggregated storage and compute architecture #10278 @JaySon-Huang
  • Fix the issue that TiFlash might retry indefinitely when a network partition occurs between TiFlash and S3 under the disaggregated storage and compute architecture #10424 @JaySon-Huang
  • Fix the issue that the FLOOR() and CEIL() functions might return incorrect results when their parameters are of the DECIMAL type #10365 @ChangRui-Ryan

• Tools

  • Backup & Restore (BR)

    • Fix the issue that zstd compression in log backup does not take effect, causing the output to remain uncompressed #18836 @3pointer
    • Fix the issue that the flush operation occasionally becomes slow when backing up data to Azure Blob Storage #18410 @YuJuncen
    • Fix the issue that log truncate might occur when file deletion fails #63358 @YuJuncen
    • Fix the issue that setting --checksum to false during backup might cause the count column in the mysql.stats_meta table to become 0 after restore #60978 @Leavrth
    • Reduce the possibility of BR failing to restore data from S3-compatible storage services when the bandwidth limits on these services are enabled #18846 @kennytm
    • Fix the issue that log backup observer might lose the observation on a Region, causing the log backup progress to fail to advance #18243 @Leavrth
    • Fix the issue that causes restore point creation to fail when backed-up tables include certain special schemas #63663 @RidRisR

  • TiCDC

    • Fix a panic that could occur when configuring a column-type partition dispatcher that includes virtual columns #12241 @wk989898
    • Fix a panic that could occur when closing the DDL puller #12244 @wk989898
    • Support filtering unsupported DDL types through the ignore-txn-start-ts parameter in the filter configuration #12286 @asddongmen
    • Fix the issue that changefeed tasks might get stuck when using Azure Blob Storage as the downstream #12277 @zurakutsia
    • Fix the issue that DROP FOREIGN KEY DDL is not replicated to the downstream #12328 @3AceShowHand
    • Fix the issue that TiCDC might panic when encountering rollback and prewrite entries during Region subscription #19048 @3AceShowHand
    • Fix the issue that assertion errors in TiKV might cause TiCDC to panic #18498 @tharanga