Conectar o ProbeDeck ao ClickHouse

Conecte o ProbeDeck no iOS ou iPadOS ao ClickHouse Cloud ou a um ClickHouse auto-hospedado.

O ProbeDeck é um cliente para iOS e iPadOS que permite verificar a integridade de um servidor ClickHouse, inspecionar as tabelas system e executar SQL. Ele se conecta à interface HTTP do ClickHouse pela rede do dispositivo ou por um bastion SSH; não requer um servidor de retransmissão.

​

Antes de começar

• Instale o ProbeDeck pela App Store.
• Use iOS ou iPadOS 17.0 ou posterior.
• Permita que o dispositivo acesse o endpoint HTTP ou HTTPS do ClickHouse pela rede, por VPN ou por um bastion SSH.
• Crie um usuário do ClickHouse com acesso aos bancos de dados que deseja consultar.
• Conceda ao usuário acesso SELECT às tabelas system relevantes para monitoramento.

ProbeDeck	ClickHouse Cloud	ClickHouse auto-hospedado	Observações
1.1.7 ou posterior	Serviço atual	Nenhuma versão mínima de servidor fixada	Usa a interface HTTP(S). Teste a conexão e verifique cada seção de monitoramento em relação à versão do seu servidor e às permissões concedidas.

Algumas seções de monitoramento dependem de tabelas de log opcionais ou de tabelas system mais recentes. Por exemplo, system.server_settings, que o ProbeDeck usa para obter o limite de memória configurado, requer o ClickHouse 23.3 ou posterior. O ProbeDeck marca uma seção afetada como limitada quando sua fonte não está disponível.

​

Como funciona

1. O ProbeDeck envia solicitações SQL ao endpoint HTTP(S) do ClickHouse.
2. Ele lê dados de monitoramento das tabelas system usando o usuário configurado do ClickHouse.
3. O aplicativo exibe os resultados das consultas e as visualizações de monitoramento no dispositivo. Um bastion SSH pode encaminhar a mesma conexão HTTP(S) quando não há uma rota direta do dispositivo até o endpoint.

​

Conectar ao ClickHouse Cloud

1. Obtenha os detalhes de conexão do serviço

   No console do ClickHouse Cloud, abra seu serviço, selecione Connect e escolha HTTPS.

   Para se conectar ao ClickHouse via HTTP(S), você precisa das seguintes informações:

   Parâmetro(s)	Descrição
   HOST and PORT	Normalmente, a porta é 8443 ao usar TLS ou 8123 quando não se usa TLS.
   DATABASE NAME	Por padrão, há um banco de dados chamado default; use o nome do banco de dados ao qual você deseja se conectar.
   USERNAME and PASSWORD	Por padrão, o nome de usuário é default. Use o nome de usuário apropriado para o seu caso de uso.

   Os detalhes do seu serviço do ClickHouse Cloud estão disponíveis no console do ClickHouse Cloud. Selecione um serviço e clique em Connect:

   

   Escolha HTTPS. Os detalhes de conexão são exibidos em um comando curl de exemplo.

   

   Se você estiver usando ClickHouse autogerenciado, os detalhes de conexão são definidos pelo administrador do seu ClickHouse.

2. Adicione a conexão no ProbeDeck

   1. Na tela Connections, toque em +.
   2. Insira um nome para a conexão e o host sem https://.
   3. Defina Port como 8443 e ative TLS.
   4. Insira o nome de usuário e a senha do banco de dados exibidos na caixa de diálogo Connect. O nome do banco de dados é opcional.
   5. Toque em Test Connection. Após uma verificação bem-sucedida, o ProbeDeck exibe a versão do servidor e o tempo de ida e volta.
   6. Toque em Save.

   O ProbeDeck autentica solicitações SQL ao endpoint do serviço usando essas credenciais do banco de dados. O ClickHouse Cloud usa chaves no nível da organização, disponíveis na página API Keys, para a Cloud API e os endpoints da Query API. O fluxo de conexão SQL do ProbeDeck não usa essas chaves.

​

Conecte-se ao ClickHouse auto-hospedado

1. Escolha o endpoint HTTP

   Use a porta 8123 para a interface HTTP padrão não criptografada. Para HTTPS, ative o TLS e use a porta configurada no servidor; 8443 é uma escolha comum.

   As portas 9000 e 9440 pertencem ao protocolo nativo do ClickHouse. O ProbeDeck usa a interface HTTP(S); portanto, informe a porta HTTP do servidor.

2. Adicione e teste a conexão

   1. Na tela Connections, toque em +.
   2. Insira o host do servidor sem o esquema de URL.
   3. Defina a porta HTTP(S) e a opção de TLS.
   4. Insira o nome de usuário, a senha e o banco de dados opcional do ClickHouse.
   5. Toque em Test Connection e depois em Save.

   Para um servidor na rede local, o iOS pode solicitar permissão para acessar a rede local. Se o endpoint estiver acessível apenas por uma rede corporativa, conecte primeiro o dispositivo à VPN.

​

Conecte-se por meio de um bastion SSH

