If you are a technical person and use a Mac, it is virtually a given that the first thing you do on a fresh machine is install the Homebrew package manager.

Nearly everything that is available through Homebrew can be installed manually by building from sources or just unpacking the binaries when available. However, the feeling that each piece of software is installed with all its dependencies, deployed in an isolated place, can be removed without leaving traces and contaminating the system, properly upgraded later, and all this with a single command, is worth a lot. Homebrew does this for us.

Same applies to ClickHouse. While the installation procedure boils down to downloading a binary, setting the executable flag on it, and, optionally, running a self-deploying command, being able to do all this in a systematic and safe way is a long requested feature for virtually all systems. For Linux, DEB and RPM packages and repositories that list them are available. Our Homebrew tap, on the other hand, solves this for macOS.

TL;DR

Assuming you have a properly installed Homebrew in the system, execute (avoid sudo):

# First, add the altinity/clickhouse tap and install the clickhouse formula from it in one command.
$ brew install altinity/clickhouse/clickhouse
...
# Then, (re)start the server.
$ brew services restart altinity/clickhouse/clickhouse
...
# Finally, execute a simple query using the client.
$ clickhouse-client -q 'SELECT version()'
21.12.2.1

Depending on your macOS version and architecture the first command may take anywhere from 1 minute if a bottle is available, to up to 3 hours if building from sources. But that’s it! You’ve got Clickhouse server and client running natively on your Mac!

You can stop here and enjoy your ClickHouse, but if you want more control and better understanding, read on to learn about the details and how to get the most out of this tap and the formulae it provides.

Glossary

Homebrew – the most popular third-party package manager for macOS (available for Linux too, however, hardly used there by anyone). Once installed, it provides the brew command that can be used to install, remove, or upgrade software, as well as run services that this software provides. Installation is straightforward, just execute the command from the front page of the project and follow the instructions, which won’t be many.

Formula – (plural formulae) a recipe for installing, removing, and building a package.

Tap – a formulae repository. Initially, the installation of Homebrew contains the default core tap maintained by the Homebrew team itself. Anyone else can create their own third-party taps that can be added by users at will.

Keg-only formula – a formula that, when installed, won’t be linked into the main UNIX-style directory structure. Keg-only formulae are used, for example, when different conflicting versions of the same software need to be installed simultaneously.

Bottle – while formula is just a recipe, a bottle is the actual binary archive with a prebuilt package. If the formula doesn’t have bottles associated with it and the target platform of the user, the brew command will start building the package from sources automatically, when the user attempts to install that formula.

How to use this tap?

Step 1: Add the altinity/clickhouse tap

First, we need to tell our Homebrew installation where to look for formulae for ClickHouse by registering our custom tap:

$ brew tap altinity/clickhouse

This should be done only once, and our Homebrew installation will remember it.

Taps are usually represented as GitHub repositories and, when adding, Homebrew will automatically look for one based on its standard naming conventions and GitHub repo URL resolution rules.

The altinity/clickhouse tap contains several different formulae and aliases for convenience. You can list them (as well as other metadata of the tap) by executing the following command:

$ brew tap-info --json altinity/clickhouse

The following is the list of formulae and aliases that are currently available in the tap:

Formulae:

clickhouse@21.12	the latest version
clickhouse@21.11	keg-only
clickhouse@21.8-altinity-stable	keg-only, the latest Altinity stable version
clickhouse-odbc	special variant of ODBC driver formula
clickhouse-cpp	special variant of C++ client library formula

Aliases:

clickhouse	always points to the latest versioned formula (currently clickhouse@21.12)
clickhouse-client	same as clickhouse
clickhouse-server	same as clickhouse
clickhouse@stable	same as clickhouse
clickhouse@altinity-stable	always points to the latest Altinity stable versioned formula (currently clickhouse@21.8-altinity-stable)

New versioned formulae will be added after each corresponding ClickHouse release.

Step 2: Install the ClickHouse formula

Once our Homebrew installation knows where to look for additional formulae, we can ask it to install them:

$ brew install clickhouse

The command above will install the latest versioned formula of ClickHouse, which includes both the server and the client, as well as other utilities that are typically available in the combined clickhouse executable. The installation process may be very quick if a bottle is available (see below), otherwise, it will start a lengthy process of building from sources.

Take your time and read the Caveats section, printed after the installation succeeds.

Later, you will be able to upgrade the installed package by executing:

# Make sure you stopped any running server and client instances, if any.
$ brew upgrade clickhouse

Note, that here (and later) we omit the altinity/clickhouse/... part when referring to a formula. This is acceptable, since there is no other formula in any of the other known taps, including the core tap that comes with the Homebrew by default, whose name is clickhouse, so there will be no conflicts and ambiguities.

