ClickHouse CLI

Utilisez ClickHouse CLI pour gérer les services ClickHouse Cloud et les instances ClickHouse locales

ClickHouse CLI (clickhousectl) est un outil de ligne de commande unifié permettant de gérer les ressources ClickHouse Cloud ainsi que le développement local avec ClickHouse. Il permet également de gérer les services ClickHouse Cloud Postgres et ClickPipes.

Cette page constitue une référence des commandes disponibles dans clickhousectl 0.4.2. Exécutez clickhousectl --version pour vérifier la version installée, et clickhousectl <command> --help sur n’importe quelle commande pour obtenir la liste complète des flags.

​

Installation

curl https://clickhouse.com/cli | sh

Un alias chctl est également créé automatiquement pour plus de commodité.

Pour mettre à jour une installation existante vers la dernière version :

clickhousectl update           # self-update
clickhousectl update --check   # check for updates without installing

​

Gestion de Cloud

Authentifiez-vous auprès de ClickHouse Cloud et gérez vos services directement depuis la ligne de commande.

​

Authentification

# Log in with an API key (read/write access)
clickhousectl cloud auth login --api-key <key> --api-secret <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

Les clés API sont enregistrées dans .clickhouse/credentials.json (fichier local au projet, ignoré par git). Vous pouvez également utiliser des environment variables :

export CLICKHOUSE_CLOUD_API_KEY=your-key
export CLICKHOUSE_CLOUD_API_SECRET=your-secret

Préséance des credentials, de la plus élevée à la plus faible : flags --api-key/--api-secret, credentials du projet dans .clickhouse/credentials.json, variables d’environnement (shell, puis .env), tokens OAuth issus de cloud auth login.

Les tokens OAuth sont en lecture seule ; les commandes d’écriture (create, delete, start, stop, update, scale) nécessitent une authentification par clé API.

​

Services

# 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 <service-id>

# Update service settings (name, IP allow list, tags, endpoints, ...)
clickhousectl cloud service update <service-id> --add-ip-allow 0.0.0.0/0

# Scale a service
clickhousectl cloud service scale <service-id> \
  --min-replica-memory-gb 24 \
  --max-replica-memory-gb 48 \
  --num-replicas 3

# Start/stop a service
clickhousectl cloud service start <service-id>
clickhousectl cloud service stop <service-id>

# Reset the default user password
clickhousectl cloud service reset-password <service-id>

# Delete a service
clickhousectl cloud service delete <service-id>

​

Exécuter des requêtes

Exécutez du SQL sur un service Cloud via HTTP grâce à la Query API — sans binaire clickhouse local ni mot de passe de service. Un seul des paramètres --id ou --name doit être fourni, et il est obligatoire :

# Query by service ID or by name
clickhousectl cloud service query --id <service-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 <service-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 <service-id>

# Replace a stored Query API key that the endpoint rejects
clickhousectl cloud service repair-query-key <service-id>

Avec l’authentification par clé API, les requêtes s’exécutent avec un accès en lecture et en écriture. La clé authentifiée est utilisée directement lorsque le query endpoint du service l’autorise déjà ; sinon, la première requête provisionne un query endpoint ainsi qu’une clé lecture/écriture propre au service, et enregistre cette clé dans .clickhouse/credentials.json. Passez --no-auto-enable pour échouer au lieu de provisionner. Avec OAuth, le SQL s’exécute sous votre utilisateur cloud avec un accès read-only (SELECT uniquement), et rien n’est provisionné.

À savoir :

