ClickHouse Client

[Edit this page](https://github.com/ClickHouse/ClickHouse/tree/master/docs/en/interfaces/client.md)

ClickHouse provides a native command-line client for executing SQL queries directly against a ClickHouse server.
It supports both interactive mode (for live query execution) and batch mode (for scripting and automation).
Query results can be displayed in the terminal or exported to a file, with support for all ClickHouse output [formats](/docs/interfaces/formats), such as Pretty, CSV, JSON, and more.

The client provides real-time feedback on query execution with a progress bar and the number of rows read, bytes processed and query execution time.
It supports both [command-line options](#command-line-options) and [configuration files](#configuration_files).

## Install[​](#install "Direct link to Install")

To download ClickHouse, run:

```
curl https://clickhouse.com/ | sh
```

To also install it, run:

```
sudo ./clickhouse install
```

See [Install ClickHouse](/docs/install) for more installation options.

Different client and server versions are compatible with one another, but some features may not be available in older clients. We recommend using the same version for client and server.

## Run[​](#run "Direct link to Run")

Note

If you only downloaded but did not install ClickHouse, use `./clickhouse client` instead of `clickhouse-client`.

To connect to a ClickHouse server, run:

```
$ clickhouse-client --host server

ClickHouse client version 24.12.2.29 (official build).
Connecting to server:9000 as user default.
Connected to ClickHouse server version 24.12.2.

:)
```

Specify additional connection details as necessary:

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Option Description|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `--port <port>` The port ClickHouse server is accepting connections on. The default ports are 9440 (TLS) and 9000 (no TLS). Note that ClickHouse Client uses the native protocol and not HTTP(S).|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `-s [ --secure ]` Whether to use TLS (usually autodetected).|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `-u [ --user ] <username>` The database user to connect as. Connects as the `default` user by default.| `--password <password>` The password of the database user. You can also specify the password for a connection in the configuration file. If you do not specify the password, the client will ask for it.|  |  |  |  | | --- | --- | --- | --- | | `-c [ --config ] <path-to-file>` The location of the configuration file for ClickHouse Client, if it is not at one of the default locations. See [Configuration Files](#configuration_files).| `--connection <name>` The name of preconfigured connection details from the [configuration file](#connection-credentials). | | | | | | | | | | | | | |

For a complete list of command-line options, see [Command Line Options](#command-line-options).

### Connecting to ClickHouse Cloud[​](#connecting-cloud "Direct link to Connecting to ClickHouse Cloud")

The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console. Select the service that you want to connect to and click **Connect**:

  
  

Choose **Native**, and the details are shown with an example `clickhouse-client` command:

### Storing connections in a configuration file[​](#connection-credentials "Direct link to Storing connections in a configuration file")

You can store connection details for one or more ClickHouse servers in a [configuration file](#configuration_files).

The format looks like this:

```
<config>
    <connections_credentials>
        <connection>
            <name>default</name>
            <hostname>hostname</hostname>
            <port>9440</port>
            <secure>1</secure>
            <user>default</user>
            <password>password</password>
            <!-- <history_file></history_file> -->
            <!-- <history_max_entries></history_max_entries> -->
            <!-- <accept-invalid-certificate>false</accept-invalid-certificate> -->
            <!-- <prompt></prompt> -->
        </connection>
    </connections_credentials>
</config>
```

See the [section on configuration files](#configuration_files) for more information.

Note

To concentrate on the query syntax, the rest of the examples leave off the connection details (`--host`, `--port`, etc.). Remember to add them when you use the commands.

## Interactive mode[​](#interactive-mode "Direct link to Interactive mode")

### Using interactive mode[​](#using-interactive-mode "Direct link to Using interactive mode")

To run ClickHouse in interactive mode, simply execute:

```
clickhouse-client
```

This opens the Read-Eval-Print Loop (REPL) where you can start typing SQL queries interactively.
Once connected, you'll get a prompt where you can enter queries:

```
ClickHouse client version 25.x.x.x
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 25.x.x.x

hostname :)
```

In interactive mode, the default output format is `PrettyCompact`.
You can change the format in the `FORMAT` clause of the query or by specifying the `--format` command-line option.
To use the Vertical format, you can use `--vertical` or specify `\G` at the end of the query.
In this format, each value is printed on a separate line, which is convenient for wide tables.

In interactive mode, by default whatever was entered is run when you press `Enter`.
A semicolon is not necessary at the end of the query.

You can start the client with the `-m, --multiline` parameter.
To enter a multiline query, enter a backslash `\` before the line feed.
After you press `Enter`, you will be asked to enter the next line of the query.
To run the query, end it with a semicolon and press `Enter`.

ClickHouse Client is based on `replxx` (similar to `readline`) so it uses familiar keyboard shortcuts and keeps a history.
The history is written to `~/.clickhouse-client-history` by default.

To exit the client, press `Ctrl+D`, or enter one of the following instead of a query:

- `exit` or `exit;`
- `quit` or `quit;`
- `q`, `Q` or `:q`
- `logout` or `logout;`

### Query processing information[​](#processing-info "Direct link to Query processing information")

When processing a query, the client shows:

1. Progress, which is updated no more than 10 times per second by default.
   For quick queries, the progress might not have time to be displayed.
2. The formatted query after parsing, for debugging.
3. The result in the specified format.
4. The number of lines in the result, the time passed, and the average speed of query processing.
   All data amounts refer to uncompressed data.

You can cancel a long query by pressing `Ctrl+C`.
However, you will still need to wait for a little for the server to abort the request.
It is not possible to cancel a query at certain stages.
If you do not wait and press `Ctrl+C` a second time, the client will exit.

ClickHouse Client allows passing external data (external temporary tables) for querying.
For more information, see the section [External data for query processing](/docs/engines/table-engines/special/external-data).

### Aliases[​](#cli_aliases "Direct link to Aliases")

You can use the following aliases from within the REPL:

- `\l` - SHOW DATABASES
- `\d` - SHOW TABLES
- `\c <DATABASE>` - USE DATABASE
- `.` - repeat the last query

### Keyboard shortcuts[​](#keyboard_shortcuts "Direct link to Keyboard shortcuts")

- `Alt (Option) + Shift + e` - open editor with the current query. It is possible to specify the editor to use with the environment variable `EDITOR`. By default, `vim` is used.
- `Alt (Option) + #` - comment line.
- `Ctrl + r` - fuzzy history search.

The full list with all available keyboard shortcuts is available at [replxx](https://github.com/AmokHuginnsson/replxx/blob/1f149bf/src/replxx_impl.cxx#L262).

Tip

To configure the correct work of the meta key (Option) on MacOS: