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 и журнал действий.
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 и резервных копий
Развертывание пользовательской функции
clickhousectl local udf deploy my_udf.
Вывод в формате JSON и агенты для программирования
Команды Cloud поддерживают параметр--json, а CLI автоматически переключается на JSON, если обнаруживает агента для программирования. В этом случае cloud service query по умолчанию использует формат JSONEachRow, поэтому скрипты, которые разбирают его вывод, должны явно указывать --format, например --format TabSeparated. См. разделы Вывод в формате JSON и Коды выхода. Чтобы установить ClickHouse agent skills, выполните clickhousectl skills.
Дополнительные материалы
- Справочник по clickhousectl: все группы команд, локальная разработка, навыки, самообновление и телеметрия.
- Руководства в репозитории:
- Справочные материалы в репозитории: аутентификация и доступ, SQL и API запросов, конфигурация ClickPipe, а также автоматизация и контракты вывода.