Ative o Túnel SSH no formulário de conexão e informe:

1. O host do bastion e a porta SSH (22 por padrão).
2. O nome de usuário SSH.
3. Uma senha SSH ou uma chave privada.

O ProbeDeck abre um canal SSH direct-tcpip do bastion para o host do ClickHouse e a porta HTTP(S) na seção Servidor. Na primeira conexão, compare a impressão digital SHA-256 da chave de host do bastion com um valor fornecido pelo administrador do servidor antes de aceitá-la.

​

Configure a autenticação e o TLS

O ProbeDeck envia o nome de usuário e a senha do banco de dados nos cabeçalhos da requisição X-ClickHouse-User e X-ClickHouse-Key. Ele não inclui credenciais na URL.

Para usar TLS mútuo, ative TLS Client Certificate e importe um arquivo PKCS#12 (.p12) que contenha o certificado do cliente e a chave privada. Em seguida, informe a frase secreta.

Quando um endpoint auto-hospedado apresenta um certificado autossinado ou emitido por uma CA privada, o ProbeDeck exibe sua impressão digital SHA-256, emissor, assunto e período de validade. Compare a impressão digital com o valor fornecido pelo administrador do servidor antes de aceitá-lo. O ProbeDeck vincula a decisão àquela conexão; uma alteração no certificado interrompe a conexão até que você a revise.

O ProbeDeck armazena os segredos de conexão e o material de chave importado no Keychain do iOS do dispositivo.

​

Monitorar o ClickHouse

Abra a conexão salva e selecione Monitor. O dashboard resume as seguintes fontes:

Área	Fonte do ClickHouse
Consultas em execução, tempo decorrido, memória e linhas lidas	system.processes
Estado da replicação e fila	system.replicas, system.replication_queue
Disks, partes e merges	system.disks, system.parts, system.merges
Mutações	system.mutations
Métricas de memória e do servidor	system.metrics, system.asynchronous_metrics, system.server_settings
Taxas históricas de consultas e de disco	system.metric_log, system.asynchronous_metric_log

Clique em consultas em execução para ordenar as consultas ativas por tempo decorrido e verificar o uso de memória e as linhas lidas.

​

Consulte o conjunto de dados de preços de imóveis do Reino Unido

Este exemplo usa o conjunto de dados de preços de imóveis do Reino Unido. Carregue o conjunto de dados em uk_price_paid e, em seguida:

1. Abra a conexão e selecione Data.
2. Abra o Editor SQL.
3. Execute esta consulta limitada e somente leitura:

SELECT
    town,
    count() AS sales,
    round(avg(price)) AS average_price
FROM uk_price_paid
GROUP BY town
ORDER BY sales DESC
LIMIT 10

O resultado deve conter dez cidades com suas respectivas quantidades de transações e preços médios.

​

Limitações conhecidas

• O ProbeDeck é executado no iOS e no iPadOS 17.0 ou posterior.
• Usuários da versão gratuita podem salvar uma conexão por vez. Excluí-la libera a vaga; o ProbeDeck Pro permite salvar conexões ilimitadas.
• Compatível com a interface HTTP(S) do ClickHouse, mas não com o protocolo nativo.
• O ProbeDeck carrega resultados SQL em páginas de 200 linhas e limita cada solicitação a 10.000 linhas. Use uma cláusula WHERE seletiva e LIMIT para tabelas grandes.
• A visibilidade do monitoramento depende das permissões do usuário do ClickHouse e das tabelas de log opcionais.
• O dispositivo precisa ter uma rota até o endpoint pela rede, por uma VPN ou pelo túnel SSH integrado.
• monitoramento e SQL somente leitura não exigem compra no aplicativo. KILL QUERY, KILL MUTATION, instruções de gravação e DDL e outras ações operacionais exigem o ProbeDeck Pro.

​

Solução de problemas

Authentication failed

Copie novamente o nome de usuário e a senha do banco de dados. Para o endpoint do serviço ClickHouse Cloud, use as credenciais do banco de dados na caixa de diálogo Connect do serviço. Não use uma chave da organização na página API Keys do ClickHouse Cloud.

A conexão foi recusada ou expirou

Confirme se o dispositivo consegue acessar o host e a porta HTTP(S). Verifique a lista de acesso IP do Cloud, a VPN, o firewall e o mapeamento de portas. Não use as portas do protocolo nativo 9000 ou 9440.

O monitoramento mostra permissões limitadas

O usuário do ClickHouse não consegue ler uma ou mais tabelas system necessárias. Peça ao administrador do servidor as permissões SELECT mínimas necessárias para as áreas de monitoramento que pretende usar e reconecte-se.

A impressão digital do TLS foi alterada

Peça ao administrador do servidor que confirme a rotação do certificado antes de aceitar a nova impressão digital. Uma alteração inesperada pode indicar um endpoint diferente ou um caminho de interceptação de TLS.

​

Próximas etapas

• Consulte o site do ProbeDeck para ver detalhes específicos do produto.
• Consulte a documentação da interface HTTP do ClickHouse para obter informações sobre a configuração do servidor.