> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação do Terminal web, uma sessão `clickhouse-client` no navegador via WebSocket

# Terminal web

O terminal web é uma interface experimental 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`.

<Note>
  O terminal web é um recurso experimental e vem desativado por padrão; consulte [Como habilitar o recurso](#enabling-the-feature) abaixo.
</Note>

<div id="enabling-the-feature">
  ## Habilitando o recurso
</div>

O endpoint `/webterminal` é controlado pela configuração de servidor `allow_experimental_webterminal`. Quando essa configuração está como `false` (o padrão), as solicitações para `/webterminal` retornam o status HTTP `403 Forbidden`.

Para habilitá-lo, adicione o seguinte à configuração do servidor:

```xml theme={null}
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
```

Depois de habilitar, acesse `/webterminal` em qualquer porta HTTP do ClickHouse (por exemplo, `http://localhost:8123/webterminal`) para abrir o terminal.

<div id="authentication">
  ## Autenticação
</div>

O terminal web autentica o usuário com as mesmas verificações de `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:

```json theme={null}
{"type": "auth", "user": "<user>", "password": "<password>"}
```

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.

<div id="session">
  ## Como funciona a sessão
</div>

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](https://xtermjs.org/) para renderização. Todos os recursos são fornecidos pelo próprio binário do ClickHouse — nenhum CDN de terceiros é carregado.

<div id="play-integration">
  ## Integração com `/play`
</div>

A interface Web SQL [`/play`](/pt-BR/concepts/features/interfaces/http) 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 a configuração experimental não está ativada).

<div id="security">
  ## Considerações de segurança
</div>

O terminal web expõe uma sessão interativa semelhante a um shell para qualquer pessoa que consiga se autenticar no endpoint HTTP do ClickHouse, portanto as mesmas ressalvas aplicáveis ao protocolo HTTP também se aplicam aqui:

* 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.

<div id="platform">
  ## Disponibilidade da plataforma
</div>

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 `allow_experimental_webterminal` não está habilitado).