Перейти к основному содержанию
ClickHouse CLI (clickhousectl, псевдоним chctl) позволяет управлять ClickHouse Cloud из терминала, скрипта или агента для программирования. На этой странице описаны возможности CLI, относящиеся к Cloud. Сведения обо всех группах команд и локальной разработке, а также полное описание работы CLI см. в справочнике по clickhousectl.

Чем можно управлять

Команды clickhousectl cloud позволяют работать со следующим:
  • Сервисы: создание, масштабирование, запуск и остановка сервисов ClickHouse Cloud, а также выполнение SQL-запросов к ним через API запросов.
  • Managed Postgres (бета): создание сервисов Postgres, реплик для чтения и восстановление на определённый момент времени, а также изменение их конфигурации.
  • ClickPipes: приём данных из объектного хранилища, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB и BigQuery.
  • ClickStack: управление источниками, панелями мониторинга, оповещениями, вебхуками, сохранёнными поисками и ролями в сервисе Управляемый ClickStack.
  • Пользовательские функции: локальное тестирование исполняемых UDF и их последующее развертывание в сервисе ClickHouse Cloud.
  • Резервные копии: просмотр списка резервных копий, изменение расписания резервного копирования и восстановление резервной копии в новый сервис.
  • Доступ к организации: организации, участники, приглашения, ключи API и журнал действий.
Чтобы узнать флаги любой команды и необходимые для неё разрешения ключа API, выполните clickhousectl cloud <command> --help.

Установка

Скрипт устанавливает ~/.local/bin/clickhousectl и псевдоним chctl. Убедитесь, что каталог ~/.local/bin добавлен в PATH. Об установке через npm, pip, uv и другими способами см. раздел Установка.

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

Вход через OAuth в браузере даёт доступ только для чтения. Чтобы создавать или изменять ресурсы, нужен ключ API с ролью, которая разрешает соответствующие изменения.
При входе проверяются учётные данные и выводится текущая идентичность. Проверить её можно в любой момент командой clickhousectl cloud auth whoami. Если вы состоите в нескольких организациях, добавляйте к командам Cloud параметр --org-id <org-id> (или --org-name <name>). В CI вместо входа задайте переменные CLICKHOUSE_CLOUD_API_KEY и CLICKHOUSE_CLOUD_API_SECRET. Порядок приоритета учётных данных и выход из системы описаны в разделе Аутентификация.

Примеры

Создание сервиса и выполнение запросов к нему

Команда создания завершается до того, как сервис будет запущен. Периодически выполняйте clickhousectl cloud service get "$CH_ID", пока state не примет значение running. При первом запросе с ключом API clickhousectl добавляет ваш ключ API к конечной точке API запросов сервиса и при необходимости создаёт эту конечную точку; новый ключ при этом не создаётся. Чтобы вместо этого команда завершалась с ошибкой, передайте --no-auto-enable. При использовании OAuth команда service query выполняет операторы SELECT только в режиме только для чтения. Тайм-аут API запросов составляет около 30 секунд, поэтому для длительных запросов и массовых загрузок используйте clickhouse client.

Создание управляемого сервиса Postgres

Пароль и строку подключения возвращает только команда create, поэтому обязательно сохраните их. Если не указать --ip-allow, порты 5432 и 6432 будут открыты для всех адресов. Дождитесь, пока поле state примет значение running, а затем подключитесь через psql, используя CA‑сертификат.

Просмотр ClickPipes, ClickStack и резервных копий

Эти команды чтения поддерживают аутентификацию через OAuth. Для создания ClickPipe или изменения ресурса ClickStack нужен ключ API — см. руководства в репозитории ниже.

Развертывание пользовательской функции

Сначала протестируйте функцию на локальном сервере с помощью команды clickhousectl local udf deploy my_udf.

Вывод в формате JSON и агенты для программирования

Команды Cloud поддерживают параметр --json, а CLI автоматически переключается на JSON, если обнаруживает агента для программирования. В этом случае cloud service query по умолчанию использует формат JSONEachRow, поэтому скрипты, которые разбирают его вывод, должны явно указывать --format, например --format TabSeparated. См. разделы Вывод в формате JSON и Коды выхода. Чтобы установить ClickHouse agent skills, выполните clickhousectl skills.

Дополнительные материалы