Перейти к основному содержанию
clickhousectl (псевдоним chctl) — официальный CLI для ClickHouse, от локальной разработки до ClickHouse Cloud. Он подходит как для работы вручную в терминале, так и для скриптов и агентов для программирования. С помощью clickhousectl можно:
  • Устанавливать локальные версии ClickHouse и переключаться между ними, запускать изолированные локальные серверы и выполнять SQL-запросы
  • Локально запускать Postgres в Docker
  • Создавать, настраивать и масштабировать сервисы ClickHouse Cloud, создавать их резервные копии и выполнять к ним запросы
  • Создавать, отслеживать, настраивать и восстанавливать сервисы ClickHouse Managed Postgres
  • Создавать ClickPipes и управлять ими для приёма данных из объектного хранилища, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB и BigQuery
  • Управлять источниками, панелями мониторинга, оповещениями, вебхуками, сохранёнными поисками и ролями в сервисе Управляемый ClickStack
  • Разрабатывать исполняемые UDF локально и развертывать их в ClickHouse Cloud
  • Управлять участниками организации, приглашениями, ключами API и ролями
  • Устанавливать официальные ClickHouse agent skills в агенты для программирования
На этой странице приведены типичные примеры. Исчерпывающую справку по каждой команде и флагу выводит clickhousectl <command> --help. Справка большинства команд завершается блоком CONTEXT FOR AGENTS; для команд Cloud в нём также перечислены разрешения ключа API, необходимые для их выполнения. Пошаговые инструкции по конкретным задачам доступны по ссылкам на руководства в каждом разделе. Обзор, ориентированный на Cloud, см. в разделе ClickHouse CLI.

Установка

clickhousectl работает в macOS и Linux на архитектурах ARM64 и x86_64.
Скрипт устанавливает ~/.local/bin/clickhousectl и создаёт псевдоним chctl. Убедитесь, что каталог ~/.local/bin добавлен в переменную PATH. Его также можно установить с помощью менеджера пакетов: Псевдоним chctl создают только установочный скрипт и npm. Чтобы обновить уже установленную версию, выполните clickhousectl update (см. Самообновление).

Требования

  • Docker — только для локального Postgres
  • Для команд Cloud — аккаунт ClickHouse Cloud. Команды чтения работают с OAuth-аутентификацией через браузер (cloud auth login). Для создания или изменения ресурсов нужен ключ API. Подробнее см. в разделе Аутентификация.

Локальные команды

Локальные команды выполняются в текущем каталоге. Каждый проект хранит данные своего сервера в .clickhouse/, а исполняемые файлы ClickHouse хранятся глобально в ~/.clickhouse/ и используются всеми проектами совместно. CLI не ищет родительские каталоги, поэтому запускайте локальные команды из корневого каталога проекта. Полное описание рабочего процесса приведено в руководстве по локальной разработке.

Установка и выбор версий

local use при необходимости устанавливает версию, назначает её версией по умолчанию для последующих запусков сервера и создаёт на неё символическую ссылку ~/.local/bin/clickhouse, чтобы clickhouse client и clickhouse local были доступны через PATH. Чтобы не создавать символическую ссылку, передайте --no-global. Если по этому пути уже находится обычный файл, он не изменяется. local remove не удаляет версию по умолчанию, а также версию, которую использует запущенный сервер в каком-либо проекте. С флагом --force такие серверы останавливаются, а версия удаляется; при этом сбрасывается версия по умолчанию и удаляется символическая ссылка.

Инициализация проекта

Команда init необязательна. Она создаёт каталог .clickhouse/ для данных среды выполнения (он добавляется в git-ignore), а также заготовки SQL-файлов, которые можно закоммитить: clickhouse/ (tables/, materialized_views/, queries/, seed/, udfs/) и postgres/ (tables/, views/, functions/, queries/, seed/). При повторном запуске создаётся только то, чего ещё нет.

Запуск локальных серверов

У каждого именованного сервера есть собственные данные в .clickhouse/servers/<name>/data/, и при остановке сервера они сохраняются до следующего запуска. Если имя не указано, первый сервер получает имя default; если default уже запущен, генерируется новое имя. По умолчанию используются порты HTTP 8123 и TCP 9000; если они заняты, назначаются свободные. --version задаёт версию только для данного запуска, не меняя версию по умолчанию. Если запустить сервер без указания версии, когда версия по умолчанию не задана, будет установлена latest, но она не станет версией по умолчанию; чтобы сделать её таковой, сначала выполните local use latest.

Выполнение SQL-запросов с помощью локального клиента

local client подключается к именованному серверу с помощью того же бинарного файла ClickHouse, которым этот сервер запущен (имя по умолчанию: default). Аргументы после -- передаются в clickhouse client без изменений. Вывод и код выхода формирует clickhouse client — даже в режиме JSON, поэтому в скриптах задавайте формат вывода SQL явно.

Пользовательская конфигурация сервера

Поместите частичную конфигурацию в формате XML или YAML в каталог ~/.clickhouse/configs/ и укажите её имя при запуске сервера:
Файл накладывается поверх встроенных значений по умолчанию, поэтому в нём достаточно указать только те настройки, которые вы меняете. Выбор не запоминается: при последующем запуске без --config оверлей удаляется. Управляемые пути к данным и порты всегда имеют приоритет над значениями из конфигурации.

Запись сведений о подключении в файл dotenv

dotenv считывает фактические порты запущенного сервера и записывает CLICKHOUSE_HOST, CLICKHOUSE_PORT и CLICKHOUSE_HTTP_PORT, а также пользователя, пароль и базу данных, если они переданы. Остальные строки в существующем файле сохраняются. Загружайте файл с помощью dotenv-загрузчика вашего приложения; никогда не передавайте выведенный на экран предварительный результат в eval.

Локальный Postgres

Локальный Postgres работает в Docker, поэтому Docker должен быть запущен. Поддерживаются Postgres 17 и 18, в том числе теги образов вида 18-alpine; новые инстансы по умолчанию создаются с версией 18.
Инстанс определяется своим именем и мажорной версией. При возобновлении остановленного инстанса используются его прежние порт, пользователь, пароль и база данных, поэтому флаги, заданные при создании, на возобновление не влияют. Если пароль не указан явно, генерируется случайный. Файл .env.local содержит пароль, поэтому не добавляйте его в систему контроля версий.

Локальные UDF

local udf развертывает исполняемые UDF из clickhouse/udfs/<name>/ на локальном сервере. cloud udf загружает тот же каталог в Cloud (см. UDF в Cloud).
Все команды, кроме init, принимают параметр --server <name> (по умолчанию — default). Команда deploy проверяет корректность udf.json так же, как это делает Cloud. На работающем сервере она перезагружает функции и проверяет, что функция загружена. Локальное развертывание со средой выполнения native поддерживается только на хостах Linux с архитектурой amd64 или arm64. См. руководство по пользовательским функциям.

Аутентификация

Команды Cloud используют один из двух типов учётных данных: Если у вас еще нет аккаунта ClickHouse Cloud, clickhousectl cloud auth signup откроет страницу регистрации в вашем браузере.

Вход через OAuth

Это откроет браузер для прохождения OAuth Device Flow. Токены сохраняются глобально в ~/.clickhouse/tokens.json и обновляются автоматически.
Доступ через OAuth предоставляется только для чтения. Чтобы создавать или изменять ресурсы, войдите с помощью ключа API.

Ключ API

Создайте ключ API с ролями, которые требуются вашим командам, и сохраните его. При интерактивном вводе секрет не попадает в историю командной оболочки:
При входе ключ проверяется, и выводится идентичность, которой он принадлежит. Если API отклоняет ключ, он не сохраняется, а команда завершается с кодом 4. Если API недоступен, ключ сохраняется с предупреждением. В CI и других сценариях автоматизации не сохраняйте ключ, а передавайте его через менеджер секретов:
При разработке CLI также считывает эти переменные из файла .env в текущем каталоге. Не добавляйте .env в систему контроля версий.

Проверка и очистка учётных данных

whoami работает с учётными данными любого типа и завершается с кодом 4, если учётные данные отклонены. status может завершиться с кодом 0, даже если ни одни из учётных данных не подходят, поэтому для проверки доступа используйте whoami. Выход из системы не сбрасывает переменные окружения и не изменяет файл .env.

Приоритет учётных данных

Используется первый из доступных источников:
  1. Флаги --api-key и --api-secret
  2. .clickhouse/credentials.json
  3. Экспортированные переменные окружения
  4. Переменные из файла .env в текущем каталоге
  5. Глобальные OAuth-токены
Добавьте флаг --debug к любой команде cloud, чтобы вывести в stderr выбранный источник учётных данных и URL API:

Выбор организации

Команды уровня организации выбирают её автоматически, только если ваши учётные данные дают доступ ровно к одной организации. В противном случае укажите --org-id или --org-name с точным названием организации:
Большинство команд для работы с ресурсами принимают позиционный аргумент ID или точное значение --name. О разрешениях, ключах с ограниченными правами и очистке данных при выходе из системы см. раздел «Аутентификация и доступ».

Cloud

Команды Cloud обращаются к ClickHouse Cloud API. Запросы на создание и обновление завершаются сразу после того, как API их принимает, поэтому периодически опрашивайте get, пока ресурс не перейдёт в нужное состояние.

Сервисы

Сохраните начальный пароль, который отображается при создании: он выводится только один раз. Команда создания завершается раньше, чем заканчивается подготовка, поэтому повторно выполняйте get, пока состояние не станет running. Если не указать --ip-allow, доступ будет разрешён со всех IP-адресов (0.0.0.0/0). Записи задаются в формате IP_OR_CIDR=DESCRIPTION. Чтобы восстановить резервную копию в новый сервис, используйте --backup-id, а чтобы разместить сервис в BYOC infrastructure — --byoc-id. Обновление, масштабирование и настройка сервиса:
Объём памяти на реплику должен быть кратен 4 ГБ и составлять не более 120 ГБ для бесплатных и 356 ГБ для платных сервисов; допускается до 50 реплик. Ограничения на уровне организации и хранилища могут снижать эти значения. Для горизонтального автомасштабирования в организации должна быть включена соответствующая возможность. Команда update изменяет только переданные флаги. Другие группы команд сервиса: settings (list, get, schema, set, unset), scaling-schedule, upgrade-window, replica-aware-routing (бета), snapshot (бета), private-endpoint, backup-config и prometheus. Подробнее см. в руководстве Создание сервиса ClickHouse Cloud и работа с ним.

API запросов

cloud service query выполняет один оператор SQL по HTTP — без локального исполняемого файла clickhouse и без пароля сервиса:
  • OAuth выполняет запрос от вашего имени с доступом к SQL только для чтения. К сервису ничего не привязывается.
  • Ключ API: при первом вызове clickhousectl добавляет ваш ключ API к конечной точке API запросов сервиса и при необходимости создаёт эту конечную точку с ролями sql_console_admin. Существующие роли, источники (origins) и другие привязки ключей сохраняются, новый ключ не создаётся. Изменяя конечную точку, CLI выводит в stderr сообщение Binding the authenticated API key to the Query API endpoint for service '<name>'.... Чтобы в этом случае команда завершалась с ошибкой, передайте --no-auto-enable.
Ключ для конкретного сервиса, сохранённый более ранней версией CLI, по-прежнему имеет приоритет для этого сервиса. Если API его отклоняет, замените его явно командой cloud service repair-query-key <service-id>. API запросов принимает один оператор на запрос. Примерно через 30 секунд ожидание может прерваться по тайм-ауту, при этом SQL продолжит выполняться, поэтому перед повторной попыткой записи проверьте результат. Для скриптов из нескольких операторов, пакетных загрузок и длительных запросов используйте clickhouse client. Список разрешённых IP-адресов сервиса ограничивает прямые подключения, но не проксируемый маршрут API запросов. Запрос к бездействующему сервису пробуждает его; остановленный сервис необходимо запустить командой cloud service start. Управление конечной точкой API запросов сервиса, именованными конечными точками SQL и сохранёнными запросами:
query-endpoint create заменяет роли всех ключей, привязанных к конечной точке. См. Поведение SQL и API запросов.

Managed Postgres

cloud postgres управляет ClickHouse Managed Postgres. Эти команды находятся в стадии бета, а поддержка GCP доступна в рамках закрытой предварительной версии.
Для AWS доступны размеры m6gd.large, c6gd.xlarge и r6gd.xlarge. Для GCP укажите --provider gcp, регион GCP и размер, например c4-standard-lssd-4. Сохраните пароль и строку подключения из вывода create. Последующие ответы get не содержат учётных данных, а получить новые можно только с помощью reset-password. Подключайтесь через psql с параметром sslmode=verify-full и файлом CA. Если при создании не указать флаги доступа, к Postgres (5432) и PgBouncer (6432) будет разрешён доступ со всех IPv4- и IPv6-адресов. Передавайте по одному --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION] на каждое правило или --block-public-access, чтобы не задавать ни одного правила. Если указано хотя бы одно правило, действуют только явно перечисленные правила. Мониторинг и восстановление:
cloud postgres query поддерживает только OAuth, поэтому команда завершается ошибкой, пока активен источник ключа API с более высоким приоритетом. Для мониторинга предназначены metrics, slow-queries и prometheus. restore копирует текущие правила доступа IPv4 исходного сервиса в восстановленный сервис, если не указаны --ip-allow или --block-public-access. Операции восстановления и создания реплик возвращают результат без пароля. promote и switchover завершаются сразу после принятия запроса; после выполнения promote периодически опрашивайте postgres get --json, пока реплика не вернёт isPrimary: true. См. руководство по Managed Postgres.

ClickPipes

cloud clickpipe выполняет приём данных из объектного хранилища, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB и BigQuery. Для создания ClickPipe и обнаружения схемы требуются ключ API и работающий целевой сервис. Для каждого источника предусмотрена отдельная подкоманда clickpipe create <source>; чтобы получить список её флагов, запустите её с --help. Загрузка файлов из S3 с использованием роли IAM. Сначала выполните обнаружение схемы, затем выберите столбцы:
Реплицируйте Postgres с помощью CDC (фиксации изменений данных). По умолчанию TLS-соединение проверяется; если источником служит Managed Postgres, экспортируйте его сертификат CA и передайте его:
--table-mapping создаёт таблицы ReplacingMergeTree, поэтому текущее состояние следует читать с FINAL WHERE _peerdb_is_deleted = 0. Для пайпа Kafka порядок действий тот же: выполните clickpipe schema-discover kafka с теми же флагами источника, а затем передайте столбцы:
По умолчанию пайпы BigQuery создают снимок. Для CDC (фиксации изменений данных) передайте --replication-mode cdc, --replication-method, а также в --table-mapping-json укажите для каждой таблицы столбец водяной метки или функцию событий; расписание синхронизации задаётся с помощью --sync-cron или --sync-interval-seconds. Управление существующими пайпами:
Перед выполнением update CDC-пайпы должны находиться в состоянии Paused: остановите пайп, периодически вызывайте get, пока пайп не перейдёт в состояние Paused, а затем обновите его. Сервис может сам возобновить пайп в ходе обновления, поэтому выполняйте start, только если get по-прежнему показывает Paused. Параметр --start-paused доступен для объектного хранилища, Kafka, Kinesis и Pub/Sub. Прочие группы команд: cdc-scaling, context get (готовность GCP workload identity и субъект) и reverse-private-endpoint. Подробнее см. руководство по ClickPipes и справочник по конфигурации ClickPipe.

ClickStack

cloud clickstack управляет источниками, панелями мониторинга, оповещениями, вебхуками, сохранёнными поисками и ролями в существующем сервисе Управляемый ClickStack. Ресурсы описываются в JSON‑файлах (--file или - для stdin). Для операций чтения поддерживается OAuth, а для операций записи требуется ключ API.
Каждое обновление ClickStack полностью перезаписывает ресурс. Сохраните текущее состояние с помощью get --json и передавайте полное определение, а не только изменённые поля. Подробнее см. руководство по ClickStack.

UDF в Cloud

cloud udf управляет исполняемыми UDF уровня организации, их версиями и привязками к сервисам. deploy загружает каталог, протестированный с помощью local udf, дожидается завершения сборки, подключает эту версию и ждёт, пока она не будет развернута:
Чтобы выполнить каждый шаг вручную, используйте udf create, udf version create, udf attach (с флагом --wake для бездействующего сервиса), udf detach и udf delete. Эти команды возвращают управление сразу после принятия запроса; чтобы отслеживать состояние, периодически опрашивайте udf get и udf attachment get. Операции чтения поддерживают OAuth, а для операций записи требуется ключ API. Подробнее см. руководство по пользовательским функциям.

Организации и доступ

Подкоманды cloud org принимают --org-id, а не позиционный ID. org usage охватывает период не более 31 дня. Кроме того, у org есть подкоманды quota, balance, notification-types, role (пользовательские роли организации) и byoc (BYOC infrastructure). Уведомления находятся в статусе бета. Управление участниками, приглашениями и ключами API:
Если при выполнении key create не указать --ip-allow, любой сетевой доступ будет запрещён, — в отличие от создания сервиса. Секрет отображается только один раз. Команда key list возвращает только одну страницу, если не передать --all. При выполнении key update неуказанные флаги сохраняют текущие значения, а --clear-expiry, --clear-roles и --clear-ip-allow сбрасывают соответствующие настройки.

Резервные копии

При восстановлении всегда создаётся новый сервис. Команда cloud backup bucket (get, create, update, delete) настраивает собственный бакет для резервных копий с помощью JSON‑файла, формат которого зависит от провайдера. Подробнее см. раздел о резервном копировании в руководстве по сервису ClickHouse Cloud.

Вывод в формате JSON

Команды, возвращающие структурированные данные, поддерживают флаг --json. К ним относятся локальные команды, команды Cloud, а также команды skills, update и telemetry:
Когда CLI обнаруживает агента для программирования (например, Claude Code, Cursor, Codex, Gemini CLI, Goose или Devin, а также любой инструмент, задающий AI_AGENT), он автоматически переключается на JSON. SQL-клиенты и нативные клиенты используют собственные форматы: cloud service query в режиме JSON возвращает JSONEachRow, а local client всегда выводит данные в нативном формате. Скрипты, которые разбирают вывод запросов, должны явно указывать --format. В режиме JSON ошибки среды выполнения выводятся в stderr в виде объекта со стабильным полем code и полем message:
Ветвите логику по error.code, а не по тексту сообщения. Ошибки использования (usage errors) по-прежнему выводятся в виде текста с кодом выхода 2. Описание форм вывода и кодов ошибок см. в разделе контракты автоматизации и вывода.

Коды выхода

local client, local postgres client и другие команды, передающие управление нативным клиентам, возвращают собственный код выхода клиента.

Навыки для агентов

Установите официальный пакет ClickHouse agent skills в используемые вами агенты для программирования:
По умолчанию навыки устанавливаются в текущий проект, а с флагом --global — в ваш домашний каталог. Общий каталог .agents/skills/ подключается всегда. При запуске без терминала необходимо указать --agent, --all или --detected-only. Чтобы получить список имён поддерживаемых агентов, выполните clickhousectl skills --help.

Самообновление

CLI также проверяет наличие обновлений в фоновом режиме (не чаще одного раза в 24 часа) и выводит уведомление, если доступна новая версия.

Телеметрия

clickhousectl собирает анонимные данные об использовании, которые помогают определять направление разработки. При первом запуске выводится уведомление, и никакие данные не отправляются; сбор начинается со следующего запуска, если вы его не отключите. Каждое событие содержит:
  • Путь команды и имена явно переданных флагов и аргументов — но не их значения
  • Результат выполнения и код выхода
  • Для команды с опечаткой — имя команды или флага, предложенное CLI, но не то, что вы ввели
  • Для сбоев во время выполнения — ограниченный набор категорий: стадия и вид сбоя, HTTP-статус из списка разрешённых, а также категории повторных попыток, состояния подготовки ресурсов и длительности
  • Версия CLI, ОС и архитектура, признак запуска в CI и обнаруженный агент для программирования
Значения аргументов, SQL-запросы, учётные данные, идентификаторы ресурсов, аргументы после -- и сообщения об ошибках никогда не записываются. Идентификатор установки или устройства не используется. Чтобы отказаться от сбора данных:
Задайте CHCTL_TELEMETRY_DEBUG=1, чтобы выводить полезную нагрузку в stderr, ничего не отправляя. Подробнее см. в описании телеметрии.