Scaling

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

TiUP
Kubernetes

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

Then run:

tiup cluster scale-out <cluster-name> scale-out-tidb.yaml

To add a TiKV node:

# 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

To add a TiFlash node for columnar analytics:

# 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

Verify the new nodes are online:

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}}}'

Scale TiKV nodes:

kubectl patch tidbcluster <cluster-name> -n <namespace> \
  --type=merge \
  -p '{"spec":{"tikv":{"replicas":5}}}'

Scale TiFlash nodes:

kubectl patch tidbcluster <cluster-name> -n <namespace> \
  --type=merge \
  -p '{"spec":{"tiflash":{"replicas":2}}}'

Monitor rollout status:

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>

On Kubernetes, update the resource requests and limits in the 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.

Get Started

Core Concepts

Deployment

Data Management

Operations

Component scaling overview

Horizontal scaling

Scale out with TiUP

Scale out with Kubernetes

Load balancer configuration

Vertical scaling

Scale in (remove nodes)

​Component scaling overview

​Horizontal scaling

​Scale out with TiUP

​Scale out with Kubernetes

​Load balancer configuration

​Vertical scaling

​Scale in (remove nodes)

Component scaling overview

Horizontal scaling

Scale out with TiUP

Scale out with Kubernetes

Load balancer configuration

Vertical scaling

Scale in (remove nodes)