Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pingcap/tidb/llms.txt
Use this file to discover all available pages before exploring further.
TiDB is designed for horizontal scaling. TiDB server nodes are stateless and can be added at any time. TiKV and TiFlash nodes are added by the operator or TiUP, and PD automatically rebalances data across nodes. Scaling operations do not require downtime.
Component scaling overview
| Component | Scale direction | Notes |
|---|
| TiDB server | Horizontal | Stateless; add nodes and update the load balancer |
| TiKV | Horizontal | PD rebalances regions automatically after nodes are added |
| TiFlash | Horizontal | Columnar storage for analytics; add nodes for more capacity |
| PD | Horizontal | Odd number of nodes recommended for Raft quorum |
TiKV rebalancing runs in the background and may take time proportional to the amount of data being moved. Monitor region scheduling in TiDB Dashboard during the operation.
Horizontal scaling
Scale out with TiUP
Create a topology file describing the nodes to add. For example, to add a TiDB node:# scale-out-tidb.yaml
tidb_servers:
- host: 10.0.1.5
port: 4000
status_port: 10080
tiup cluster scale-out <cluster-name> scale-out-tidb.yaml
# scale-out-tikv.yaml
tikv_servers:
- host: 10.0.1.6
port: 20160
status_port: 20180
data_dir: /data/tikv
tiup cluster scale-out <cluster-name> scale-out-tikv.yaml
# scale-out-tiflash.yaml
tiflash_servers:
- host: 10.0.1.7
data_dir: /data/tiflash
latest_offload_threshold: 0.98
tiup cluster scale-out <cluster-name> scale-out-tiflash.yaml
tiup cluster display <cluster-name>
Scale out with Kubernetes
TiDB on Kubernetes is managed via the TidbCluster custom resource. Edit the replica count for the component you want to scale.Scale TiDB server nodes:kubectl patch tidbcluster <cluster-name> -n <namespace> \
--type=merge \
-p '{"spec":{"tidb":{"replicas":3}}}'
kubectl patch tidbcluster <cluster-name> -n <namespace> \
--type=merge \
-p '{"spec":{"tikv":{"replicas":5}}}'
kubectl patch tidbcluster <cluster-name> -n <namespace> \
--type=merge \
-p '{"spec":{"tiflash":{"replicas":2}}}'
kubectl get tidbcluster <cluster-name> -n <namespace> -w
Load balancer configuration
TiDB server nodes are stateless and interchangeable. Place a load balancer in front of them and route MySQL traffic to port 4000.
Example HAProxy configuration:
frontend tidb-frontend
bind *:4000
default_backend tidb-backend
backend tidb-backend
balance roundrobin
server tidb1 10.0.1.3:4000 check
server tidb2 10.0.1.4:4000 check
server tidb3 10.0.1.5:4000 check
Vertical scaling
Vertical scaling means increasing CPU or memory on existing nodes. For TiUP deployments, this requires a rolling restart.
Update the cluster topology
Edit the cluster configuration to reflect the new resource limits:tiup cluster edit-config <cluster-name>
Reload the configuration
Apply the changes with a rolling restart:tiup cluster reload <cluster-name>
TidbCluster CR:
spec:
tidb:
requests:
cpu: "4"
memory: "16Gi"
limits:
cpu: "8"
memory: "32Gi"
Scale in (remove nodes)
To remove nodes with TiUP:
tiup cluster scale-in <cluster-name> --node <host>:<port>
Before scaling in TiKV nodes, ensure that the remaining nodes have sufficient capacity for the data that will be migrated. PD must complete region evacuation before the node is removed. This can take significant time for large datasets.
