Pular para o conteúdo
Saiku Cloud

Conectar um data warehouse ClickHouse

Este guia mostra como conectar um banco ClickHouse (ClickHouse Cloud ou self-hosted) ao Saiku Cloud. Cinco minutos se o seu data warehouse já é público; dez se precisar criar um usuário somente leitura.

Impacto no tier: todos os tiers do Saiku Cloud (Starter, Team, Business) suportam BYOC do ClickHouse.

O que você vai precisar

  • Uma instância ClickHouse 23.8+ (versões mais antigas funcionam, mas a superfície de dialeto que testamos é 23.8+).
  • Acessibilidade de rede — veja o passo 1.
  • Acesso admin ao seu data warehouse para criar um usuário somente leitura (ou as credenciais de um usuário somente leitura existente).

Passo 1 — Allowlist do nosso IP de egress

Todas as consultas do Saiku Cloud para o seu data warehouse saem de um único IP estático:

87.99.153.244

Adicione isso à allowlist de rede do seu data warehouse antes de testar a conexão. Notas por provedor:

  • ClickHouse Cloud: Console → seu serviço → Settings → Network → IP access list. Adicione 87.99.153.244 como regra de IP único.
  • Self-hosted: firewall na frente (UFW, iptables, security group do seu provedor de nuvem) mais <allow_for_users> no users.xml se você restringiu quem pode conectar.

O IP é estável — nos comprometemos a dar ao menos 30 dias de aviso antes de qualquer rotação. Política completa: nosso compromisso de estabilidade do IP de egress.

Passo 2 — Crie um usuário somente leitura no ClickHouse

O Saiku Cloud só lê do seu data warehouse — nunca escreve, nunca altera schemas. O formato de menor privilégio:

-- As the default user or another superuser:
CREATE USER saiku_read IDENTIFIED WITH plaintext_password BY 'pick-something-strong';


-- Grant read access to the database(s) you want Saiku to see.
-- Repeat for each database.
GRANT SELECT ON analytics.* TO saiku_read;

Algumas notas:

  • plaintext_password é o método de autenticação mais simples; o ClickHouse Cloud também suporta sha256_password e double_sha1_password. Qualquer um funciona para nossa conexão JDBC — o driver faz hash antes do tráfego.
  • ClickHouse Cloud tem uma UI para gerenciamento de usuários (Console → Users) se preferir não escrever SQL.
  • Perfil de configurações: considere criar um perfil separado para saiku_read com um limite apertado de max_memory_usage + max_execution_time para que uma query descontrolada não impacte sua carga de produção. Veja os docs de quotas do ClickHouse.

Passo 3 — Monte a URL JDBC

O formato:

jdbc:clickhouse://<host>:<port>/<database>?ssl=true

Exemplos concretos:

  • ClickHouse Cloud: jdbc:clickhouse://my-service.us-east-1.aws.clickhouse.cloud:8443/default?ssl=true&sslMode=STRICT
  • Self-hosted com reverse-proxy HTTPS: jdbc:clickhouse://ch.yourcompany.com:443/analytics?ssl=true
  • Self-hosted plaintext (apenas rede privada): jdbc:clickhouse://ch.internal:8123/analytics. O IP de egress do Saiku Cloud precisa ser permitido na camada de rede; plaintext está OK DENTRO de uma rede confiável, mas não pela internet aberta.

Parâmetros chave:

  • ssl=true — habilita TLS. Obrigatório para ClickHouse Cloud + recomendado para qualquer implantação pública.
  • sslMode=STRICT — verifica que o cert do servidor cadeia até uma CA em que confiamos + verifica que o hostname bate. O ClickHouse Cloud usa Let’s Encrypt, então isso funciona de cara.
  • compress=true — compressão opt-in do lado do cliente (LZ4 por default). Reduz o tamanho do payload JDBC para grandes conjuntos de resultados; geralmente uma vitória para cargas de BI. O driver shaded clickhouse-jdbc-all empacota as libs nativas LZ4 + Brotli + Zstd.

Passo 4 — Conecte pelo wizard do Saiku Cloud

  1. Faça login em https://cloud.saiku.bi/.

  2. Vá em Conexões na barra lateral esquerda.

  3. Em 1. Escolha o tipo de data warehouse, clique no tile ClickHouse.

  4. Preencha:

    • URL JDBC — a URL do passo 3.
    • Usuário — saiku_read (ou o que tiver nomeado o usuário no passo 2).
    • Senha — a senha do passo 2.

  5. Clique em Testar conexão.

Um banner verde de resultado: ✓ Connection successful mais a versão detectada do ClickHouse → siga para o passo 5.

Um banner vermelho de resultado → veja Solução de problemas.

Passo 5 — Salve a conexão

Após um teste bem-sucedido, o wizard renderiza uma seção 3. Salvar conexão. Preencha:

  • Senha (digite de novo para salvar) — a mesma senha.
  • Rótulo — Production ClickHouse ou Analytics warehouse.

Clique em Salvar conexão.

Solução de problemas

✗ Connection failed (HOST_UNREACHABLE) ou (TIMEOUT)

  1. Porta errada — você usou 9000 (protocolo nativo) em vez de 8123 (HTTP) ou 8443 (HTTPS). A correção está no passo 3.
  2. Firewall / allowlist de IP — o passo 1 não foi aplicado. A “IP access list” do ClickHouse Cloud às vezes demora um minuto para propagar após salvar; tente de novo.
  3. DNS — nslookup <host> do seu laptop. Se resolve para um IP privado, o guarda anti-SSRF mostraria HOST_DENIED (não HOST_UNREACHABLE).

✗ Connection failed (AUTH_FAILED)

Erro ClickHouse 192 / 193 / 516. Usuário ou senha errados.

  • Sensibilidade a maiúsculas no usuário — nomes de usuário do ClickHouse são sensíveis a maiúsculas.
  • Hosts permitidos — seu usuário pode estar travado em IPs específicos via <allow_for_hosts> no users.xml. Adicione 87.99.153.244 a essa lista, ou remova a cláusula <allow_for_hosts> para permitir de qualquer lugar (e confiar no firewall).
  • plaintext_password vs sha256_password — ambos funcionam com nosso driver, mas se você descasou o tipo de hash armazenado do usuário com a senha fornecida, a checagem de hash no servidor falha. Geralmente só é problema ao migrar um usuário entre tipos de hash.

✗ Connection failed (DATABASE_NOT_FOUND)

Erro ClickHouse 81. O host aceita suas credenciais, mas o nome do banco na URL JDBC não existe. Verifique:

SHOW DATABASES;

✗ Connection failed (DIALECT_UNSUPPORTED)

A URL não começa com jdbc:clickhouse:. Se você colou uma URL jdbc:ch:, o resolvedor de dialeto bate isso como um scheme separado e aceita também — mas garanta que a URL em si comece com uma dessas duas.

Qualquer outra coisa

Tire um screenshot do wizard com o banner vermelho de resultado visível (especificamente a linha Kind: ...) e mande para support@saiku.bi.

Enterprise: rede privada

Para clientes Enterprise rodando uma configuração de rede privada, a regra do IP de egress é substituída por VPC peering. O fluxo do wizard de conexão é, fora isso, idêntico. Entre em contato com seu account team para provisionar o peering.

Teste com FoodMart

Quer testar o Saiku Cloud com esse dialeto antes de conectar seus próprios dados? Baixe o dataset de exemplo FoodMart empacotado para ClickHouse:

Dataset de exemplo FoodMart para ClickHouse