Pular para o conteúdo principal
clickhousectl (alias chctl) é a CLI oficial do ClickHouse, do desenvolvimento local ao ClickHouse Cloud. Ela atende tanto pessoas no terminal quanto scripts e agentes de programação. Com o clickhousectl, você pode:
  • Instalar e alternar entre versões locais do ClickHouse, executar servidores locais isolados e rodar SQL
  • Executar o Postgres localmente com Docker
  • Criar, configurar, escalar, fazer backup e consultar serviços do ClickHouse Cloud
  • Criar, monitorar, configurar e restaurar serviços do ClickHouse Managed Postgres
  • Criar e operar ClickPipes a partir de armazenamento de objetos, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB e BigQuery
  • Gerenciar fontes de dados, dashboards, alertas, webhooks, buscas salvas e funções em um serviço Managed ClickStack
  • Desenvolver UDFs executáveis localmente e implantá-las no ClickHouse Cloud
  • Gerenciar membros da organização, convites, chaves de API e funções
  • Instalar as ClickHouse Agent Skills oficiais em agentes de programação
Esta página apresenta exemplos representativos. clickhousectl <command> --help é a referência definitiva para todos os comandos e flags. A ajuda da maioria dos comandos termina com um bloco CONTEXT FOR AGENTS; nos comandos do Cloud, esse bloco também lista as permissões de chave de API necessárias. Para guias passo a passo, siga os links indicados em cada seção. Para uma visão geral focada no Cloud, consulte CLI do ClickHouse.

Instalação

O clickhousectl funciona no MacOS e no Linux, em arquiteturas ARM64 e x86_64.
O script instala ~/.local/bin/clickhousectl e cria o alias chctl. Verifique se ~/.local/bin está no seu PATH. Você também pode instalá-lo com um gerenciador de pacotes: Apenas o script de instalação e o npm criam o alias chctl. Para atualizar uma instalação existente, execute clickhousectl update (consulte Autoatualização).

Requisitos

  • Docker, apenas para Postgres local
  • Para comandos do Cloud, uma conta do ClickHouse Cloud. Comandos de leitura funcionam com OAuth pelo navegador (cloud auth login). Para criar ou alterar recursos, é necessária uma chave de API. Consulte Autenticação.

Local

Os comandos locais operam no diretório atual. Cada projeto armazena os dados do servidor em .clickhouse/, enquanto os binários do ClickHouse são compartilhados globalmente em ~/.clickhouse/. A CLI não busca nos diretórios pais; por isso, execute os comandos locais a partir da raiz do seu projeto. Consulte o guia de desenvolvimento local para ver o fluxo de trabalho completo.

Instalar e selecionar versões

local use instala a versão, se necessário, define-a como padrão para as próximas inicializações do servidor e cria um link simbólico para ela em ~/.local/bin/clickhouse, para que clickhouse client e clickhouse local fiquem disponíveis no seu PATH. Passe --no-global para não criar o link simbólico. Se já existir um arquivo comum nesse caminho, ele será mantido como está. local remove não remove a versão padrão nem uma versão em uso por um servidor em execução em qualquer projeto. Com --force, esses servidores são interrompidos e a versão é removida, e a definição de versão padrão e o link simbólico também são removidos.

Inicializar um projeto

init é opcional. Ele cria um diretório .clickhouse/ ignorado pelo git para dados de tempo de execução, além de scaffolds SQL que você pode fazer commit: clickhouse/ (tables/, materialized_views/, queries/, seed/, udfs/) e postgres/ (tables/, views/, functions/, queries/, seed/). Ao executá-lo novamente, apenas o que estiver faltando é criado.

Executar servidores locais

Cada servidor nomeado tem seus próprios dados em .clickhouse/servers/<name>/data/, e esses dados são preservados para a próxima inicialização quando o servidor é parado. Se nenhum nome for informado, o primeiro servidor será default; se default já estiver em execução, um novo nome será gerado. As portas padrão são HTTP 8123 e TCP 9000; se estiverem ocupadas, portas livres serão atribuídas. --version escolhe uma versão apenas para aquela inicialização, sem alterar a versão padrão. Uma inicialização simples, sem versão informada e sem versão padrão definida, instala latest sem defini-la como padrão; para isso, execute local use latest antes.

