TiFlash: the columnar analytical engine inside TiDB

The analytical half of a hybrid database

TiFlash is a columnar storage component of TiDB and of TiDB Cloud, the fully managed service of TiDB, and it mainly plays the role of Analytical Processing in the Hybrid Transactional and Analytical Processing architecture of TiDB.

That is the whole proposition, and it is worth being precise about it, because the same words are used for two quite different products. A system that stores rows and also answers analytical queries, keeping one copy of the data, is an HTAP engine. A system that keeps a columnar replica for analytics and a row store for transactions is a different thing, and TiFlash is the second: it is a columnar store that sits beside TiKV and serves the analytical side of TiDB's queries.

The implementation base matters for anyone reading the code. The TiFlash repository is based on ClickHouse, and the README thanks the ClickHouse team for the work. So the storage engine, the query execution machinery and much of the vectorised processing come from there, with TiDB-specific pieces layered on top for the replication protocol and the integration with TiKV.

The quick start offers two routes. You can explore TiFlash with a free trial of TiDB Cloud, or read the Quick Start with HTAP and Use TiFlash guides for a self-hosted installation, and the documentation site for TiDB is where both live.

Replication from TiKV over Raft, in sub-second time

TiFlash stores data in columnar format and synchronizes data updates in real time from TiKV by Raft logs with sub-second latency. That sentence contains the design.

TiKV is the row store, and it is a Raft-replicated system with a log per region. TiFlash subscribes to those logs and applies them into its columnar structures, which is how a copy of the data ends up in a shape that analytical queries can scan efficiently.

The Raft log is a better transport than a change data capture stream, and the reason is in the consistency guarantee below. Because TiFlash applies the same log that TiKV commits, its state is not an eventually-consistent approximation that might catch up later, it is derived from the same ordered history. The cost of that is a copy of the data, which is the trade every HTAP system makes and the reason the analytical store is a separate component rather than a different encoding of the same files.

Sub-second latency is the number to hold on to, because it determines what a query can read. A query that has to wait for the columnar copy to catch up is a query with a staleness bound, and at under a second that bound is small enough for interactive use on operational data, which is the use case TiDB Cloud sells.

Snapshot isolation on the analytical path

Reads in TiFlash are guaranteed transactionally consistent with Snapshot Isolation level. That is the second sentence of the architecture, and it is the one that decides whether the analytical path is usable for anything but reporting.

The concern is specific. A columnar copy that applies Raft logs asynchronously can, at any instant, hold a state that no single point in the transaction history corresponds to: some rows from before a commit and some from after. Reporting queries tolerate that. A query that computes a total and a breakdown, or that joins an order against an inventory row, does not, because the two halves may come from different points in time.

Snapshot isolation resolves this by pinning the read to a single timestamp, so the copy is read as of a consistent point in the transaction history, even though the underlying data arrived in pieces. The guarantee is what lets TiDB route a query to TiFlash without changing the answer the row store would have given.

That guarantee is also what makes the sub-second replication meaningful. Freshness and consistency are different properties, and a system that has only one of them is not usable as a transactional analytical read path.

Building it needs LLVM 17, Rust and a recursive clone

The build section is honest about the toolchain, which is a rare thing in a README. TiFlash can be built on x86-64 and amd64, or on aarch64, and on Linux or MacOS.

The prerequisites are CMake 3.23.0 or newer, Clang 17.0.0 or newer, Rust, Python 3.0 or newer, Ninja-Build or GNU Make, and Ccache, which the README says is not necessary but highly recommended to reduce rebuild time.

The per-platform instructions are given as separate sections. On Ubuntu and Debian the Rust toolchain comes from rustup with the default toolchain set to none, LLVM is installed from the apt.llvm.org script, and the remaining packages are cmake, ninja-build, zlib1g-dev, libcurl4-openssl-dev and ccache. Arch Linux has a single pacman line covering clang, lld, libc++, compiler-rt, openmp, cmake, ninja, openssl, zlib, llvm and ccache. Rocky Linux points at a script in the tree, release-linux-llvm/env/prepare-sysroot.sh, rather than listing packages. MacOS installs the command line tools, then ninja, cmake, [email protected], ccache and llvm@17 from brew, and exposes the LLVM 17 toolchain through CC and CXX.

The source checkout is recursive and parallel:

