clickhouse-client --query: Run SQL in CI
clickhouse-client --query "<sql>" sends one statement to the ClickHouse server, prints the result, and exits.
clickhouse-client is the native CLI for ClickHouse. --query is the non-interactive entry point for schema setup, seeding, and assertions in a pipeline.
What it does
clickhouse-client --query executes a single SQL statement over the native TCP protocol (default port 9000) and exits. You can also pipe data into a query, for example feeding a file into an INSERT, which is the common bulk-load pattern in CI.
Common usage
clickhouse-client --host localhost --query "SELECT version()"
# create a table, then load rows from stdin
clickhouse-client --query "CREATE TABLE IF NOT EXISTS app.events (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY id"
cat events.csv | clickhouse-client --query "INSERT INTO app.events FORMAT CSV"Options
| Flag | What it does |
|---|---|
| --query <sql> | Run one statement and exit |
| --host / --port | Server address (native protocol, default 9000) |
| --user / --password | Credentials |
| --database <db> | Default database for the query |
| --format <fmt> | Output format (TabSeparated, JSON, CSV, ...) |
| --multiquery | Allow several semicolon-separated statements |
In CI
Pipe CSV/TSV into an INSERT ... FORMAT statement rather than building giant VALUES lists; it is faster and avoids shell length limits. The native client uses port 9000, not the HTTP port 8123, so a port-mapping mistake is a common cause of connection failures.
Common errors in CI
"Code: 210. DB::NetException: Connection refused (localhost:9000)" means the server is not up or you targeted the HTTP port. "Code: 516. Authentication failed" means wrong --user/--password. "Code: 81. Database app does not exist" means you skipped creating the database first. "Code: 62. Syntax error" points at the SQL.