Executar SQL com o cliente local

local client se conecta a um servidor nomeado usando o mesmo binary do ClickHouse que o executa (nome padrão: default). Os argumentos após -- são repassados ao clickhouse client sem alterações. A saída e o status de saída vêm do clickhouse client, mesmo no modo JSON; por isso, ao escrever scripts, defina você mesmo o formato de saída SQL.

Configuração personalizada do servidor

Coloque uma configuração parcial em XML ou YAML em ~/.clickhouse/configs/ e selecione-a pelo nome ao iniciar um servidor:
O arquivo é sobreposto aos valores padrão internos, portanto só precisa conter as configurações que você alterar. A seleção não é memorizada: uma inicialização posterior sem --config remove o overlay. Os caminhos dos dados e as portas gerenciados sempre prevalecem sobre os valores da configuração.

Gravar os detalhes de conexão em um arquivo dotenv

dotenv lê as portas reais do servidor em execução e grava CLICKHOUSE_HOST, CLICKHOUSE_PORT e CLICKHOUSE_HTTP_PORT, além do usuário, da senha e do banco de dados, quando você os fornece. As demais linhas de um arquivo existente são preservadas. Carregue o arquivo com o carregador de dotenv da sua aplicação; nunca use eval na pré-visualização exibida.

Postgres local

O Postgres local roda no Docker, então o Docker precisa estar em execução. As versões 17 e 18 do Postgres são compatíveis, incluindo tags de imagem como 18-alpine; novas instâncias usam a versão 18 por padrão.
Uma instância é identificada pelo nome e pela versão principal. Ao retomar uma instância parada, a porta, o usuário, a senha e o banco de dados originais são reutilizados; por isso, as flags de criação não têm efeito na retomada. Uma senha aleatória é gerada, a menos que você informe uma. O arquivo .env.local contém a senha, então mantenha-o fora do controle de versão.

UDFs locais

local udf implanta UDFs executáveis a partir de clickhouse/udfs/<name>/ em um servidor local. cloud udf envia o mesmo diretório para o Cloud (consulte UDFs no Cloud).
Todos os comandos, exceto init, aceitam --server <name> (padrão: default). O deploy valida o udf.json da mesma forma que o Cloud. Em um servidor em execução, ele recarrega as funções e confirma que a função foi carregada. O tempo de execução native só pode ser implantado localmente em hosts Linux amd64 ou arm64. Consulte o guia de funções definidas pelo usuário.

Autenticação

Os comandos do Cloud usam um de dois tipos de credencial: Se você ainda não tem uma conta no ClickHouse Cloud, clickhousectl cloud auth signup abre a página de cadastro no seu navegador.

Login com OAuth

Isso abre seu navegador para o fluxo de dispositivo do OAuth. Os tokens são salvos globalmente em ~/.clickhouse/tokens.json e atualizados automaticamente.
O OAuth é read-only. Para criar ou alterar recursos, faça login com uma chave de API.

Chave de API

Crie uma chave de API com as funções necessárias para os seus comandos e, em seguida, salve-a. O prompt interativo evita que o segredo fique registrado no histórico do seu shell:
O login verifica a chave e exibe a identidade à qual ela pertence. Se a API rejeitar a chave, ela não é salva e o comando termina com código de saída 4. Se a API estiver inacessível, a chave é salva e um aviso é exibido. Para CI e outras automações, injete a chave pelo seu gerenciador de segredos em vez de salvá-la:
Em desenvolvimento, a CLI também lê essas variáveis de um arquivo .env no diretório atual. Não inclua o .env no controle de versão.

Verificar e limpar credenciais

O whoami funciona com qualquer tipo de credencial e retorna o código de saída 4 se as credenciais forem rejeitadas. O status pode retornar o código de saída 0 mesmo quando nenhuma credencial funciona, por isso use o whoami para testar o acesso. O logout não remove variáveis de ambiente nem edita o .env.

