O terminal web é uma interface no navegador que fornece uma sessão interativa do clickhouse-client via WebSocket. Ele está disponível em qualquer porta HTTP do ClickHouse no caminho /webterminal.
Navegue até /webterminal em qualquer porta HTTP do ClickHouse (por exemplo, http://localhost:8123/webterminal) para abrir o terminal.
Habilitando e desabilitando a funcionalidade
/webterminal vem habilitado por padrão e é controlado pela configuração do servidor enable_webterminal. Para desabilitá-lo, defina a configuração como false; as requisições para /webterminal passarão a retornar o status HTTP 403 Forbidden.
enable_webterminal substitui a antiga configuração allow_experimental_webterminal. O nome antigo ainda é aceito por questão de compatibilidade retroativa quando enable_webterminal não está definido.
Session e de controle de acesso do protocolo HTTP, mas as credenciais são transmitidas pelo próprio canal da conexão WebSocket já estabelecida, em vez de pela solicitação de upgrade HTTP. Após a conclusão do handshake do WebSocket, o navegador envia a primeira mensagem em JSON:
O campo user é opcional: quando omitido ou vazio, o nome de usuário usa como padrão a configuração do servidor default_session_user (ou sua sobrescrita por endpoint em uma configuração de protocolos componíveis), que é default, salvo configuração em contrário. Se default_session_user for definido como uma string vazia, conexões sem nome de usuário serão proibidas: uma mensagem auth com user omitido ou vazio falha na autenticação, o servidor fecha o WebSocket com o código 1008 e, quando a seção session_log está habilitada na configuração do servidor, a recusa é registrada em system.session_log como um evento LoginFailure com user vazio.
Isso evita colocar credenciais em parâmetros de consulta da URL ou em cabeçalhos Authorization incluídos na solicitação de upgrade, onde elas poderiam acabar no histórico do navegador, nos logs de acesso do servidor e nos logs do proxy reverso. Os parâmetros de URL, o HTTP Basic e os cabeçalhos X-ClickHouse-User/X-ClickHouse-Key na solicitação de upgrade intencionalmente não são considerados pelo /webterminal.
Credenciais inválidas fazem o servidor fechar o WebSocket com o código 1008; a interface do navegador solicita as credenciais novamente.
Após a autenticação, o servidor executa o clickhouse-client conectado a um pseudoterminal e encaminha sua entrada e saída via WebSocket. A sessão oferece a experiência completa do clickhouse-client, incluindo:
- Realce de sintaxe.
- Autocompletar.
- Consultas de várias linhas.
- Histórico de comandos (armazenado no servidor durante a sessão).
O terminal usa xterm.js para renderização. Todos os recursos são fornecidos pelo próprio binário do ClickHouse — nenhum CDN de terceiros é carregado.
A interface Web SQL /play incorpora o terminal web como um painel acoplável. Ative-o pelo ícone de terminal na barra lateral ou pressione a tecla ~ quando o editor de consulta estiver vazio. A página /play detecta a disponibilidade de /webterminal ao carregar e oculta os controles do terminal quando o endpoint não está disponível (por exemplo, quando enable_webterminal está definido como false).
Este site de documentação incorpora o mesmo terminal em uma barra estreita para desenvolvedores na parte inferior da página, conectado ao ClickHouse playground como o usuário play, somente leitura, para que seja possível testar os exemplos de qualquer página sem sair dela. A barra fixa reserva um espaço correspondente no fim da página para não ocultar os controles do rodapé. Enquanto o terminal está aberto, a página de documentação fica bloqueada e sua barra de rolagem é ocultada. A rolagem sobre o terminal fica restrita ao seu histórico e não move a página de documentação por trás dele. Clique na barra “ClickHouse terminal” ou pressione a tecla ~ para abrir o painel com preenchimento acima da barra. Clique novamente na barra, use o chevron, pressione ~ ou Escape, ou arraste a borda superior do painel para baixo para recolhê-lo; essa borda também permite redimensioná-lo. Encerrar a sessão — exit ou Ctrl+D — também recolhe o painel.
Ao fechar o painel, a sessão e seu histórico são mantidos: ao reabrir o terminal, você retorna ao mesmo prompt. A sessão permanece na página e, portanto, é preservada ao navegar entre páginas da documentação, mas não ao recarregar a aba do navegador — após recarregá-la, o painel retorna com uma nova sessão.
A barra do terminal faz parte do layout para desktop do site e não está disponível em viewports estreitos.
Considerações de segurança
- Sempre disponibilize
/webterminal por HTTPS em ambientes não confiáveis para proteger as credenciais e o tráfego da sessão.
- Restrinja o acesso no nível da rede (firewall, proxy reverso ou a configuração
listen_host) da mesma forma que você restringe o acesso ao protocolo HTTP.
- O endpoint valida o cabeçalho
Origin em relação ao Host para mitigar o sequestro de WebSocket entre origens; configure os proxies reversos adequadamente se você encerrar o TLS externamente.
- Por trás de um proxy reverso que encerra TLS, a conexão upstream com o ClickHouse usa
http simples, embora o navegador use https; por isso, a verificação estrita de mesma origem rejeitaria conexões legítimas. Para essas implantações, defina webterminal_allowed_origins como uma lista, separada por vírgulas, de origens completas autorizadas a abrir sessões WebSocket; quando essa configuração não está vazia, ela substitui a verificação padrão de mesma origem. Exemplo: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.
O handler também impõe conformidade com o protocolo WebSocket de acordo com a RFC 6455: frames de cliente sem máscara, opcodes reservados, frames de controle grandes demais ou fragmentados e bits RSV reservados são rejeitados com códigos de fechamento por erro de protocolo.
O handler é compilado em todas as plataformas suportadas pelo ClickHouse. A camada de pseudoterminal usada pelo executor integrado do clickhouse-client é implementada com base em primitivas POSIX portáveis (posix_openpt/grantpt/unlockpt), com uma implementação específica para Linux que usa o ptsname_r, que é seguro para threads. Os links para /webterminal na página inicial do ClickHouse e em /play ficam ocultos automaticamente quando o endpoint não está disponível (por exemplo, quando enable_webterminal está definido como false). 