• service query exécute une seule statement par requête. Le SQL multi-statements est rejeté par la Query API, quel que soit son mode de transmission — --query, --queries-file ou stdin — avec Error: SQL error 62: Syntax error (Multi-statements are not allowed). Un ; final sur une statement unique ne pose pas de problème. Pour les scripts, exécutez clickhousectl local use latest et utilisez plutôt clickhouse client sur le service.
• --query et --queries-file sont mutuellement exclusifs (code de sortie 2). Stdin n’est lu que si aucun des deux n’est fourni. --query ne lit jamais stdin : rediriger ou envoyer des données par pipe en parallèle constitue donc une erreur bloquante plutôt qu’un no-op silencieux : Error: --query cannot be combined with SQL or data on stdin. Envoyez plutôt un INSERT et ses données sous forme d’un single stream — printf 'INSERT INTO t FORMAT CSV\n' | cat - data.csv | clickhousectl cloud service query --id <service-id> — ou lisez une statement complète depuis stdin avec --queries-file -.
• L’output format par défaut est PrettyCompact sur un terminal et TabSeparated en cas de pipe. --json sélectionne JSONEachRow et ne peut pas être combiné avec --format (code de sortie 2).
• Une clé API Query enregistrée que l’endpoint rejette avec un HTTP 401/403 n’est jamais remplacée automatiquement ; la CLI consulte l’enregistrement de management de la clé uniquement pour en indiquer la raison. Remplacez ce credential précis avec clickhousectl cloud service repair-query-key <service-id>, qui supprime également la clé remplacée. Sur un service en cours d’exécution, la commande ne se termine avec le code 0 qu’une fois qu’une query de probe avec la nouvelle clé a réussi, résultat rapporté sous verification dans la sortie --json. Si la Query API rejette toujours la clé à la fin de la readiness window, la commande se termine avec le code 1, mais la réparation reste valide : ne la relancez pas, exécutez plutôt cloud service query.
• La Query API expire après environ 30 secondes ; la statement continue de s’exécuter sur le service, mais le résultat est perdu. Au-delà de cette durée, exécutez clickhousectl local use latest afin de placer le clickhouse binary standard dans le PATH, puis connectez-vous avec clickhouse client --host <host> --secure --port 9440 --user default --password <password>.

​

Points de terminaison de service et configuration

# Query endpoints (used by the Query API)
clickhousectl cloud service query-endpoint get <service-id>
clickhousectl cloud service query-endpoint create <service-id> --role sql_console_admin
clickhousectl cloud service query-endpoint delete <service-id>

# 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 <service-id>
clickhousectl cloud service private-endpoint create <service-id> --endpoint-id <endpoint-id>

# Backup configuration
clickhousectl cloud service backup-config get <service-id>
clickhousectl cloud service backup-config update <service-id> --backup-period-hours 24
clickhousectl cloud service backup-config update <service-id> \
  --backup-start-time 02:00 --backup-period-hours 24
clickhousectl cloud service backup-config update <service-id> --clear-backup-start-time

# Prometheus metrics for a service (always raw Prometheus exposition text)
clickhousectl cloud service prometheus <service-id>

--backup-start-time doit correspondre exactement à une heure pleine (HH:00) et est validé par la CLI avant tout appel à l’API. Cette option exige également que la période de sauvegarde soit de 24 ou 48 heures : passez --backup-period-hours 24 ou --backup-period-hours 48 dans la même commande, ou assurez-vous que l’une de ces deux valeurs est déjà enregistrée. Avec toute autre période enregistrée, la CLI refuse l’opération avant d’appeler l’API, avec le message Error: the stored backup period is 12 hours, but --backup-start-time requires 24 or 48.

--clear-backup-start-time supprime un horodatage de début enregistré et lève cette restriction. Combinez cette option avec --backup-period-hours pour effacer l’horodatage de début et définir n’importe quelle période en un seul appel. Elle est incompatible avec --backup-start-time.

​

Sauvegardes

clickhousectl cloud backup list <service-id>
clickhousectl cloud backup get <service-id> <backup-id>

Pour restaurer une sauvegarde, créez un nouveau service à partir de celle-ci : clickhousectl cloud service create --name restored-service --backup-id <backup-id>.

​

ClickPipes

Gérez les ClickPipes permettant d’ingérer des données dans un service Cloud. La plupart des commandes prennent l’ID du service comme premier argument.

# List pipes and get details
clickhousectl cloud clickpipe list <service-id>
clickhousectl cloud clickpipe get <service-id> <clickpipe-id>

