ClickHouse Macintosh (Monterey) Client

How to install the ClickHouse Python terminal client on a Macintosh running Monterey using the Brew package installer, and connect to your Altinity.Cloud ClickHouse Cluster.

26 January 2023 · Read time 4 min

Overview - Macintosh ClickHouse Client

This section covers the installation and use of the Mac ClickHouse client.
After installation, you will be able to run ClickHouse queries from a Macintosh terminal.
The following ClickHouse install instructions using Brew is tested to work on Monterey (OS version 12.1)

Prerequisites

  • You have copied the Connection Details from your cluster.
  • Python version 3.7 (or later) is installed
  • The PIP Python Package installer is installed
  • The Brew package installer is installed

More information

Installing ClickHouse on macOS

Installation of the macOS ClickHouse client uses the Brew package installer.

To install macOS ClickHouse client:

  1. Enter each of the four lines in turn. The final step starts ClickHouse.

    brew tap altinity/clickhouse
    brew tap-info --json altinity/clickhouse
    brew install clickhouse
    brew services start clickhouse
    

Checking the ClickHouse Version Installed

This step checks the installed version of the ClickHouse macOS client.
You will note that it is not necessary to login to ClickHouse to run this command.

To check the installed ClickHouse version from a macOS terminal:

  1. Enter the following string:

    clickhouse client -q 'SELECT version()'
    22.7.2.1
    

Note that you are still in the macOS shell, not the ClickHouse interactive mode, as the following examples demonstrate.

Logging on to your ClickHouse cluster

To login to your cluster from the macOS terminal:

  1. From the Connection Details, copy and paste the string of text into the macOS terminal:

    clickhouse-client -h example-cluster.your-cluster.altinity.cloud --port 9440 -s --user=admin --password
    

ClickHouse terminal response

  1. Enter your ClickHouse cluster password at the prompt.

  2. The ClickHouse version number is displayed, and the interactive prompt mode shows:
    example-cluster :)

    ClickHouse client version 22.7.2.1.
    
    Password for user (admin): 
    ********
    
    Connecting to example-cluster.your-cluster.altinity.cloud:9440 as user admin.
    Connected to ClickHouse server version 22.3.15 revision 54455.
    
    ClickHouse server version is older than ClickHouse client. 
    It may indicate that the server is out of date and can be upgraded.
    
    example-cluster :) 
    

Running ClickHouse Queries

To display all the tables in your cluster from a macOS terminal:

  1. At the ClickHouse prompt, enter the query command show tables:

    example-cluster :) show tables
    
    SHOW TABLES
    
    Query id: c04f8699-33db-4f4f-9a5b-e92fd25b6bb6
    
    Password for user (admin):
    Connecting to example-cluster.your-cluster.altinity.cloud:9440 as user admin.
    Connected to ClickHouse server version 22.3.15 revision 54455.
    
    ClickHouse server version is older than ClickHouse client. 
    It may indicate that the server is out of date and can be upgraded.
    
    ┌─name─────────┐
    │ events       │
    │ events_local │
    └──────────────┘
    
    2 rows in set. Elapsed: 0.073 sec.
    

To display the data in the in your cluster table named events from a macOS terminal:

  1. At the ClickHouse prompt, enter the query command select * from events:

    example-cluster :) select * from events
    
    SELECT *
    FROM events
    
    Query id: 998dbb3e-786e-404e-9d17-f044a6098191
    
    Password for user (admin):
    Connecting to example-cluster.your-cluster.altinity.cloud:9440 as user admin.
    Connected to ClickHouse server version 22.3.15 revision 54455.
    
    ClickHouse server version is older than ClickHouse client. 
    It may indicate that the server is out of date and can be upgraded.
    
    ┌─event_date─┬─event_type─┬─article_id─┬─title───┐
    │ 2023-01-04 │          113 │ Example │
    │ 2023-01-10 │          113 │ Example │
    │ 2023-01-10 │          114 │ Example │
    └────────────┴────────────┴────────────┴─────────┘
    
    3 rows in set. Elapsed: 0.074 sec.
    
    example-cluster :)
    

To quit, or exit from the ClickHouse interactive mode:

  1. Enter the exit command to return to your macOS shell environment.

    example-cluster :) exit
    Bye.
    

This concludes the Quick Start instructions for how to install and use the Macintosh ClickHouse terminal client.


Related links

Last modified 2023.01.26: Getting Started rewrite