ClickHouse на сервере: частые ошибки и решения

MAATRIX

Ошибки ClickHouse на сервере чаще всего связаны с памятью, дисками и особенностями его архитектуры. Ниже — разбор частых проблем: memory limit exceeded, connection refused, «too many parts», отказ авторизации и переполнение диска. Для каждой сначала решение, потом причина — чтобы починить быстро и понять, как выстроить работу так, чтобы ошибка не повторялась. ClickHouse — мощный аналитический движок, и большинство его ошибок это сигналы о том, что нагрузка переросла настройки или ресурсы.

Memory limit exceeded

Самая частая ошибка: Memory limit (for query) exceeded. Запрос попытался занять больше памяти, чем разрешено профилем. Это защита, а не поломка — без неё один тяжёлый запрос уронил бы весь сервер. Сначала поймите, упёрлись вы в лимит на запрос или в общий лимит сервера:

clickhouse-client --query "SELECT value FROM system.settings WHERE name='max_memory_usage'"

Если запрос действительно тяжёлый (агрегация по огромной таблице, GROUP BY с высокой кардинальностью), правильное решение — не задирать лимит, а оптимизировать запрос: добавить фильтр по ключу партиционирования, уменьшить объём читаемых данных, использовать приближённые функции вроде uniqCombined вместо точных. Если же лимит выставлен неоправданно низко для вашего сервера, аккуратно поднимите max_memory_usage, оставив запас RAM системе и другим запросам.

Отдельный случай — Memory limit (total) exceeded, когда суммарно все запросы превысили общий лимит сервера. Это значит, что параллельных тяжёлых запросов слишком много для вашей памяти. Ограничьте число одновременных запросов или, если нагрузка стабильно высокая, добавьте RAM — это честный сигнал, что серверу тесно.

Connection refused

Code: 210. Connection refused или невозможность подключиться клиентом означает, что сервер не слушает по указанному адресу и порту. Проверьте статус и порты:

sudo systemctl status clickhouse-server
sudo ss -ltnp | grep -E '8123|9000'

Если процесса нет, смотрите журнал /var/log/clickhouse-server/clickhouse-server.err.log — там будет причина, по которой сервер не поднялся. Частые причины: ошибка в XML-конфиге после ручной правки (ClickHouse строг к синтаксису), нехватка памяти на старте или занятый порт. Если сервер работает, но слушает только localhost, а вы подключаетесь снаружи, добавьте нужный адрес в <listen_host> и перезапустите.

Помните про два разных порта: 8123 — HTTP-интерфейс, 9000 — нативный протокол для clickhouse-client. Если приложение использует HTTP, а открыт только нативный порт (или наоборот), будет отказ. Проверьте, какой порт реально нужен вашему клиенту, и что именно он открыт фаерволом.

Too many parts

Ошибка Too many parts — специфична для ClickHouse и очень показательна. Движок MergeTree хранит данные кусками (parts) и в фоне сливает их. Если вы вставляете данные слишком часто мелкими порциями, куски образуются быстрее, чем движок успевает их сливать, и срабатывает защита. Решение почти всегда в изменении способа вставки, а не в настройках сервера.

Главное правило: вставляйте данные большими пачками, а не по одной строке. Вместо тысячи вставок по строке делайте одну вставку на тысячу строк. Если данные идут потоком, буферизуйте их на стороне приложения или используйте таблицу с движком Buffer, которая накапливает вставки и сбрасывает их пачками. Частая вставка мелкими порциями — антипаттерн для ClickHouse, и Too many parts прямо на него указывает. Увеличивать лимит parts_to_throw_insert — плохая идея: вы лишь отодвинете проблему, а слияние кусков будет отставать всё сильнее.

Ошибки авторизации

Authentication failed или Password for user is not correct — пароль не совпадает или пользователь настроен иначе, чем вы подключаетесь. Проверьте список пользователей и способ их аутентификации:

clickhouse-client --query "SELECT name, auth_type FROM system.users"

Частая причина после установки — пользователь default остался с пустым паролем или, наоборот, вы задали пароль при установке и забыли передать его клиенту. Подключайтесь с флагом --password. Если пользователи заданы и через XML в users.xml, и через SQL, может возникнуть путаница: одна и та же учётка описана в двух местах с разными настройками. Держите управление пользователями в чём-то одном — либо SQL, либо XML, чтобы не ловить противоречия.

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

Переполнение диска и рост данных

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

df -h
clickhouse-client --query "SELECT table, formatReadableSize(sum(bytes)) FROM system.parts WHERE active GROUP BY table ORDER BY sum(bytes) DESC"

Главный инструмент управления объёмом — TTL и партиционирование. Если таблица разбита по месяцам через PARTITION BY toYYYYMM(...), старые данные удаляются мгновенно целым куском: ALTER TABLE logs.events DROP PARTITION '202501';. Ещё лучше задать автоматический TTL при создании таблицы, чтобы данные старше нужного срока удалялись сами. Это снимает проблему переполнения раз и навсегда, если объём поступающих данных предсказуем.

Если же данных объективно много и они все нужны, вывод честный: нужен диск большего объёма. В MAATRIX можно арендовать VPS в России, США или Великобритании с нужным объёмом SSD и памяти под ClickHouse и перенести данные без спешки. Оплата — картой РФ, по СБП, криптой или токеном MAAT, иностранная карта не требуется.

Как выстроить работу без частых ошибок

Большинство проблем ClickHouse решаются на этапе проектирования. Вставляйте данные пачками, а не по строке — это снимает Too many parts. Ставьте лимиты памяти на запрос — это снимает риск, что один отчёт уронит сервер. Продумывайте ORDER BY и PARTITION BY под свои запросы — это ускоряет чтение и упрощает удаление старых данных. Настройте TTL — и диск не переполнится. Эти четыре решения закрывают львиную долю всех типичных ошибок ещё до того, как они появятся.

Частые вопросы