This is not true when it comes to clickhouse-cpp and clichouse-odbc formulae from this tap. They also exist in the Homebrew’s core tap so if you want to use the versions from our this tap, you need to refer to those formulae by their full names, i.e., altinity/clickhouse/clickhouse-cpp and altinity/clickhouse/clickhouse-odbc. We encourage you to install these versions as they are built by following the recommendations of the original developers, which is not always possible with the formulae in the core tap due to imposed restrictions by Homebrew maintainers for formulae there.

Step 3 (optional): Start the ClickHouse server

Never use sudo. The recommended way of starting the ClickHouse server is via Homebrew services commands:

$ brew services start clickhouse

Note, that start command will also enable the service to be started at system boot. If the server process is stopped for any reason, it will be restarted automatically.

If you want to manually run the server process, you need to pass the flags that will tell it where to look for the config that reflects this installation, etc.:

$ $(brew --prefix clickhouse)/bin/clickhouse server --config-file $(brew --prefix)/etc/clickhouse-server/config.xml --pid-file $(brew --prefix)/var/run/clickhouse-server/clickhouse-server.pid

Step 4 (optional): Run the ClickHouse client

Now that ClickHouse is installed, and the server is running, the following command will start the client and connect it to the locally running server:

$ clickhouse client -q 'SELECT version()'
21.12.2.1

Paths

Homebrew installs everything under its own prefix and keeps it separate from the system. Each package in its turn is installed under its dedicated prefix, and then, unless keg-only, linked into the main UNIX-style directory structure. Same applies to the rest of the paths that the installed software might use, like configs in …/etc/, logs in …/var/log/, etc.

Here is where to look for the directories that are used by Homebrew installation of ClickHouse:

ClickHouse installation directory	$(brew --prefix clickhouse)
Config files	$(brew --prefix)/etc/clickhouse-server/
Data files	$(brew --prefix)/var/lib/clickhouse/
Log files	$(brew --prefix)/var/log/clickhouse-server/
Server process PID file	$(brew --prefix)/var/run/clickhouse-server/

All these files and directories, except the content of ClickHouse installation directory, will be preserved between installations.

For a versioned formula (see below) the paths are the same, only the ClickHouse installation directory will have the corresponding suffix, e.g., $(brew --prefix clickhouse@21.11).

Multiple versions

The tap defines several versioned formulae, which you might want to experiment with or use in parallel with the default one. All versioned formulae can be installed manually and coexist with each other, as well as with the latest one. However, make sure that there is only one instance of the server running at the same time when started via brew services, since they are going to use the same data and config paths, ports, etc.

All of the versioned formulae are marked as keg-only which means they will not be linked in the default paths. Only the latest one is installed as a default version of ClickHouse and can be called directly. To install and run a specific versioned formula, execute:

$ brew install clickhouse@21.11
...
# Make sure this is going to be the only running server instance.
$ brew services start clickhouse@21.11
...
$ $(brew --prefix clickhouse@21.11)/bin/clickhouse client -q 'SELECT version()'
21.11.8.4

Bottles and building from sources

Formulae are recipes for building the package from sources, but they also can have references to the precompiled packages that can be installed directly and save you time.

Those packages are called bottles. For formulae in this tap, bottles are available for the following platforms:

• macOS Monterey on Intel
• macOS Monterey on Apple silicon

We plan to extend the list of supported versions of macOS in the near future.

If your platform is not in this list, you still can install the formula, you will just need to wait until ClickHouse is built in-place from the sources. If this is the case, it is worth adding --verbose flag to see the progress:

$ brew install --verbose clickhouse

The build can take anywhere from 20 minutes to 3 hours.

You can also build the latest version of the sources for a formula:

$ brew install --HEAD --verbose clickhouse

The above command will check out the tip of the branch that corresponds to that specific version (e.g., branch 21.11 for clickhouse@21.11 and so on) and build it from sources. There are no bottles for HEAD versions of the formulae.

Conclusion

For macOS users, running ClickHouse meant manually downloading binaries, setting up the paths, the start-up commands, and taking on all of the steps themselves. Or downloading the source code and starting the lengthy process to compile ClickHouse themselves – then manually place the binaries where needed.

With brew, macOS developers and systems operators can type in a few commands and retrieve their preferred version of ClickHouse – whether the community build or the Altinity Stable version – and get right to work with the lightning fast analytics database.

For more information, make sure you visit our documentation page, and check out other articles about Altinity Stable for ClickHouse from the Altinity Resources page.