# Create a pipe. Sources: object-storage, kafka, kinesis, pubsub,
# postgres, mysql, mongodb, bigquery
clickhousectl cloud clickpipe create object-storage <service-id> \
  --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 <service-id> \
  --name my-cdc-pipe \
  --host pg.example.com \
  --pg-database appdb \
  --username replicator \
  --password <password> \
  --table-mapping public.orders:orders \
  --sync-interval-seconds 30 \
  --ca-certificate ./source-ca.pem

# Lifecycle
clickhousectl cloud clickpipe start <service-id> <clickpipe-id>
clickhousectl cloud clickpipe stop <service-id> <clickpipe-id>
clickhousectl cloud clickpipe resync <service-id> <clickpipe-id>   # CDC pipes only
clickhousectl cloud clickpipe delete <service-id> <clickpipe-id>

# Scaling and settings. scale requires at least one of
# --replicas, --cpu-millicores, or --memory-gb
clickhousectl cloud clickpipe scale <service-id> <clickpipe-id> --replicas 2
clickhousectl cloud clickpipe settings get <service-id> <clickpipe-id>
clickhousectl cloud clickpipe settings update <service-id> <clickpipe-id>

# Discover a source schema without creating a pipe (beta)
clickhousectl cloud clickpipe schema-discover <service-id> kafka [options]
clickhousectl cloud clickpipe schema-discover <service-id> kinesis [options]
clickhousectl cloud clickpipe schema-discover <service-id> object-storage [options]
clickhousectl cloud clickpipe schema-discover <service-id> pubsub [options]

# Reverse private endpoints: AWS PrivateLink, Amazon MSK multi-VPC,
# Google Private Service Connect
clickhousectl cloud clickpipe reverse-private-endpoint list <service-id>
clickhousectl cloud clickpipe reverse-private-endpoint get <service-id> <endpoint-id>
clickhousectl cloud clickpipe reverse-private-endpoint create <service-id> \
  --type VPC_ENDPOINT_SERVICE \
  --description 'kafka source' \
  --vpc-endpoint-service-name <vpc-endpoint-service-name>
clickhousectl cloud clickpipe reverse-private-endpoint update <service-id> <endpoint-id> \
  --custom-private-dns-mapping pg.internal.example.com
clickhousectl cloud clickpipe reverse-private-endpoint delete <service-id> <endpoint-id>

À savoir :

