Deploy a TiFlash Cluster


If you want to get a first-hand experience on how to use the TiFlash RC version, contact PingCAP for more information and assistance.

This document introduces the environment requirements for deploying a TiFlash cluster and the deployment methods in different scenarios.

This section provides hardware configuration recommendations based on different TiFlash deployment methods.

TiFlash standalone deployment

  • Minimum configuration: 32 VCore, 64 GB RAM, 1 SSD + n HDD
  • Recommended configuration: 48 VCore, 128 GB RAM, 1 NVMe SSD + n SSD

There is no limit to the number of target machines (one at least). A single machine can use multiple disks, but deploying multiple instances on a single machine is not recommended.

It is recommended to use an SSD disk to buffer the real-time data being replicated and written to TiFlash. The performance of this disk need to be not lower than the hard disk used by TiKV. It is recommended that you use a better performance NVMe SSD and the SSD's capacity is not less than 10% of the total capacity. Otherwise, it might become the bottleneck of the amount of data that this node can handle.

For other hard disks, you can use multiple HDDs or regular SSDs. A better hard disk will surely bring better performance.

TiFlash supports multi-disk deployment, so there is no need to use RAID.

TiFlash and TiKV are deployed on the same node

See Hardware recommendations for TiKV server, and increase the memory capacity and the number of and CPU cores as needed.

It is not recommended to deploy TiFlash and TiKV on the same disk to prevent mutual interference.

Hard disk selection criteria are the same as TiFlash standalone deployment. The total capacity of the hard disk is roughly: the to-be-replicated data capacity of the entire TiKV cluster / the number of TiKV replicas * the number of TiFlash replicas.

For example, if the overall planned capacity of TiKV is 1TB, each Region in TiKV has 3 replicas, and each Region in TiFlash has 2 replicas, then the recommended capacity of TiFlash will be 1024GB / 3 * 2. You can choose to replicate part of the tables instead of all.

TiDB version requirements

Currently, the testing of TiFlash is based on the related components of TiDB 4.0 (including TiDB, PD, TiKV, and TiFlash). For the download method of TiDB 4.0, refer to the following installation and deployment steps.

Install and deploy TiFlash

This section describes how to install and deploy TiFlash in the following scenarios:


  1. Before starting the TiFlash process, you must ensure that PD's Placement Rules feature is enabled (For how to enable it, see the second step in the Add TiFlash component to an existing TiDB cluster section).
  2. When TiFlash is running, you must ensure that PD's Placement Rules feature remains enabled.

Fresh TiFlash deployment

TiUP cluster is the deployment tool for TiDB 4.0 or later versions. It is recommended that you use TiUP cluster to install and deploy TiFlash. The steps are as follows:

  1. Install TiUP.

  2. Install the TiUP cluster component.

    tiup cluster
  3. Write the topology configuration file and save it as topology.yaml.

    You can refer to the topology configuration file template.

    In addition to configuring the TiDB cluster, you also need to configure the IP of TiFlash servers in tiflash_servers. Currently the configuration only supports IP but not domain name.

    If you need to deploy TiFlash, set replication.enable-placement-rules in the pd section to true.

        replication.enable-placement-rules: true
      - host:
      - host:
      - host:
      - host:
      - host:
      - host:
      - host:
      - host:

    If you want to customize the deployment directory, configure the data_dir parameter. If you want to deploy TiFlash on multiple disks, separate each directory with commas. For example:

      - host:
        data_dir: /data1/tiflash/data,/data2/tiflash/data
  4. Refer to the TiUP deployment process, and complete the following steps:

    • Deploy the TiDB cluster (test is the cluster name):

      tiup cluster deploy test v4.0.0-rc topology.yaml  -i ~/.ssh/id_rsa
    • Start the TiDB cluster:

      tiup cluster start test
  5. View the cluster status:

    tiup cluster display test

Add TiFlash component to an existing TiDB cluster

  1. First, confirm that your current TiDB version supports TiFlash; otherwise, you need to upgrade your TiDB cluster to 4.0 rc or higher versions.

  2. Execute the config set enable-placement-rules true command in pd-ctl (resources/bin in the tidb-ansible directory includes the pd-ctl binary file) to enable PD's Placement Rules feature.

    Currently, pd-ctl is not connected to TiUP cluster, you need to manually download pd-ctl.

  3. Refer to Scale out a TiFlash node and deploy TiFlash.