TiFlash is a columnar storage component of TiDB and TiDB Cloud, the fully-managed service of TiDB. It mainly plays the role of Analytical Processing (AP) in the Hybrid Transactional/Analytical Processing (HTAP) architecture of TiDB.
TiFlash stores data in columnar format and synchronizes data updates in real-time from TiKV by Raft logs with sub-second latency. Reads in TiFlash are guaranteed transactionally consistent with Snapshot Isolation level. TiFlash utilizes Massively Parallel Processing (MPP) computing architecture to accelerate the analytical workloads.
TiFlash repository is based on ClickHouse. We appreciate the excellent work of the ClickHouse team.
Quickly explore TiFlash with a free trial of TiDB Cloud.
See TiDB Cloud Quick Start Guide.
See Quick Start with HTAP and Use TiFlash.
TiFlash can be built on the following hardware architectures:
And the following operating systems:
The following packages are required:
Detailed steps for each platform are listed below.
git clone https://github.com/pingcap/tiflash.git --recursive -j 20
cd tiflash
To build TiFlash for development:
# In the TiFlash repository root:
cmake --workflow --preset dev
Note: In Linux, usually you need to explicitly specify to use LLVM.
export CC="/usr/bin/clang-17"
export CXX="/usr/bin/clang++-17"
In MacOS, if you install llvm clang, you need to explicitly specify to use llvm clang.
Add the following lines to your shell environment, e.g. ~/.bash_profile
.
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"
export CC="/opt/homebrew/opt/llvm/bin/clang"
export CXX="/opt/homebrew/opt/llvm/bin/clang++"
Or use CMAKE_C_COMPILER
and CMAKE_CXX_COMPILER
to specify the compiler, like this:
mkdir cmake-build-debug
cd cmake-build-debug
cmake .. -GNinja -DCMAKE_BUILD_TYPE=DEBUG -DCMAKE_C_COMPILER=/opt/homebrew/opt/llvm/bin/clang -DCMAKE_CXX_COMPILER=/opt/homebrew/opt/llvm/bin/clang++
ninja tiflash
After building, you can get TiFlash binary in dbms/src/Server/tiflash
in the cmake-build-debug
directory.
TiFlash has several CMake build options to tweak for development purposes. These options SHOULD NOT be changed for production usage, as they may introduce unexpected build errors and unpredictable runtime behaviors.
To tweak options, pass one or multiple -D...=...
args when invoking CMake, for example:
cd cmake-build-debug
cmake .. -GNinja -DCMAKE_BUILD_TYPE=DEBUG -DFOO=BAR
^^^^^^^^^
Build Type:
-DCMAKE_BUILD_TYPE=RELWITHDEBINFO
: Release build with debug info (default)
-DCMAKE_BUILD_TYPE=DEBUG
: Debug build
-DCMAKE_BUILD_TYPE=RELEASE
: Release build
Usually you may want to use different build directories for different build types, e.g. a new build directory named cmake-build-release
for the release build, so that compile unit cache will not be invalidated when you switch between different build types.
Build with Unit Tests:
-DENABLE_TESTS=ON
: Enable unit tests (enabled by default in debug profile)
-DENABLE_TESTS=OFF
: Disable unit tests (default in release profile)
Build using GNU Make instead of ninja-build:
Build with System Libraries:
Build for AMD64 Architecture:
Unit tests are automatically enabled in debug profile. To build these unit tests:
# In the TiFlash repository root:
cmake --workflow --preset unit-tests-all
Then, to run these unit tests:
cd cmake-build-debug
./dbms/gtests_dbms
./libs/libdaemon/src/tests/gtests_libdaemon
./libs/libcommon/src/tests/gtests_libcommon
More usages are available via ./dbms/gtests_dbms --help
.
TiFlash supports testing with thread sanitizer and address sanitizer.
To build unit test executables with sanitizer enabled:
# In the TiFlash repository root:
cmake --workflow --preset asan-tests-all # or tsan-tests-all
There are known false positives reported from leak sanitizer (which is included in address sanitizer). To suppress these errors, set the following environment variables before running the executables:
LSAN_OPTIONS="suppressions=tests/sanitize/asan.suppression" ./dbms/gtests_dbms ...
# or
TSAN_OPTIONS="suppressions=tests/sanitize/tsan.suppression" ./dbms/gtests_dbms ...
Check out the Integration Test Guide for more details.
To build micro benchmark tests, you need release profile and tests enabled:
# In the TiFlash repository root:
cmake --workflow --preset benchmarks
Then, to run these micro benchmarks:
cd cmake-build-release
./dbms/bench_dbms
# Or run with filter:
# ./dbms/bench_dbms --benchmark_filter=xxx
More usages are available via ./dbms/bench_dbms --help
.
To build coverage report, run the script under release-centos7-llvm
cd release-centos7-llvm
./gen_coverage.sh
# Or run with filter:
# FILTER='*DMFile*:*DeltaMerge*:*Segment*' ./gen_coverage.sh
# After the script finished, it will output the directory of code coverage report, you can check out the files by webbrowser
python3 -m http.server --directory "${REPORT_DIR}" "${REPORT_HTTP_PORT}"
Here is the overview of TiFlash architecture The architecture of TiFlash's distributed storage engine and transaction layer.
See TiFlash Development Guide and TiFlash Design documents.
Before submitting a pull request, please resolve clang-tidy errors and use format-diff.py to format source code, otherwise CI build may raise error.
NOTE: It is required to use clang-format 17.0.0+.
# In the TiFlash repository root:
merge_base=$(git merge-base upstream/master HEAD)
python3 release-centos7-llvm/scripts/run-clang-tidy.py -p cmake-build-debug -j 20 --files `git diff $merge_base --name-only`
# if there are too much errors, you can try to run the script again with `-fix`
python3 format-diff.py --diff_from $merge_base
TiFlash is under the Apache 2.0 license. See the LICENSE file for details.