Precedência de credenciais

A primeira fonte disponível prevalece:
  1. Flags --api-key e --api-secret
  2. .clickhouse/credentials.json
  3. Variáveis de ambiente exportadas
  4. Variáveis do arquivo .env no diretório atual
  5. Tokens OAuth globais
Use --debug em qualquer comando cloud para exibir no stderr a fonte de credenciais selecionada e a URL da API:

Selecionar uma organização

Os comandos com escopo de organização selecionam a organização automaticamente somente quando suas credenciais dão acesso a exatamente uma. Caso contrário, informe --org-id ou --org-name com o nome exato:
A maioria dos comandos de recursos aceita um ID posicional ou um --name exato. Consulte autenticação e acesso para mais informações sobre permissões, chaves restritas e limpeza ao fazer logout.

Cloud

Os comandos do Cloud chamam a API do ClickHouse Cloud. As requisições de criação e atualização retornam assim que a API as aceita; por isso, consulte get repetidamente até que o recurso atinja o estado desejado.

Serviços

Salve a senha inicial exibida na criação, pois ela é retornada apenas uma vez. O comando de criação retorna antes de o provisionamento terminar, então repita get até que o estado seja running. Se --ip-allow for omitido, todos os IPs serão permitidos (0.0.0.0/0). As entradas aceitam o formato IP_OR_CIDR=DESCRIPTION. Restaure um backup em um novo serviço com --backup-id ou implante um serviço na infraestrutura BYOC com --byoc-id. Atualize, escale e configure um serviço:
A memória por réplica deve ser um múltiplo de 4 GB, com no máximo 120 GB em serviços não pagos e 356 GB em serviços pagos, e até 50 réplicas. Os limites da organização e do warehouse podem reduzir esses valores. O escalonamento automático horizontal exige que a funcionalidade correspondente esteja habilitada na organização. update altera apenas as flags que você informar. Os outros grupos de comandos de serviço são settings (list, get, schema, set, unset), scaling-schedule, upgrade-window, replica-aware-routing (Beta), snapshot (Beta), private-endpoint, backup-config e prometheus. Consulte criar e operar um Serviço Cloud.

API de consultas

cloud service query executa uma instrução SQL via HTTP, sem exigir um binário clickhouse local nem a senha do serviço:
  • OAuth executa a consulta com a sua identidade, com acesso SQL read-only. Nada é vinculado ao serviço.
  • Chave de API: na primeira chamada, o clickhousectl adiciona sua chave de API ao endpoint da API de consultas do serviço e, se necessário, cria o endpoint com as funções sql_console_admin. As funções, origens e outras vinculações de chaves existentes são mantidas, e nenhuma chave nova é criada. Quando a CLI altera o endpoint, ela exibe Binding the authenticated API key to the Query API endpoint for service '<name>'... no stderr. Passe --no-auto-enable para que o comando falhe nesse caso.
Uma chave por serviço salva por uma versão anterior da CLI continua tendo precedência para esse serviço. Se a API rejeitá-la, cloud service repair-query-key <service-id> a substitui de forma explícita. A API de consultas aceita uma instrução por requisição. A requisição pode atingir o tempo limite após cerca de 30 segundos enquanto o SQL continua em execução, portanto verifique o resultado antes de repetir uma escrita. Use o clickhouse client para scripts com várias instruções, cargas em massa e consultas longas. A allowlist de IPs do serviço restringe conexões diretas, mas não a rota da API de consultas, que passa por proxy. Consultar um serviço idle o reativa; já um serviço parado precisa ser iniciado com cloud service start. Gerencie o endpoint da API de consultas do serviço, os endpoints SQL nomeados e as consultas salvas:
query-endpoint create substitui as funções de todas as chaves vinculadas ao endpoint. Consulte Comportamento do SQL e da API de consultas.

Managed Postgres