• clickpipe create postgres exige soit --table-mapping <schema.table:target_table> (répétable, une table par flag), soit --table-mapping-json <json> ; les deux peuvent être combinés. La forme JSON reprend textuellement l’objet de mapping de tables de l’API et constitue le seul moyen de définir excludedColumns, sortingKeys, partitionByExpr, partitionKey et tableEngine. Notez que partitionKey partitionne le snapshot initial à des fins de parallélisme et n’a aucun lien avec le PARTITION BY de la table de destination, qui correspond à partitionByExpr. --iam-role est requis avec --auth IAM_ROLE et rejeté avec l’authentification basique, et --replication-slot-name n’est valide qu’avec --replication-mode cdc_only.
• Les paramètres CDC de Postgres sont appliqués à la création du pipe : --sync-interval-seconds, --pull-batch-size, --initial-load-parallelism, --snapshot-rows-per-partition, --snapshot-parallel-tables, --allow-nullable-columns, --enable-failover-slots et --delete-on-merge. Seuls le sync interval et le pull batch size peuvent être modifiés par la suite ; les paramètres de snapshot et de chargement initial ne le peuvent pas.
• --role <role>, disponible sur toutes les sous-commandes clickpipe create, est répétable et sélectionne le rôle ClickHouse accordé à l’utilisateur de destination du pipe. Il remplace le rôle que cet utilisateur recevrait autrement : sans --role, l’utilisateur détient clickpipes_system et default_role ; avec --role my_role, il détient clickpipes_system et my_role. Le rôle doit pouvoir créer des tables dans la base de données de destination — un rôle en lecture seule fait échouer la création avec Not enough privileges. Les noms clickpipes et clickpipes_system, réservés par l’API, sont rejetés.
• Le TLS et la vérification de certificat sont activés par défaut pour les sources Postgres. Une chaîne source approuvée publiquement ne nécessite aucun fichier CA ; pour une CA source privée ou auto-signée, transmettez son bundle PEM avec --ca-certificate <path>. Pour une source ClickHouse Cloud Postgres, récupérez ce bundle avec clickhousectl cloud postgres certs get. La vérification du hostname s’appuie sur --host, sauf si --tls-host <hostname> la remplace.
• Pour les pipes Kafka et Kinesis, --auth est déduit des flags de credential lorsqu’il est omis, et aucune authentification n’est envoyée si aucun flag de credential n’est fourni.
• clickpipe settings couvre uniquement les paramètres d’ingestion des pipes de streaming (Kafka, Kinesis) et de stockage objet, et les paramètres propres à Kafka sont omis pour les pipes non Kafka. Les pipes CDC de bases de données (Postgres, MySQL, MongoDB, BigQuery) n’ont pas de paramètres d’ingestion : settings get sur l’un d’eux se termine avec le code 1 et renvoie vers clickhousectl cloud clickpipe get <service-id> <clickpipe-id>, où sont indiqués leur sync interval et leur pull batch size.
• Un pipe ne peut utiliser qu’un reverse private endpoint ayant atteint le statut Ready ; un endpoint AWS PrivateLink reste en PendingAcceptance tant que la demande de connexion n’a pas été acceptée dans le compte propriétaire de la source. Les pipes Kafka référencent l’endpoint par son ID avec --reverse-private-endpoint-id (répétable) ; les pipes CDC Postgres et MySQL transmettent l’un des dnsNames de l’endpoint via --host.
• Les pipes Google Cloud Pub/Sub sont en preview limitée : contactez le support pour activer la fonctionnalité pour votre organisation avant d’en créer un. --service-account-file prend le chemin d’une clé JSON de service account GCP, ou - pour lire la clé depuis stdin ; la clé n’est jamais acceptée en ligne, elle n’apparaît donc ni dans la liste des processus ni dans l’historique du shell.

​

Postgres services (beta)

Créez et gérez des services ClickHouse Cloud Postgres.

# 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 <pg-id>

# Update a service
clickhousectl cloud postgres update <pg-id> --size m7i.4xlarge --add-tag env=prod

# Reset the password (exactly one of --password or --generate)
clickhousectl cloud postgres reset-password <pg-id> --generate

# Runtime configuration (postgresql.conf + PgBouncer) and CA certificates.
# config patch takes exactly one of --set (repeatable) or --file
clickhousectl cloud postgres config get <pg-id>
clickhousectl cloud postgres config patch <pg-id> --set max_connections=500
clickhousectl cloud postgres config replace <pg-id> --file config.json
clickhousectl cloud postgres certs get <pg-id>

# Read replicas, failover, and point-in-time restore
clickhousectl cloud postgres read-replica create <pg-id> --name replica-1
clickhousectl cloud postgres promote <replica-id> --wait
clickhousectl cloud postgres switchover <pg-id> --wait
clickhousectl cloud postgres restore <pg-id> --name restored --restore-target 2026-04-16T12:00:00Z

# Restart a service
clickhousectl cloud postgres restart <pg-id>

# Delete a service
clickhousectl cloud postgres delete <pg-id>

À savoir :

• --provider vaut aws par défaut ; gcp est également accepté, avec des tailles de machine GCP telles que c4-standard-4. --size est validé par la Cloud API et non par la CLI : une taille non prise en charge n’est donc rejetée qu’au niveau du server.
• Les changements de rôle sont à cohérence à terme, et l’API accuse réception de promote et switchover avant de les appliquer : un code de sortie 0 ne suffit donc pas à confirmer que le rôle a changé. Ces deux commandes acceptent --wait, qui interroge la cible jusqu’à ce qu’elle signale le nouveau rôle, ainsi que --wait-timeout <seconds> (300 par défaut) pour borner cette interrogation. L’ancien primary peut continuer à signaler isPrimary=true pendant plusieurs minutes : vérifiez donc avec clickhousectl cloud postgres list --filter isPrimary=true qu’un seul service est primary.
• postgres delete fonctionne quel que soit l’état du service, y compris running : il n’est donc pas nécessaire de l’arrêter au préalable.

