Что нового в clickhousectl v0.5.0

clickhousectl (chctl) — это единый интерфейс командной строки (CLI) для ClickHouse и Postgres, работающий как на вашем ноутбуке, так и в ClickHouse Cloud. Локально он устанавливает и переключает версии ClickHouse, запускает серверы ClickHouse в рамках проектов и Postgres на базе Docker, а также подключает клиенты. В облаке он охватывает весь жизненный цикл ClickHouse, ClickHouse Managed Postgres, ClickPipes, ClickStack, резервных копий, ключей и участников.

Версия v0.4.0 вышла из стадии бета-тестирования и получила поддержку горизонтального автомасштабирования и обнаружения схем для ClickPipe. Основные новшества в v0.5.0:

• Пользовательские функции (UDF) от начала до конца: создание заготовки, локальное тестирование, а затем развертывание в Cloud одной командой.
• ClickHouse Managed Postgres: метрики, логи сервера, паттерны медленных запросов, SQL-запросы только для чтения по протоколу HTTP и правила разрешения IP-адресов.
• Более согласованный и удобный для автоматизации CLI: единообразные селекторы, ввод через --file, выбор глобальной организации, ошибки в формате JSON везде. Обратите внимание, что некоторые из этих изменений нарушают обратную совместимость; см. раздел об изменениях, ломающих совместимость.
• Сохраненные запросы и конечные точки Query API: сохраненные запросы получили статус GA (общедоступны) и могут быть представлены в виде конечных точек HTTP.
• ClickPipes для CDC BigQuery: непрерывная репликация из BigQuery с заданным интервалом или по расписанию cron.
• ClickStack теперь доступен в CLI: дашборды, оповещения, вебхуки, сохраненные поисковые запросы, источники и роли.
• Разрешения в справке: для каждой команды Cloud указаны необходимые ей разрешения API-ключей.
• Гораздо более широкое покрытие Cloud: настройки сервисов, расписания масштабирования, окна обновлений, снимки, бакеты резервных копий, инфраструктура BYOC, роли организаций, квоты, кредиты.

Если инструмент уже установлен, обновите его на месте:

Если нет, установите его одним из удобных способов ниже:

Исполняемые UDF теперь имеют полноценный рабочий процесс. local udf init создает каркас директории UDF (определение udf.json плюс скрипт на Python или нативные бинарные файлы amd64/arm64). local udf deploy устанавливает ее на локальный сервер, позволяя тестировать с помощью обычного SQL. Когда все заработает, cloud udf deploy упаковывает директорию, создает UDF (или новую версию), привязывает ее к вашему сервису и активирует его — и все это за один шаг.

Для более точного контроля также доступны низкоуровневые команды Cloud (в бета-версии): cloud udf create, version create, attach / detach (с флагом --wake) и attachment list.

См. руководство по пользовательским функциям.

Теперь вы можете исследовать сервисы ClickHouse Managed Postgres прямо из терминала. postgres metrics возвращает метрики сервиса в виде компактных рядов, postgres logs отображает логи сервера в виде таблицы (с фильтрацией по уровню критичности или тексту сообщения), а postgres slow-queries выводит нормализованные паттерны запросов, отсортированные по общей/средней/p95/p99 длительности, использованию CPU, количеству строк, журналам упреждающей записи (WAL) и другим параметрам. Команда get затем отображает недавние выполнения выбранного паттерна. postgres prometheus предоставляет исходную конечную точку Prometheus для вашей существующей системы сбора метрик. Агенты могут использовать те же команды для проведения анализа первопричин медленной работы Postgres.

cloud postgres query выполняет SQL-запросы только для чтения по HTTP, используя ваш вход через OAuth, без необходимости использования psql, настройки сетевых путей или пароля. Также появились новинки: postgres backup list (с колонкой Status), отображение провайдера в postgres list и проверка вводимых параметров конфигурации. postgres get показывает самое раннее время восстановления. Запись конфигурации (--set, --pg-config-file) теперь поддерживает еще 29 параметров Postgres, включая пороги autovacuum, checkpoint_timeout, wal_buffers, io_method и default_toast_compression. Значения перечислений проверяются до отправки каких-либо данных.

Вы также можете настроить сетевой доступ из CLI. postgres create принимает повторяющиеся правила --ip-allow <IP_OR_CIDR>:<PORTS>[=<DESCRIPTION>] или флаг --block-public-access, а postgres update добавляет и удаляет правила с помощью --add-ip-allow и --remove-ip-allow <RULE_ID> (только для IPv4). postgres restore копирует правила IP источника на восстановленный сервис, так как в противном случае API восстановления открыл бы доступ для всех адресов.

См. руководство по ClickHouse Managed Postgres.

В версии 0.5.0 стандартизирован способ передачи аргументов в команды, так что, освоив одну команду, вы будете интуитивно понимать структуру остальных. Это важно для людей и еще важнее для агентов, которые переносят логику с одной команды на другую. Новые правила таковы:

• Завершите путь подкоманды, а затем укажите существующие ресурсы по их позиционному идентификатору.
• Альтернативный вариант — выбрать ресурс по точному имени с помощью --name.
• Выберите организацию с помощью --org-id или --org-name, указав это в любом месте после слова cloud.
• Флаг --new-name переименовывает ресурс.

Большинство изменений сохраняют старые варианты написания в качестве скрытых псевдонимов, однако некоторые нарушают работу существующих скриптов.

Старые формы завершаются ошибкой использования (код выхода 2) и не интерпретируются молча заново.

cloud saved-query создает, обновляет и удаляет сохраненные запросы с параметрами по умолчанию. Эти операции теперь общедоступны (GA), поэтому пометка Beta удалена. С помощью cloud query-api-endpoint вы можете управлять конечными точками Query API и предоставлять сохраненные запросы в качестве HTTP-эндпоинтов, например, для работы дашбордов или приложений напрямую из ClickHouse. Исправлено: запросы query-api-endpoint list и поиск по --name завершались ошибкой десериализации, как только в организации появлялся хотя бы один эндпоинт.

См. справочник по Query API.

В этом релизе возможности ClickPipes значительно расширились. Главным новообразованием стала команда clickpipe update — полноценная команда обновления, которая безопасно применяет настройки к работающим пайпам, включая сценарий CDC: пауза → обновление → возобновление. CDC-пайпы получили расширенные сопоставления таблиц (включая выбор движка таблицы; ReplacingMergeTree теперь используется по умолчанию для Postgres), выбор базы данных назначения и масштабирование CDC.

BigQuery CDC. Команда clickpipe create bigquery раньше поддерживала только снимки. Теперь она принимает --replication-mode cdc или cdc_only вместе с --replication-method query_based (для каждой таблицы указывается queryCdcWatermarkColumn) или events_based (для каждой таблицы указывается eventsFunction, вставки или изменения). Синхронизация выполняется по расписанию --sync-interval-seconds или по cron-расписанию через --sync-cron (в UTC, если не указан префикс CRON_TZ=<zone>). Настройки тюнинга охватывают параллелизм выгрузки, задержку видимости и размер окна выгрузки. Некорректные комбинации вызывают локальную ошибку до того, как будет прочитан ключ сервисного аккаунта.

Полный пример с параметрами --service-account-file и --staging-path приведен в справочнике по конфигурации ClickPipe в разделе «Настройка CDC BigQuery».

А также: сопоставления таблиц MongoDB теперь поддерживают structuredIngestion (типизированные колонки, исключения, ключи сортировки и секционирование вместо единственной колонки JSON), а пайпы MySQL поддерживают --mysql-type cloudsqlmysql для Cloud SQL.

Мелкие дополнения: элементы управления TLS для Postgres, удостоверение рабочей нагрузки GCP, схемы Protobuf для Kinesis (с автоопределением аутентификации по ключам доступа), реестр схем Kafka AWS Glue, параллелизм начальной загрузки MongoDB, настройка снимков BigQuery, параметры настройки источников, определения потоковых таблиц, запуск поддерживаемых пайпов в приостановленном состоянии и цели DNS. Проверка теперь выполняется до отправки любых данных: диапазоны портов, диапазоны масштабирования, размеры вставок и обязательные колонки объектного хранилища проверяются заранее.

См. руководство по ClickPipes и справочник по конфигурации ClickPipe.

Новая группа команд cloud clickstack для управления ресурсами ClickStack (мониторинга и наблюдаемости) в сервисе Cloud: источниками данных, ролями, дашбордами, оповещениями, вебхуками и сохраненными поисковыми запросами. Вы можете хранить дашборды и оповещения в формате JSON в своем репозитории и применять их из CI, или позволить агенту создать дашборд для вас. dashboard validate проверяет определение перед его созданием, а webhook validate делает то же самое для вебхуков.

CLI поддерживает последнюю версию контракта API ClickStack:

• Дашборды поддерживают все четыре типа фильтров (выражение запроса, статический список, метка Prometheus, фильтр источника), плитки со стековой линией (stacked-line), тепловые карты рядов (series heatmaps) и lineInterpolation.
• Оповещения могут использовать встроенный параметр chartConfig (source: inline) вместо плитки или сохраненного поискового запроса. Параметры channel/channels теперь необязательны, а новые поля displayName и tags передаются без изменений. Поле name теперь является шаблоном заголовка Handlebars. alert list отображает displayName, а --name сопоставляется с любым из этих полей.
• Права ролей проверяются на соответствие их интеграции (ClickHouse или MongoDB), поэтому опечатка вызовет ошибку локально, а не будет проигнорирована.

См. руководство по ClickStack.

Теперь из CLI можно управлять гораздо большим количеством настроек сервиса Cloud:

• service settings: чтение схемы настроек ClickHouse, установка и получение настроек с типизированными значениями.
• service scaling-schedule: расписания масштабирования на основе времени.
• service upgrade-window: управление временем проведения обновлений.
• service profile list: просмотр доступных профилей сервиса для региона.
• service wake: принудительный вывод простаивающего сервиса из спящего режима.
• service snapshot (Бета): просмотр списка снимков и управление конфигурацией снимков.
• service replica-aware-routing.
• Описания списков разрешенных IP-адресов (IP allowlist).

См. руководство по сервису Cloud.

backup bucket управляет собственным бакетом резервных копий сервиса (при использовании собственного хранилища), а service backup-config управляет конфигурацией резервного копирования, включая шифрование. Метки времени резервных копий теперь приводятся к стандарту UTC. Бакеты резервных копий AWS принимают iamRoleExternalId в теле запроса --file (обязательно при создании; при обновлении опустите параметр для сохранения текущего значения, задайте новое для его замены или установите в null для очистки).

Новые команды на уровне организации: org role (пользовательские роли), org quota, org balance (кредитные балансы), org prometheus discovery и org notifications (Бета). Команда осуществляет постраничный вывод уведомлений организации и фильтрует их по степени важности, типу, ресурсу и диапазону дат. org byoc управляет инфраструктурой BYOC от начала до конца: validate проверяет готовность вашего облачного аккаунта, create (включая флаги для собственной сети VPC) подготавливает ее, progress отслеживает процесс подготовки, а get, update и delete покрывают остальные операции. Также поддерживаются конфигурация частных конечных точек (Private endpoint) и теги.

cloud auth whoami показывает учетные данные, стоящие за вашими активными учетными данными, а auth login и auth status теперь проверяют и отображают их. При первом запуске service query CLI теперь привязывает ваш собственный ключ API и больше не создает отдельный ключ запроса, поэтому используются роли, которые у вас уже есть. Пустые учетные данные с ключом API отклоняются, а --debug объясняет, какой источник учетных данных был выбран и почему.

Справка каждой команды Cloud теперь перечисливает разрешения ключа API, необходимые для выполняемых ею под капотом вызовов API. Список генерируется из определений API, поэтому он всегда актуален и соответствует API. Агент может прочитать его перед запуском команды и узнать, достаточно ли его ключа, вместо того чтобы выяснять это по неудачному вызову. Это также закладывает основу для будущей функции, которая позволит агентам запрашивать повышение прав, когда им необходимо запустить команду, недоступную для их ключа.

• Ошибки в формате JSON повсюду: в режиме --json (или при обнаружении агента) любой сбой среды выполнения Cloud, включая ошибки авторизации и отмены, выводится в виде структурированной ошибки JSON. Коды выхода стабильны: 1 — ошибка, 2 — использование, 3 — отменено, 4 — требуется авторизация.
• Структурированный вывод для команд управления с документированными контрактами вывода JSON (см. справочник по автоматизации).
• Пагинация --all для ключей API и пагинация по селекторам для ClickStack.
• Закрытые каналы stdout (| head) обрабатываются без лишнего вывода.
• Блоки контекста агента в справке были стандартизированы и проверены по всему дереву команд.
• Обнаружение агента теперь сначала проверяет переменную AI_AGENT в agents.md. Нераспознанное значение в устаревшей переменной AGENT больше не включает вывод JSON (известное имя агента или AGENT=1 по-прежнему работают).
• Вывод постраничных списков стал единообразным: списки UDF возвращают массив результатов верхнего уровня с полем nextCursor, имеющим ту же форму, что и cloud key list.

Локальная разработка получила ряд испавлений:

• Порты сервера сохраняются при перезагрузках конфигурации.
• SQL-файлы Postgres и стандартный ввод (stdin) передаются через Docker (работает перенаправление для psql).
• Динамический .gitignore восстанавливается командой init.
• Загрузки выполняются по условию, поэтому последние сборки используются повторно.
• Ошибки поврежденных метаданных и сбоев Docker стали более понятными.
• Анонимные тома Postgres удаляются вместе со своими контейнерами.

local udf (упомянутый выше) — главная новая локальная функция.

Спасибо Заку Неймону, участвовавшему в разработке функционала UDF в этом релизе, и @ylw510, благодаря которому при неудачных установках стал отображаться вывод ошибок из clickhouse --version (#993).