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
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
Oclickhousectl funciona no MacOS e no Linux, em arquiteturas ARM64 e x86_64.
~/.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
.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:
--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 como18-alpine; novas instâncias usam a versão 18 por padrão.
.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).
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
~/.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:.env no diretório atual. Não inclua o .env no controle de versão.
Verificar e limpar credenciais
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:- Flags
--api-keye--api-secret .clickhouse/credentials.json- Variáveis de ambiente exportadas
- Variáveis do arquivo
.envno diretório atual - Tokens OAuth globais
--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:
--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, consulteget repetidamente até que o recurso atinja o estado desejado.
Serviços
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:
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 exibeBinding the authenticated API key to the Query API endpoint for service '<name>'...no stderr. Passe--no-auto-enablepara que o comando falhe nesse caso.
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.
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:
--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:
--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:
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.
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:
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
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:
--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
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:
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:
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:--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
Telemetria
Oclickhousectl 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
-- e mensagens de erro nunca são registrados. Não há ID de instalação nem de dispositivo.
Para desativar:
CHCTL_TELEMETRY_DEBUG=1 para exibir a carga útil no stderr sem enviar nenhum dado. Consulte os detalhes da telemetria.