​

Organisations

clickhousectl cloud org list
clickhousectl cloud org get <org-id>
clickhousectl cloud org update <org-id> --name new-name
clickhousectl cloud org prometheus
clickhousectl cloud org usage --from-date 2026-08-01 --to-date 2026-08-31

​

Clés API

clickhousectl cloud key list
clickhousectl cloud key get <key-id>
clickhousectl cloud key create --name ci-key --role-id <role-id>
clickhousectl cloud key update <key-id>
clickhousectl cloud key delete <key-id>

​

Membres et invitations

clickhousectl cloud member list
clickhousectl cloud member get <user-id>
clickhousectl cloud member update <user-id> --role-id <role-id>
clickhousectl cloud member remove <user-id>

clickhousectl cloud invitation list
clickhousectl cloud invitation create --email [e-mail] --role-id <role-id>
clickhousectl cloud invitation get <invitation-id>
clickhousectl cloud invitation delete <invitation-id>

​

Journal d’activité

clickhousectl cloud activity list --from-date 2026-08-01 --to-date 2026-08-31
clickhousectl cloud activity get <activity-id>

​

Sortie JSON

Utilisez l’option --json pour obtenir des réponses au format JSON depuis n’importe quelle commande cloud :

clickhousectl cloud service list --json

Les commandes org prometheus et service prometheus font exception : elles produisent toujours du texte d’exposition Prometheus brut et ignorent silencieusement --json.

​

Développement local

La CLI gère également les installations locales de ClickHouse, les serveurs locaux et les instances Postgres locales basées sur Docker. Consultez la page clickhousectl (CLI) pour bien débuter avec le développement local.

# 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 <version>
clickhousectl local which
clickhousectl local remove <exact-version>

# 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 <name>
clickhousectl local postgres client
clickhousectl local postgres stop [name]
clickhousectl local postgres stop-all
clickhousectl local postgres remove [name]
clickhousectl local postgres dotenv

À savoir :

• Les commandes local sont limitées au périmètre du projet : elles utilisent le répertoire .clickhouse du répertoire de travail courant exact et ne remontent jamais dans les répertoires parents. Placez-vous à la racine du projet avant de les exécuter.
• clickhousectl local use crée également un lien symbolique ~/.local/bin/clickhouse, ce qui rend directement accessibles les sous-commandes standard telles que clickhouse client, clickhouse benchmark et clickhouse format. Passez --no-global pour ne pas créer ce lien symbolique.
• local remove exige une version installée exacte. Elle refuse de supprimer une version utilisée par un serveur en cours d’exécution dans un projet, quel qu’il soit, ou qui correspond à la valeur par défaut actuelle ; --force arrête ces serveurs et efface la valeur par défaut ainsi que le lien symbolique global.
• Sans nom, local server stop arrête default s’il existe, sinon le seul serveur connu ; s’il existe plusieurs serveurs autres que default, un nom est demandé. Sans nom, local server remove ne sélectionne que le default existant — il ne devine jamais un serveur personnalisé.
• local client accepte -v/--version pour choisir une version de client installée en mode hôte/port direct, admet -q de façon répétée pour plusieurs requêtes et accepte plusieurs chemins pour --queries-file. Combiner --query et --queries-file constitue une erreur d’utilisation.
• local postgres start bloque jusqu’à ce que PostgreSQL accepte les connexions, dans la limite du nombre de secondes défini par --wait-timeout (60 par défaut, 600 au maximum). Si --port est omis, le port 5432 est utilisé s’il est libre, sinon un port est sélectionné automatiquement ; un port explicitement demandé mais déjà occupé est rejeté.

​

Autres commandes

# 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

​

Prérequis

• MacOS (aarch64, x86_64) ou Linux (aarch64, x86_64)
• Les commandes Cloud nécessitent une clé API ClickHouse Cloud pour l’accès en écriture ; la connexion OAuth est en lecture seule
• clickhousectl local postgres nécessite Docker