Native и HTTP протоколы

ClickHouse предоставляет четыре способа подключения, каждый из которых оптимален для своего сценария. Правильный выбор протокола влияет на производительность, совместимость с инструментами и простоту интеграции.

Native TCP (порт 9000)

Native TCP — бинарный протокол ClickHouse с колоночным layout данных:

# clickhouse-client по умолчанию использует Native TCP (порт 9000)
clickhouse-client --host localhost --port 9000 --query "SELECT count() FROM events"

# Python: clickhouse-driver использует Native TCP
from clickhouse_driver import Client
client = Client('localhost', port=9000)
result = client.execute("SELECT count() FROM events")

Характеристики:

• Бинарный протокол, минимальный overhead на сериализацию
• Колоночная передача данных (Native format)
• Поддержка сжатия (lz4, zstd) на уровне протокола
• Streaming результатов (не буферизует весь ответ в памяти)
• Используется для server-to-server: Distributed queries, репликация

HTTP (порт 8123)

HTTP-интерфейс — REST-like API, совместимый с любым HTTP-клиентом:

# Простой запрос через curl
curl 'http://localhost:8123/?query=SELECT+1'

# Запрос с результатом в JSONEachRow
curl 'http://localhost:8123/?query=SELECT+user_id,+event_type+FROM+events+FORMAT+JSONEachRow'

# POST с телом запроса
curl -X POST 'http://localhost:8123/' \
  --data "SELECT count() FROM events FORMAT JSON"

# Проверка здоровья (monitoring-friendly)
curl 'http://localhost:8123/?query=SELECT+1'
# Ответ: 1

Характеристики:

• Работает с любым HTTP-клиентом: curl, httpx, requests, wget
• JDBC/ODBC-драйверы часто используют HTTP-интерфейс
• Поддерживает все FORMAT-ы (JSONEachRow, CSV, Parquet, Arrow)
• Подходит для мониторинга: простой healthcheck через ?query=SELECT+1
• Загрузка больших файлов через multipart POST

MySQL wire protocol (порт 9004)

ClickHouse поддерживает MySQL wire protocol — клиенты, написанные для MySQL, могут подключаться к ClickHouse без изменений:

<!-- /etc/clickhouse-server/config.d/mysql_port.xml -->
<clickhouse>
    <mysql_port>9004</mysql_port>
</clickhouse>

После включения MySQL-совместимые клиенты подключаются напрямую:

# MySQL client подключается к ClickHouse
mysql --host=localhost --port=9004 --user=default --password='' -e "SELECT count() FROM events"

# Grafana: добавить ClickHouse как MySQL-источник (host:9004)
# Metabase, Superset, Redash: MySQL connector → ClickHouse

Используйте, когда: нужна совместимость с BI-инструментами, поддерживающими только MySQL (Grafana MySQL source, старые JDBC-драйверы).

PostgreSQL wire protocol (порт 9005)

Аналогично MySQL wire protocol, ClickHouse поддерживает PostgreSQL wire protocol:

<!-- /etc/clickhouse-server/config.d/pg_port.xml -->
<clickhouse>
    <postgresql_port>9005</postgresql_port>
</clickhouse>

# psql подключается к ClickHouse как к PostgreSQL
psql -h localhost -p 9005 -U default -c "SELECT count() FROM events"

# Python psycopg2 подключается к ClickHouse
import psycopg2
conn = psycopg2.connect(host='localhost', port=9005, database='default', user='default', password='')

Используйте, когда: нужна совместимость с PostgreSQL-совместимыми клиентами и BI-инструментами (pgAdmin, DBeaver с PostgreSQL-драйвером).

Сравнение протоколов

Когда выбирать какой протокол

Native TCP (9000):

• clickhouse-client в CLI
• Server-to-server: Distributed queries, INSERT от другого ClickHouse
• Python (clickhouse-driver) для максимальной производительности

HTTP (8123):

• Любой HTTP-клиент без специализированного драйвера
• JDBC/ODBC через clickhouse-java или clickhouse-native-jdbc
• Мониторинг и healthcheck
• REST API для веб-приложений

MySQL wire (9004):

• BI-инструменты, поддерживающие только MySQL: Grafana MySQL source
• Существующая инфраструктура с MySQL-драйверами
• Не нужно устанавливать специфичный ClickHouse-драйвер

PostgreSQL wire (9005):

• psql CLI и PostgreSQL-совместимые клиенты
• pgAdmin, DBeaver с PostgreSQL-профилем
• Инфраструктура, стандартизованная на PostgreSQL-совместимых подключениях

Ключевые выводы

1. ClickHouse поддерживает четыре протокола подключения: Native TCP (9000), HTTP (8123), MySQL wire (9004), PostgreSQL wire (9005).
2. Native TCP — самый быстрый: бинарный колоночный формат, lz4/zstd сжатие, streaming без буферизации.
3. HTTP (8123) — универсальный: работает с curl, JDBC/ODBC, REST API, мониторингом.
4. MySQL (9004) и PostgreSQL (9005) wire protocols выключены по умолчанию, включаются через mysql_port/postgresql_port в config.xml.
5. Для BI-инструментов (Grafana, Metabase) используй MySQL wire protocol если нет нативного ClickHouse-коннектора.