git clone https://github.com/pingcap/tiflash.git --recursive -j 20
cd tiflash

The recursive flag matters, because the tree carries its dependencies as submodules, and a shallow, non-recursive clone produces a build that fails late rather than early.

The build presets, and the warning attached to them

The development build is a preset, which is the shortest path:

cmake --workflow --preset dev

and the README gives the manual equivalent for anyone who would rather not use presets, creating a build directory, configuring with Ninja and a debug build type, and building the tiflash target:

mkdir cmake-build-debug
cd cmake-build-debug
cmake .. -GNinja -DCMAKE_BUILD_TYPE=DEBUG
ninja tiflash

The options are passed as -D arguments to CMake, and the README attaches a warning to them: these options should not be changed for production usage, as they may introduce unexpected build errors and unpredictable runtime behaviours.

The options themselves are the usual three. The build type is RELWITHDEBINFO for a release build with debug information, which is the default, or DEBUG, or RELEASE. The README suggests using separate build directories per build type, so the compile unit cache is not invalidated when you switch, which is a small piece of advice that saves a full rebuild every time you toggle a flag. Unit tests are enabled with ENABLE_TESTS=ON, which is the default in the debug profile, and off by default in the release profile. And you can use GNU Make instead of Ninja by simply not passing -GNinja, in which case the build is make tiflash -j.

The note on -j is worth repeating, because it is a real operational detail. Higher parallelism consumes more memory, and if you hit a compiler out of memory or a hang, the answer is to lower the parallelism to a reasonable number, perhaps half your core count, depending on the memory available.

Two documented build failures and their fixes

The README documents specific problems, and they are the kind of thing that otherwise costs a day.

The first is the CMake version on older Ubuntu. On Ubuntu 18.04 and 20.04 the default installed cmake may not be recent enough, and the fix is to add the Kitware APT Repository, installing software-properties-common and lsb-release, adding the key, adding the repository for the current release and updating before installing cmake.

The second is a link error, ld.lld: error: duplicate symbol: ssl3_cbc_digest_record. The README's diagnosis is that a pre-installed libssl3 is present where TiFlash prefers libssl1, and that TiFlash has vendored libssl1, so the system copy can simply be removed to make compiling work:

sudo apt remove libssl-dev

If that does not work, the README asks you to file an issue.

Both of these are consequences of the same thing, a project that vendors parts of its dependency stack in order to control what it links against. That is a defensible choice for a database that has to be reproducible across distributions, and it is also the source of the sharp edges a new contributor meets first.

Where TiFlash is the wrong choice

The first wrong-tool case is a team that does not run TiDB. TiFlash is a component of TiDB's HTAP architecture and it gets its data from TiKV, so a standalone analytical workload has no use for it. A columnar database that ingests from its own sources is a different product with a different operational profile.

The second is a workload that does not need the same data twice. If the analytical questions are asked against data that no transaction touches, or against data that can be a few minutes stale, the same result comes from replicating into a warehouse on a schedule, with none of the cost of a second copy that is kept in step over Raft.

The third is an organisation that cannot operate a C++ and Rust system of this size. The build alone says a lot: LLVM 17, Rust, CMake 3.23, a recursive clone of a large tree, a vendored OpenSSL, and a CI matrix across architectures and distributions. Nobody should be running TiFlash for the first time by compiling it, and the realistic adoption path for most teams is TiDB Cloud or the packaged distribution rather than a source build.

There is also the version matrix to consider. The release list shows two maintained lines, v8.5.8 and v7.5.8, with the 7.5 line still receiving releases in September 2026 after the 8.5 line's August release, so a deployment is a decision about which series to run and for how long.

Editorial conclusion

Adopt TiFlash when you are already running TiDB and need analytical queries over the same data as your transactions, and want the freshness of a replicated columnar copy rather than a separate warehouse. Do not adopt it as a standalone analytical database, since it is a component of TiDB's HTAP architecture and depends on TiKV for its data, and do not build it from source unless you have the toolchain it demands, which means LLVM 17, Rust, CMake 3.23 and a recursive clone of a large tree. Before you build, read the build options section, because the README states plainly that the options are not to be changed for production use, and decide your build type and test settings before you start rather than after.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. pingcap/tiflash on GitHub
3. Project website
4. README
5. Releases