Prerequisites

ClickHouse can be build on Linux, FreeBSD and macOS. If you use Windows, you can still build ClickHouse in a virtual machine running Linux, e.g. VirtualBox with Ubuntu.

Create a Repository on GitHub

To start developing for ClickHouse you will need a GitHub account. Please also generate an SSH key locally (if you don't have one already) and upload the public key to GitHub as this is a prerequisite for contributing patches.

Next, fork the ClickHouse repository in your personal account by clicking the "fork" button in the upper right corner.

To contribute changes, e.g., a fix for an issue or a feature, first commit your changes to a branch in your fork, then create a "Pull Request" with the changes to the main repository.

For working with Git repositories, please install Git. For example, in Ubuntu, run:

A Git cheatsheet can be found here. A detailed Git manual is here.

Clone the Repository to Your Development Machine

First, download the source files to your working machine, i.e. clone the repository:

This command creates a directory ClickHouse/ containing the source code, tests, and other files. You can specify a custom directory for checkout after the URL, but it is important that this path does not contain whitespaces as this may break the build later on.

ClickHouse's Git repository uses submodules to pull in 3rd party libraries. Submodules are not checked out by default. You can either

• run git clone with option --recurse-submodules,

• if git clone is run without --recurse-submodules, run git submodule update --init --jobs <N> to checkout all submodules explicitly. (<N> can be set for example to 12 to parallelize the download.)

• if git clone is run without --recurse-submodules and you like to use sparse and shallow submodule checkout to omit unneeded files and history in submodules to save space (ca. 5 GB instead of ca. 15 GB), run ./contrib/update-submodules.sh. This alternative is used by CI but not recommended for local development as it makes working with submodules less convenient and slower.

To check the status of the Git submodules, run git submodule status.

If you get the following error message

the SSH keys for connecting to GitHub are missing. These keys are normally located in ~/.ssh. For SSH keys to be accepted you need to upload them in GitHub's settings.

You can also clone the repository via HTTPS:

This, however, will not let you send your changes to the server. You can still use it temporarily and add the SSH keys later replacing the remote address of the repository with git remote command.

You can also add original ClickHouse repo address to your local repository to pull updates from there:

After successfully running this command you will be able to pull updates from the main ClickHouse repo by running git pull upstream master.

tip

Please do not use verbatim git push, you may push to the wrong remote and/or the wrong branch. It is better to specify the remote and branch names explicitly, e.g. git push origin my_branch_name.

Writing Code

Below you can find some quick links which may be useful when writing code for ClickHouse:

• ClickHouse Architecture.
• Code style guide.
• Third-party libraries
• Writing tests
• Open issues

IDE

Visual Studio Code and Neovim are two options that have worked well in the past for developing ClickHouse. If you are using VS Code, we recommend using the clangd extension to replace IntelliSense as it is much more performant.

CLion is another great alternative. However, it can be slower on larger projects like ClickHouse. A few things to keep in mind when using CLion:

• CLion creates a build path on its own and automatically selects debug for the build type
• It uses a version of CMake that is defined in CLion and not the one installed by you
• CLion will use make to run build tasks instead of ninja (this is normal behavior)

Other IDEs you can use are Sublime Text, Qt Creator, or Kate.

Create A Pull Request

Navigate to your fork repository in GitHub's UI. If you have been developing in a branch, you need to select that branch. There will be a "Pull request" button located on the screen. In essence, this means "create a request for accepting my changes into the main repository".

A pull request can be created even if the work is not completed yet. In this case please put the word "WIP" (work in progress) at the beginning of the title, it can be changed later. This is useful for cooperative reviewing and discussion of changes as well as for running all of the available tests. It is important that you provide a brief description of your changes, it will later be used for generating release changelog.

Testing will commence as soon as ClickHouse employees label your PR with a tag "can be tested". The results of some first checks (e.g. code style) will come in within several minutes. Build check results will arrive within half an hour. The main set of tests will report itself within an hour.

The system will prepare ClickHouse binary builds for your pull request individually. To retrieve these builds click the "Details" link next to "Builds" entry in the list of checks. There you will find direct links to the built .deb packages of ClickHouse which you can deploy even on your production servers (if you have no fear).

Write Documentation

Every pull request which adds a new feature must come with proper documentation. If you'd like to preview your documentation changes the instructions for how to build the documentation page locally are available in the README.md file here. When adding a new function to ClickHouse you can use the template below as a guide:

Using Test Data

Developing ClickHouse often requires loading realistic datasets. This is particularly important for performance testing. We have a specially prepared set of anonymized data of web analytics. It requires additionally some 3GB of free disk space.

In clickhouse-client:

Import the data: