> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # ClickHouse CLI > Используйте ClickHouse CLI для управления сервисами ClickHouse Cloud и локальными экземплярами ClickHouse ClickHouse CLI (`clickhousectl`) — это универсальный инструмент командной строки для управления ресурсами ClickHouse Cloud и локальной разработки на базе ClickHouse. Он также позволяет управлять сервисами [ClickHouse Cloud Postgres](/ru/products/managed-postgres/overview) и [ClickPipes](/ru/integrations/clickpipes). Эта страница представляет собой справочник по набору команд `clickhousectl` 0.4.2. Выполните `clickhousectl --version`, чтобы узнать установленную версию, и `clickhousectl --help` для любой команды, чтобы получить полный список флагов.

Установка

```bash theme={null} curl https://clickhouse.com/cli | sh ``` Для удобства также автоматически создаётся алиас `chctl`. Чтобы обновить существующую установку до последней версии: ```bash theme={null} clickhousectl update # self-update clickhousectl update --check # check for updates without installing ```

Управление Cloud

Войдите в ClickHouse Cloud и управляйте своими сервисами прямо из командной строки.

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

```bash theme={null} # Log in with an API key (read/write access) clickhousectl cloud auth login --api-key --api-secret # Log in with the OAuth device flow (interactive; read-only access) clickhousectl cloud auth login # Show which credential source is active clickhousectl cloud auth status # Log out and clear saved credentials clickhousectl cloud auth logout # Create a new ClickHouse Cloud account clickhousectl cloud auth signup ``` Ключи API сохраняются в `.clickhouse/credentials.json` (локально в проекте, файл игнорируется git). Также можно использовать переменные окружения: ```bash theme={null} export CLICKHOUSE_CLOUD_API_KEY=your-key export CLICKHOUSE_CLOUD_API_SECRET=your-secret ``` Старшинство учётных данных, от высшего к низшему: флаги `--api-key`/`--api-secret`, учётные данные проекта в `.clickhouse/credentials.json`, переменные окружения (сначала shell, затем `.env`), токены OAuth, полученные через `cloud auth login`. Токены OAuth работают только для чтения; команды записи (create, delete, start, stop, update, scale) требуют аутентификации по ключу API.

Сервисы

```bash theme={null} # List services clickhousectl cloud service list # Create a service clickhousectl cloud service create --name my-service \ --provider aws \ --region us-east-1 # Get service details clickhousectl cloud service get # Update service settings (name, IP allow list, tags, endpoints, ...) clickhousectl cloud service update --add-ip-allow 0.0.0.0/0 # Scale a service clickhousectl cloud service scale \ --min-replica-memory-gb 24 \ --max-replica-memory-gb 48 \ --num-replicas 3 # Start/stop a service clickhousectl cloud service start clickhousectl cloud service stop # Reset the default user password clickhousectl cloud service reset-password # Delete a service clickhousectl cloud service delete ```

Выполнение запросов

Выполняйте SQL-запросы к сервису ClickHouse Cloud по HTTP через Query API — локальный бинарный файл `clickhouse` и пароль сервиса при этом не нужны. Необходимо указать ровно один из параметров `--id` или `--name`: ```bash theme={null} # Query by service ID or by name clickhousectl cloud service query --id -q 'SELECT 1' clickhousectl cloud service query --name my-service -q 'SELECT version()' # Run a query from a SQL file (use "-" for stdin), choosing an output format. # The file must hold a single statement clickhousectl cloud service query --id \ --queries-file report.sql --format JSONEachRow # With neither --query nor --queries-file, SQL is read from stdin echo 'SELECT 1' | clickhousectl cloud service query --id # Replace a stored Query API key that the endpoint rejects clickhousectl cloud service repair-query-key ``` При аутентификации по ключу API запросы выполняются с правами на чтение и запись. Аутентифицированный ключ используется напрямую, если эндпоинт запроса сервиса уже разрешает его; в противном случае первый запрос создаёт эндпоинт запроса и отдельный ключ на чтение/запись для этого сервиса и сохраняет его в `.clickhouse/credentials.json`. Передайте `--no-auto-enable`, чтобы команда завершалась с ошибкой вместо создания ресурсов. При использовании OAuth SQL выполняется от имени вашего облачного пользователя с доступом только для чтения (только `SELECT`), и ничего не создаётся. Что важно знать: * `service query` выполняет один оператор на запрос. SQL с несколькими операторами отклоняется Query API независимо от способа передачи — `--query`, `--queries-file` или stdin — с сообщением `Error: SQL error 62: Syntax error (Multi-statements are not allowed)`. Завершающая `;` у одиночного оператора допустима. Для скриптов выполните `clickhousectl local use latest` и подключайтесь к сервису через `clickhouse client`. * `--query` и `--queries-file` взаимоисключающи (код выхода 2). Stdin читается только в том случае, если не указан ни один из них. `--query` никогда не читает stdin, поэтому перенаправление или передача данных по конвейеру вместе с ним приводит к явной ошибке, а не молча превращается в no-op: `Error: --query cannot be combined with SQL or data on stdin.` Вместо этого отправляйте `INSERT` вместе с его данными единым потоком — `printf 'INSERT INTO t FORMAT CSV\n' | cat - data.csv | clickhousectl cloud service query --id ` — либо считывайте оператор целиком из stdin с помощью `--queries-file -`. * Формат вывода по умолчанию — `PrettyCompact` в терминале и `TabSeparated` при передаче по конвейеру. `--json` выбирает `JSONEachRow` и не может использоваться вместе с `--format` (код выхода 2). * Сохранённый ключ Query API, который эндпоинт отклоняет с HTTP 401/403, никогда не заменяется автоматически; CLI читает управляющую запись ключа лишь для того, чтобы сообщить причину. Замените именно этот credential командой `clickhousectl cloud service repair-query-key ` — она также удаляет заменённый ключ. На работающем сервисе она завершается с кодом 0 только после того, как пробный запрос с новым ключом выполнится успешно; результат отражается в поле `verification` вывода `--json`. Если по истечении окна готовности Query API по-прежнему отклоняет ключ, команда завершается с кодом 1, но исправление остаётся в силе: не запускайте её повторно, а выполните `cloud service query`. * Query API завершается по тайм-ауту примерно через 30 секунд; оператор продолжает выполняться на сервисе, но результат теряется. Для более длительных операций выполните `clickhousectl local use latest`, чтобы поместить стандартный бинарный файл `clickhouse` в `PATH`, и подключитесь с помощью `clickhouse client --host --secure --port 9440 --user default --password `.

Конечные точки сервиса и конфигурация

```bash theme={null} # Query endpoints (used by the Query API) clickhousectl cloud service query-endpoint get clickhousectl cloud service query-endpoint create --role sql_console_admin clickhousectl cloud service query-endpoint delete # Private endpoints. --endpoint-id takes an AWS VPC endpoint ID, a GCP PSC # connection ID, or an Azure private endpoint Resource ID / resourceGuid clickhousectl cloud service private-endpoint get-config clickhousectl cloud service private-endpoint create --endpoint-id # Backup configuration clickhousectl cloud service backup-config get clickhousectl cloud service backup-config update --backup-period-hours 24 clickhousectl cloud service backup-config update \ --backup-start-time 02:00 --backup-period-hours 24 clickhousectl cloud service backup-config update --clear-backup-start-time # Prometheus metrics for a service (always raw Prometheus exposition text) clickhousectl cloud service prometheus ``` `--backup-start-time` должен указывать ровно начало часа (`HH:00`); это проверяется в CLI до любого вызова API. Кроме того, период резервного копирования должен составлять `24` или `48` часов: передайте `--backup-period-hours 24` или `--backup-period-hours 48` в той же команде либо заранее сохраните одно из этих двух значений. При любом другом сохранённом периоде CLI откажет ещё до обращения к API, выдав `Error: the stored backup period is 12 hours, but --backup-start-time requires 24 or 48.` `--clear-backup-start-time` удаляет сохранённое время начала и снимает это ограничение. Используйте его вместе с `--backup-period-hours`, чтобы одним вызовом сбросить время начала и задать любой период. Этот параметр конфликтует с `--backup-start-time`.

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

```bash theme={null} clickhousectl cloud backup list clickhousectl cloud backup get ``` Чтобы восстановить резервную копию, создайте на её основе новый сервис: `clickhousectl cloud service create --name restored-service --backup-id `.

ClickPipes

Управление [ClickPipes](/ru/integrations/clickpipes) для ингестии данных в сервис ClickHouse Cloud. Большинство команд принимают ID сервиса первым аргументом. ```bash theme={null} # List pipes and get details clickhousectl cloud clickpipe list clickhousectl cloud clickpipe get # Create a pipe. Sources: object-storage, kafka, kinesis, pubsub, # postgres, mysql, mongodb, bigquery clickhousectl cloud clickpipe create object-storage \ --name my-pipe \ --source-url 'https://bucket.s3.us-east-1.amazonaws.com/data/*.json' \ --format JSONEachRow \ --database default \ --table events # A Postgres pipe needs at least one --table-mapping or --table-mapping-json clickhousectl cloud clickpipe create postgres \ --name my-cdc-pipe \ --host pg.example.com \ --pg-database appdb \ --username replicator \ --password \ --table-mapping public.orders:orders \ --sync-interval-seconds 30 \ --ca-certificate ./source-ca.pem # Lifecycle clickhousectl cloud clickpipe start clickhousectl cloud clickpipe stop clickhousectl cloud clickpipe resync # CDC pipes only clickhousectl cloud clickpipe delete # Scaling and settings. scale requires at least one of # --replicas, --cpu-millicores, or --memory-gb clickhousectl cloud clickpipe scale --replicas 2 clickhousectl cloud clickpipe settings get clickhousectl cloud clickpipe settings update # Discover a source schema without creating a pipe (beta) clickhousectl cloud clickpipe schema-discover kafka [options] clickhousectl cloud clickpipe schema-discover kinesis [options] clickhousectl cloud clickpipe schema-discover object-storage [options] clickhousectl cloud clickpipe schema-discover pubsub [options] # Reverse private endpoints: AWS PrivateLink, Amazon MSK multi-VPC, # Google Private Service Connect clickhousectl cloud clickpipe reverse-private-endpoint list clickhousectl cloud clickpipe reverse-private-endpoint get clickhousectl cloud clickpipe reverse-private-endpoint create \ --type VPC_ENDPOINT_SERVICE \ --description 'kafka source' \ --vpc-endpoint-service-name clickhousectl cloud clickpipe reverse-private-endpoint update \ --custom-private-dns-mapping pg.internal.example.com clickhousectl cloud clickpipe reverse-private-endpoint delete ``` Что нужно знать: * `clickpipe create postgres` требует указания одного из флагов: `--table-mapping ` (можно указывать несколько раз, по одной таблице на флаг) или `--table-mapping-json `; их можно сочетать. Форма JSON принимает объект сопоставления таблиц из API дословно и является единственным способом задать `excludedColumns`, `sortingKeys`, `partitionByExpr`, `partitionKey` и `tableEngine`. Обратите внимание: `partitionKey` разбивает начальный снимок на партиции для параллелизма и не имеет отношения к `PARTITION BY` целевой таблицы, за который отвечает `partitionByExpr`. Флаг `--iam-role` обязателен при `--auth IAM_ROLE` и отклоняется при базовой аутентификации, а `--replication-slot-name` допустим только вместе с `--replication-mode cdc_only`. * Настройки Postgres CDC применяются при создании пайпа: `--sync-interval-seconds`, `--pull-batch-size`, `--initial-load-parallelism`, `--snapshot-rows-per-partition`, `--snapshot-parallel-tables`, `--allow-nullable-columns`, `--enable-failover-slots` и `--delete-on-merge`. Впоследствии можно изменить только sync interval и pull batch size; настройки снимка и начальной загрузки изменению не подлежат. * Флаг `--role ` в любой подкоманде `clickpipe create` можно указывать несколько раз; он определяет роль ClickHouse, выдаваемую пользователю пункта назначения пайпа. Эта роль заменяет ту, которую пользователь получил бы по умолчанию: без `--role` пользователю назначаются `clickpipes_system` и `default_role`, а с `--role my_role` — `clickpipes_system` и `my_role`. Роль должна позволять создавать таблицы в целевой базе данных — с ролью только для чтения создание завершится ошибкой `Not enough privileges`. Зарезервированные в API имена `clickpipes` и `clickpipes_system` отклоняются. * Для источников Postgres TLS и проверка сертификата включены по умолчанию. Если цепочка сертификатов источника публично доверенная, файл CA не нужен; для частного или самоподписанного CA источника передайте его PEM-бандл через `--ca-certificate `. Для источника ClickHouse Cloud Postgres получите этот бандл командой `clickhousectl cloud postgres certs get`. При проверке имени хоста используется значение `--host`, если оно не переопределено флагом `--tls-host `. * Для пайпов Kafka и Kinesis значение `--auth` выводится из флагов учётных данных, если оно не указано; если флаги учётных данных не заданы, аутентификация не выполняется. * Команда `clickpipe settings` охватывает настройки ингестии только для потоковых пайпов (Kafka, Kinesis) и пайпов объектного хранилища, причём настройки, специфичные для Kafka, для остальных пайпов не выводятся. У пайпов CDC для баз данных (Postgres, MySQL, MongoDB, BigQuery) настроек ингестии нет: `settings get` для такого пайпа завершается с кодом 1 и отсылает к `clickhousectl cloud clickpipe get ` — именно там показываются их sync interval и pull batch size. * Пайп может использовать только обратную частную конечную точку, достигшую статуса `Ready`; конечная точка AWS PrivateLink остаётся в состоянии `PendingAcceptance`, пока запрос на подключение не будет принят в аккаунте, которому принадлежит источник. Пайпы Kafka ссылаются на конечную точку по ID через `--reverse-private-endpoint-id` (можно указывать несколько раз); пайпы CDC для Postgres и MySQL передают одно из значений `dnsNames` конечной точки в `--host`. * Пайпы Google Cloud Pub/Sub доступны в режиме ограниченного предварительного доступа: прежде чем создавать такой пайп, обратитесь в службу поддержки, чтобы включить эту возможность для вашей организации. Флаг `--service-account-file` принимает путь к JSON-ключу сервисного аккаунта GCP либо `-` для чтения ключа из stdin; сам ключ передать в строке нельзя, поэтому он не попадает в списки процессов и историю командной оболочки.

Postgres services (бета)

Создание сервисов [ClickHouse Cloud Postgres](/ru/products/managed-postgres/overview) и управление ими. ```bash theme={null} # List Postgres services, optionally filtering client-side. # Filter keys: state, region, name, provider, isPrimary clickhousectl cloud postgres list clickhousectl cloud postgres list --filter state=running --filter isPrimary=true # Create a Postgres service clickhousectl cloud postgres create \ --name my-pg \ --region us-east-1 \ --size m7i.2xlarge \ --pg-version 18 # Get service details clickhousectl cloud postgres get # Update a service clickhousectl cloud postgres update --size m7i.4xlarge --add-tag env=prod # Reset the password (exactly one of --password or --generate) clickhousectl cloud postgres reset-password --generate # Runtime configuration (postgresql.conf + PgBouncer) and CA certificates. # config patch takes exactly one of --set (repeatable) or --file clickhousectl cloud postgres config get clickhousectl cloud postgres config patch --set max_connections=500 clickhousectl cloud postgres config replace --file config.json clickhousectl cloud postgres certs get # Read replicas, failover, and point-in-time restore clickhousectl cloud postgres read-replica create --name replica-1 clickhousectl cloud postgres promote --wait clickhousectl cloud postgres switchover --wait clickhousectl cloud postgres restore --name restored --restore-target 2026-04-16T12:00:00Z # Restart a service clickhousectl cloud postgres restart # Delete a service clickhousectl cloud postgres delete ``` Что следует знать: * Значение `--provider` по умолчанию — `aws`; также принимается `gcp` с размерами машин GCP, такими как `c4-standard-4`. Значение `--size` проверяется на стороне Cloud API, а не CLI, поэтому неподдерживаемый размер будет отклонён только сервером. * Изменения ролей применяются не мгновенно, и API подтверждает `promote` и `switchover` ещё до их фактического применения, поэтому код выхода 0 сам по себе не гарантирует, что роль изменилась. Обе команды принимают флаг `--wait`, который опрашивает состояние, пока целевой сервис не сообщит о новой роли; параметр `--wait-timeout ` (по умолчанию 300) ограничивает время опроса. Прежний основной сервис может ещё несколько минут сообщать `isPrimary=true`, поэтому с помощью `clickhousectl cloud postgres list --filter isPrimary=true` убедитесь, что основным является ровно один сервис. * `postgres delete` работает в любом состоянии, включая `running`, поэтому предварительно останавливать сервис не требуется.

Организации

```bash theme={null} clickhousectl cloud org list clickhousectl cloud org get clickhousectl cloud org update --name new-name clickhousectl cloud org prometheus clickhousectl cloud org usage --from-date 2026-08-01 --to-date 2026-08-31 ```

Ключи API

```bash theme={null} clickhousectl cloud key list clickhousectl cloud key get clickhousectl cloud key create --name ci-key --role-id clickhousectl cloud key update clickhousectl cloud key delete ```

Участники и приглашения