cloud postgres gerencia o ClickHouse Managed Postgres. Esses comandos estão em Beta, e o suporte ao GCP está em prévia privada.
Os tamanhos disponíveis na AWS incluem m6gd.large, c6gd.xlarge e r6gd.xlarge. No GCP, passe --provider gcp com uma região do GCP e um tamanho como c4-standard-lssd-4. Salve a senha e a string de conexão retornadas pelo create. As respostas posteriores do get nunca retornam credenciais, e reset-password é a única forma de obter novas. Conecte-se com o psql usando sslmode=verify-full e o arquivo da CA. Se você omitir as flags de acesso no create, todos os endereços IPv4 e IPv6 serão permitidos no Postgres (5432) e no PgBouncer (6432). Passe um --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION] por regra ou --block-public-access para não definir nenhuma regra. Depois que você passar uma regra, somente as regras listadas serão aplicadas. Monitore e recupere:
cloud postgres query aceita apenas OAuth, portanto falha enquanto uma fonte de chave de API de maior prioridade estiver ativa. metrics, slow-queries e prometheus cuidam do monitoramento. restore copia as regras de acesso IPv4 atuais da origem para o serviço restaurado, a menos que você informe --ip-allow ou --block-public-access. Restaurações e réplicas são retornadas sem senha. promote e switchover retornam assim que a operação é aceita; após um promote, consulte postgres get --json periodicamente até que a réplica informe isPrimary: true. Veja o guia do Managed Postgres.

ClickPipes

cloud clickpipe faz a ingestão de dados de armazenamento de objetos, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB e BigQuery. A criação e a descoberta de esquema exigem uma chave de API e um serviço de destino em execução. Cada fonte de dados tem seu próprio subcomando clickpipe create <source>; execute-o com --help para ver as flags disponíveis. Carregue arquivos do S3 usando uma IAM role. Primeiro, descubra o schema e, depois, escolha as colunas:
Replique o Postgres com CDC. O TLS é verificado por padrão; para uma origem Managed Postgres, exporte a CA dela e informe-a:
--table-mapping cria tabelas ReplacingMergeTree; por isso, leia o estado atual com FINAL WHERE _peerdb_is_deleted = 0. Um pipe do Kafka segue o mesmo padrão: execute clickpipe schema-discover kafka com as mesmas flags de origem e, em seguida, passe as colunas:
Por padrão, os pipes do BigQuery executam um snapshot. Para CDC, informe --replication-mode cdc, um --replication-method e, para cada tabela, uma coluna de watermark ou uma função de eventos em --table-mapping-json; agende as sincronizações com --sync-cron ou --sync-interval-seconds. Para operar pipes existentes:
Os pipes de CDC precisam estar Paused antes do update: pare o pipe, consulte get repetidamente até que ele esteja Paused e, em seguida, atualize-o. O serviço pode retomar o pipe durante a atualização, portanto execute start somente se get ainda mostrar Paused. A opção --start-paused está disponível para armazenamento de objetos, Kafka, Kinesis e Pub/Sub. Os demais grupos de comandos são cdc-scaling, context get (prontidão e principal da identidade de carga de trabalho do GCP) e reverse-private-endpoint. Consulte o guia de ClickPipes e a referência de configuração de ClickPipe.

ClickStack

cloud clickstack gerencia fontes de dados, dashboards, alertas, webhooks, buscas salvas e funções em um serviço Managed ClickStack existente. Os recursos são arquivos JSON (--file, ou - para stdin). As leituras aceitam autenticação via OAuth; as gravações exigem uma chave de API.
Cada atualização do ClickStack substitui o recurso por inteiro. Salve o estado atual com get --json e envie a definição completa, e não apenas os campos alterados. Consulte o guia do ClickStack.

UDFs no Cloud

