TiDB Rolling Upgrade Process Using TiUP: Detailed Steps and Code References

Rolling upgrade is an online upgrade approach that ensures software updates can be completed while services remain partially or fully available, which is crucial for large clusters supporting complex workloads.

The article targets DBAs and developers who may encounter issues during TiDB upgrades, offering guidance based on the core process analysis.

TiDB Overview

TiDB is a hybrid OLTP/OLAP distributed database offering horizontal scalability, strong consistency, multi‑replica safety, distributed transactions, and real‑time analytics, while being MySQL‑compatible and low‑maintenance.

Its core components are:

TiDB Server : Stateless SQL layer exposing MySQL protocol, parses queries, generates distributed execution plans, and forwards data requests to TiKV/TiFlash.

PD (Placement Driver) : Manages metadata, stores region distribution, provides dashboard, assigns transaction IDs, and schedules data placement; typically deployed as an odd number of nodes for high availability.

TiKV Server : Distributed transactional key‑value store that holds data in regions, supports snapshot isolation, maintains multiple replicas, and ensures automatic failover.

Key Terminology

Scheduler : PD component that generates various scheduling tasks such as balance‑leader, balance‑region, hot‑region, and evict‑leader for rolling upgrades.

Store : A TiKV instance representing a storage node; each TiKV server corresponds to one Store.

TiUP Tool Introduction

Since TiDB 4.0, TiUP serves as a package manager for the TiDB ecosystem, simplifying the deployment and management of components like TiDB, PD, and TiKV, and it includes the rolling upgrade functionality discussed here.

Core Upgrade Workflow

Configuration and parameter checks, package download (omitted).

Backup old component files. schedule.leader-schedule-limit # controls the number of concurrent leader scheduling tasks 如果当前该配置项值小于64，则调整为：当前配置值+64 schedule.region-schedule-limit # controls the number of concurrent region scheduling tasks 如果当前该配置项值小于1024，则调整为：当前值+1024 详细介绍见：https://docs.pingcap.com/zh/tidb/stable/dynamic-config#在线修改-pd-配置

Deploy the component to be upgraded (TiDB server is stateless and will be restarted).

Pre‑upgrade preparation: obtain PD configuration, locate the PD leader, and adjust PD parameters to accelerate job scheduling.

Construct a job list for special components (TiKV and PD), detecting PD leader and scheduling it last.

Upgrade TiKV cluster: check PD leader health, record TiKV store leaders, create a store evictor via PD API, evict current store leader, restart TiKV instances, and remove the evictor.

Upgrade PD cluster: if the target node is the PD leader, evict it, restart the PD instance, and perform health checks.

Rollback PD schedule‑related configurations if needed.

Persist metadata information.

Upgrade completion.

Other Information

The described process corresponds to the latest TiUP master branch and should apply to TiDB 6.x versions.

PD also exposes many management APIs not documented in the official manual; interested readers can explore the source code for details.