```bash theme={null} clickhousectl cloud member list clickhousectl cloud member get clickhousectl cloud member update --role-id clickhousectl cloud member remove clickhousectl cloud invitation list clickhousectl cloud invitation create --email dev@example.com --role-id clickhousectl cloud invitation get clickhousectl cloud invitation delete ```

Журнал активности

```bash theme={null} clickhousectl cloud activity list --from-date 2026-08-01 --to-date 2026-08-31 clickhousectl cloud activity get ```

Вывод JSON

Используйте флаг `--json`, чтобы получать ответы в формате JSON при выполнении любой облачной команды: ```bash theme={null} clickhousectl cloud service list --json ``` Команды `org prometheus` и `service prometheus` — исключение: они всегда выводят необработанный текст экспозиции Prometheus и молча игнорируют `--json`.

Локальная разработка

CLI также управляет локальными установками ClickHouse, локальными серверами и локальными инстансами Postgres на базе Docker. Как начать работу с локальной разработкой, см. на странице [clickhousectl (CLI)](/ru/get-started/setup/self-managed/clickhousectl). ```bash theme={null} # Manage installed ClickHouse versions. install also accepts stable, lts, # a partial version like 25.12, an exact version, or a Postgres image # selector like postgres@18 clickhousectl local install latest clickhousectl local list clickhousectl local use clickhousectl local which clickhousectl local remove # Scaffold a project (.clickhouse/ plus clickhouse/ and postgres/ directories) clickhousectl local init # Manage local server instances (data persists in .clickhouse/servers/) clickhousectl local server start [name] clickhousectl local server list # --global lists servers across projects clickhousectl local server stop [name] clickhousectl local server stop-all clickhousectl local server remove [name] clickhousectl local server configs # named overlays for `server start --config` clickhousectl local server dotenv # Connect to a running server with clickhouse-client clickhousectl local client -q 'SELECT 1;' clickhousectl local client --host db.example.com --port 9000 --version 25.12 # Local Postgres instances (requires Docker) clickhousectl local postgres start --name clickhousectl local postgres client clickhousectl local postgres stop [name] clickhousectl local postgres stop-all clickhousectl local postgres remove [name] clickhousectl local postgres dotenv ``` Что нужно знать: * Команды `local` работают в пределах проекта: они используют каталог `.clickhouse` в текущем рабочем каталоге и никогда не ищут его в родительских каталогах. Перед их запуском перейдите в корень проекта. * `clickhousectl local use` также создаёт символическую ссылку `~/.local/bin/clickhouse`, благодаря чему стандартные подкоманды, такие как `clickhouse client`, `clickhouse benchmark` и `clickhouse format`, становятся доступны напрямую. Передайте `--no-global`, чтобы пропустить создание символической ссылки. * `local remove` принимает точную установленную версию. Команда откажется удалять версию, которую использует запущенный сервер в каком-либо проекте, а также версию, назначенную текущей по умолчанию; `--force` останавливает такие серверы и сбрасывает значение по умолчанию вместе с глобальной символической ссылкой. * Без указания имени `local server stop` останавливает `default`, если он существует, иначе — единственный известный сервер; при наличии нескольких серверов, отличных от `default`, команда запросит имя. `local server remove` без имени выбирает только существующий `default` — пользовательский сервер она никогда не угадывает. * `local client` принимает `-v`/`--version` для выбора установленной версии клиента в режиме прямого указания хоста и порта, допускает повторение `-q` для нескольких запросов и принимает несколько путей в `--queries-file`. Совмещение `--query` и `--queries-file` считается ошибкой использования. * `local postgres start` блокирует выполнение до тех пор, пока PostgreSQL не начнёт принимать подключения, но не дольше числа секунд, заданного в `--wait-timeout` (по умолчанию 60, максимум 600). Если `--port` не указан, используется порт 5432 при условии, что он свободен, иначе порт выбирается автоматически; явно запрошенный порт, который уже занят, отклоняется.

Другие команды

```bash theme={null} # Install the ClickHouse agent skills into supported coding agents clickhousectl skills --agent claude # Manage anonymous usage telemetry: command name, flag and argument names # (never their values). Opt out with DO_NOT_TRACK=1 clickhousectl telemetry status clickhousectl telemetry disable clickhousectl telemetry enable ```

Требования

* macOS (aarch64, x86\_64) или Linux (aarch64, x86\_64) * Для команд Cloud нужен [ключ API ClickHouse Cloud](/ru/products/cloud/features/admin-features/api/openapi) для доступа на запись; вход через OAuth даёт доступ только для чтения * `clickhousectl local postgres` требует Docker