cloud udf gerencia UDFs executáveis no escopo da organização, suas versões e suas anexações a serviços. deploy envia o diretório que você testou com local udf, aguarda a conclusão da compilação, anexa essa versão e aguarda até que ela seja implantada:
Para executar cada etapa manualmente, use udf create, udf version create, udf attach (com --wake para um serviço idle), udf detach e udf delete. Esses comandos retornam assim que a solicitação é aceita; consulte periodicamente udf get e udf attachment get para acompanhar o andamento. As leituras aceitam OAuth; as gravações exigem uma chave de API. Consulte o guia de funções definidas pelo usuário.

Organizações e acesso

Os subcomandos de cloud org recebem --org-id, nunca um ID posicional. org usage abrange no máximo 31 dias. org também inclui quota, balance, notification-types, role (funções personalizadas da organização) e byoc (infraestrutura BYOC). As notificações estão em Beta. Gerencie membros, convites e chaves de API:
Omitir --ip-allow em key create bloqueia todo o acesso à rede, ao contrário do que ocorre na criação de serviços. O segredo é exibido apenas uma vez. key list retorna uma única página, a menos que você informe --all. Em key update, as flags omitidas mantêm suas configurações, enquanto --clear-expiry, --clear-roles e --clear-ip-allow as removem.

Backups

A restauração sempre cria um novo serviço. cloud backup bucket (get, create, update, delete) configura um bucket de backup próprio (bring-your-own) a partir de um arquivo JSON específico do provedor. Consulte a seção de backup do Guia do Serviço Cloud.

Saída em JSON

Os comandos que retornam dados estruturados aceitam --json, incluindo os comandos locais, do Cloud, skills, update e telemetry:
Quando a CLI detecta um agente de programação (como Claude Code, Cursor, Codex, Gemini CLI, Goose ou Devin, ou qualquer ferramenta que defina AI_AGENT), ela seleciona JSON automaticamente. O SQL e os clientes nativos mantêm seus próprios formatos: cloud service query retorna JSONEachRow no modo JSON, e a saída de local client é sempre nativa. Scripts que interpretam a saída de consultas devem informar --format explicitamente. No modo JSON, os erros de tempo de execução são enviados ao stderr como um objeto com um code estável e uma message:
Use error.code para a lógica de ramificação, e não a mensagem. Erros de uso continuam sendo exibidos como texto, com código de saída 2. Consulte automação e contratos de saída para conhecer os formatos de saída e os códigos de erro.

Códigos de saída

local client, local postgres client e outros comandos que delegam a execução a clientes nativos repassam o próprio status de saída do cliente.

Agent Skills

Instale as ClickHouse Agent Skills oficiais nos seus agentes de programação:
Por padrão, as Skills são instaladas no projeto atual, ou no seu diretório pessoal com --global. O diretório compartilhado .agents/skills/ é sempre incluído. Sem um terminal, você precisa passar --agent, --all ou --detected-only. Execute clickhousectl skills --help para ver os nomes de agentes compatíveis.

Autoatualização

A CLI também verifica se há atualizações em segundo plano, no máximo uma vez a cada 24 horas, e exibe um aviso quando uma versão mais recente estiver disponível.

Telemetria

O clickhousectl coleta dados de uso anônimos para orientar o desenvolvimento. A primeira execução exibe um aviso e não envia nada; a coleta começa a partir da execução seguinte, a menos que você a desative. Cada evento contém:
  • O caminho do comando e os nomes das flags e argumentos passados explicitamente, nunca seus valores
  • O resultado e o código de saída
  • Para um comando digitado incorretamente, o nome do comando ou da flag sugerido pela CLI, nunca o que você digitou
  • Para falhas em tempo de execução, categorias limitadas: etapa e tipo da falha, um status HTTP presente em uma allowlist e categorias de nova tentativa, estado de provisionamento e duração
  • A versão da CLI, o SO e a arquitetura, se a execução ocorre em CI e o agente de programação detectado
Valores dos argumentos, SQL, credenciais, identificadores de recursos, argumentos após -- e mensagens de erro nunca são registrados. Não há ID de instalação nem de dispositivo. Para desativar:
Defina CHCTL_TELEMETRY_DEBUG=1 para exibir a carga útil no stderr sem enviar nenhum dado. Consulte os detalhes da telemetria.