Como Configurar o ClickHouse em uma VPS Ubuntu
O ClickHouse se tornou uma escolha comum sempre que uma equipe precisa consultar bilhões de linhas em menos de um segundo. É um banco de dados orientado a colunas, projetado para análise em vez de cargas transacionais, e roda tranquilamente em uma única VPS bem antes de exigir um cluster. Este guia percorre uma instalação limpa no Ubuntu, desde a primeira atualização do sistema até uma tabela funcional com consultas reais — a mesma configuração que usamos internamente ao criar ambientes de análise para clientes.
Vamos cobrir a terminologia necessária para acompanhar o processo, um breve olhar sobre como o ClickHouse processa dados na prática, alguns cenários em que ele se encaixa bem em uma stack e, por fim, a instalação em si, comando por comando. Ao final, você terá um servidor ClickHouse em execução, um banco de teste e contexto suficiente para decidir o que configurar em seguida.
Terminologia
Alguns termos aparecem repetidamente na documentação e nos arquivos de configuração do ClickHouse. Vale conhecê-los antes de abrir o terminal.
- OLAP (Online Analytical Processing) — cargas de trabalho dominadas por grandes consultas de leitura e agregações, ao contrário do OLTP, que lida com muitas transações pequenas de escrita.
- Armazenamento orientado a colunas — os dados são armazenados por coluna, não por linha. Consultas que tocam apenas algumas colunas de uma tabela larga leem muito menos dados do disco, o que explica boa parte da velocidade do ClickHouse.
- MergeTree — a família principal de mecanismos de tabela do ClickHouse. Os dados são gravados em pequenas partes e mesclados em segundo plano; praticamente toda tabela de produção usa alguma variante dele.
- ClickHouse Keeper — um serviço de coordenação embutido (uma alternativa ao ZooKeeper) usado para replicação e DDL distribuído em configurações com múltiplos nós. Não é necessário em uma instalação de servidor único, mas é bom saber caso haja planos de escalar depois.
- clickhouse-client — a ferramenta de linha de comando usada para se conectar a um servidor em execução e rodar SQL de forma interativa.
Como o ClickHouse Funciona
Em termos básicos, o ClickHouse roda como um processo de servidor (clickhouse-server) que aceita consultas por um protocolo TCP nativo na porta 9000 e por HTTP na porta 8123. Os clientes — o CLI, uma ferramenta de BI ou um driver de aplicação — se conectam a uma dessas portas e enviam SQL.
O que acontece depois que a consulta chega é onde o ClickHouse se diferencia de um banco relacional tradicional. Como os dados ficam armazenados por coluna, uma consulta que precisa de apenas três colunas de uma tabela com cinquenta lê apenas essas três do disco, ignorando o restante. Some isso a uma compactação agressiva e à execução vetorizada — em que o mecanismo processa lotes de valores de uma vez, em vez de linha por linha — e o resultado são consultas que levariam minutos em um banco tradicional retornando em um ou dois segundos.
As escritas funcionam de forma um pouco diferente das leituras. Cada INSERT cria uma nova parte de dados em disco. Em segundo plano, o ClickHouse mescla continuamente as partes menores em partes maiores — é justamente daí que vem o nome do mecanismo MergeTree. É também por isso que o ClickHouse prefere fortemente inserções em lote, grandes e pouco frequentes, em vez de milhares de inserções pequenas e individuais: cada inserção tem um custo real, e um número excessivo de partes pequenas pode deixar o processo de mesclagem visivelmente mais lento.
Aplicação Prática
O ClickHouse costuma aparecer em um conjunto específico de cenários, mais do que como banco de dados genérico:
- Dashboards em tempo real — alimentando painéis do Grafana ou Superset que precisam responder em menos de um segundo sobre conjuntos de dados grandes e em constante crescimento.
- Agregação de logs e eventos — ingerindo logs de aplicação, logs de acesso de servidores web ou eventos de segurança, muitas vezes alimentados por Vector, Fluent Bit ou um pipeline Kafka.
- Clickstream e analytics de produto — armazenando eventos brutos de usuários e rodando funis, análises de retenção e coortes diretamente em SQL, sob demanda.
- Dados de IoT e métricas — dados de série temporal com alta cardinalidade vindos de sensores ou monitoramento de infraestrutura, com volume alto de escrita e consultas que cobrem faixas amplas de tempo.
O que esses casos têm em comum é volume combinado com consultas analíticas — muitas escritas e leituras que percorrem ou agregam grandes fatias de dados, em vez de buscar uma única linha. Se a carga de trabalho se parece mais com "buscar o perfil de um usuário pelo ID", um banco relacional convencional ainda é a escolha melhor.
Guia Passo a Passo
1. Prepare a VPS
O ClickHouse roda em hardware modesto para testes, mas recompensa bem RAM e um disco rápido assim que cargas reais entram em cena. Para este guia, uma VPS com 2 vCPUs e 4 GB de RAM já é suficiente para acompanhar; para qualquer coisa além de experimentação, 8 GB de RAM e armazenamento em SSD fazem diferença real no desempenho de mesclagens e consultas. Se você precisa de uma VPS para isso, os planos de VPS da Serverspace cobrem bem essa faixa, com armazenamento NVMe disponível para cargas analíticas mais pesadas. Os passos abaixo assumem Ubuntu 22.04 ou 24.04 com acesso sudo.
2. Atualize o Sistema
Comece com uma atualização de rotina, para que o gerenciador de pacotes não trabalhe com listas de dependências desatualizadas.
sudo apt update && sudo apt upgrade -y3. Instale os Pacotes Pré-requisitos
O repositório de pacotes do ClickHouse é servido via HTTPS e assinado com uma chave GPG, então precisamos das ferramentas para lidar com os dois.
sudo apt install -y apt-transport-https ca-certificates curl gnupg4. Adicione a Chave GPG e o Repositório do ClickHouse
Por que não usar apt-key
Tutoriais mais antigos adicionam repositórios usando apt-key. Esse comando está descontinuado e, nas versões atuais do Ubuntu, ou não está mais disponível, ou é ativamente desaconselhado por questões de segurança. A abordagem atual armazena a chave em um arquivo de keyring dedicado e faz referência explícita a ele na definição do repositório — um pouco mais de digitação, mas bem mais seguro.
curl -fsSL 'https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg
ARCH=$(dpkg --print-architecture)
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg arch=${ARCH}] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
5. Instale o Servidor e o Cliente ClickHouse
Com o repositório registrado, atualize a lista de pacotes e instale os dois pacotes juntos — o cliente é o que você vai usar para rodar consultas interativamente.
sudo apt update
sudo apt install -y clickhouse-server clickhouse-client
Durante a instalação, o apt vai pedir que você defina uma senha para o usuário chamado default — esse é o login da conta administrativa embutida do ClickHouse, não um segundo usuário "padrão". Defina uma senha agora: deixar em branco funciona para um teste local rápido, mas não é algo para levar adiante em qualquer coisa acessível pela internet.
6. Inicie e Habilite o Serviço
O ClickHouse roda sob o systemd, então iniciar e habilitar segue o padrão de sempre.
sudo systemctl enable clickhouse-server
sudo systemctl start clickhouse-server
sudo systemctl status clickhouse-server
Um status saudável mostra active (running). Se não mostrar, verifique /var/log/clickhouse-server/clickhouse-server.log antes de continuar — a maioria dos problemas na primeira execução vem de uma porta já em uso ou de permissão no diretório de dados.
7. Teste a Conexão
Conecte-se com o cliente CLI usando a senha definida na instalação.
clickhouse-client --passwordUma conexão bem-sucedida leva você a um prompt como este:
my-server :) SELECT version();que retorna a versão instalada do ClickHouse e confirma que o servidor está realmente ouvindo e autenticando corretamente, não apenas em execução.
8. Crie um Banco de Dados e uma Tabela de Teste
Com a conexão ativa, crie um banco de dados e uma tabela MergeTree para confirmar que escritas e leituras se comportam como esperado.
CREATE DATABASE analytics;
CREATE TABLE analytics.events
(
event_date Date,
event_time DateTime,
user_id UInt32,
event_type String,
value Float64
)
ENGINE = MergeTree()
ORDER BY (event_date, user_id);
INSERT INTO analytics.events VALUES
('2026-08-20', '2026-08-20 09:15:00', 101, 'click', 1.0),
('2026-08-20', '2026-08-20 09:16:30', 102, 'purchase', 49.90);
SELECT event_type, count() AS total, sum(value) AS revenue
FROM analytics.events
GROUP BY event_type;
A cláusula ORDER BY aqui funciona também como a chave primária da tabela no MergeTree — ela define como os dados ficam fisicamente ordenados em disco, o que afeta diretamente a velocidade de consultas por faixa e por filtro mais adiante.
9. Configure Acesso Remoto (Opcional)
Por padrão, o ClickHouse escuta apenas em localhost. Se uma ferramenta de BI ou outro servidor precisar se conectar remotamente, abra o arquivo de configuração principal e ajuste o endereço de escuta.
sudo nano /etc/clickhouse-server/config.xmlEncontre a configuração <listen_host> e adicione 0.0.0.0 (ou um IP de interface específico) para permitir conexões externas, depois reinicie o serviço:
sudo systemctl restart clickhouse-server10. Reforço Básico de Segurança
Um banco de dados analítico exposto sem restrições em um IP público é um risco, não uma comodidade. Alguns passos fazem bastante diferença aqui.
| Porta | Finalidade | Expor publicamente? |
|---|---|---|
| 8123 | Interface HTTP | Somente se necessário, com autenticação |
| 9000 | Protocolo TCP nativo (clickhouse-client) | Não — restrinja a IPs confiáveis |
| 9440 | TCP nativo sobre TLS | Preferível à porta 9000 para acesso remoto |
Na prática, isso significa:
- Restringir o acesso com ufw ou o firewall do seu provedor, para que apenas IPs confiáveis alcancem as portas 8123 e 9000/9440.
- Criar um usuário dedicado com privilégios limitados para aplicações, em vez de usar o default para tudo:
CREATE USER analytics_app IDENTIFIED WITH sha256_password BY 'uma-senha-forte-aqui';
GRANT SELECT, INSERT ON analytics.* TO analytics_app;
- Se o servidor for acessível de fora da sua rede, habilite TLS na porta 9440 em vez de expor a porta 9000 sem criptografia.
- Mantenha o pacote atualizado — sudo apt update && sudo apt upgrade clickhouse-server clickhouse-client — já que o projeto lança correções de segurança com regularidade.
Conclusão
Neste ponto, você tem um servidor ClickHouse em execução, uma tabela de teste com consultas reais e uma noção básica de como o mecanismo de armazenamento e as portas de rede se encaixam. Para uma única VPS rodando experimentos ou uma carga analítica pequena, essa configuração já é utilizável como está. Quando o volume de consultas ou de dados crescer, os próximos passos naturais são ajustar as configurações do MergeTree para os padrões de consulta específicos, configurar backups agendados e — se um único nó deixar de ser suficiente — considerar o ClickHouse Keeper para replicação entre múltiplos servidores. Nada disso exige recomeçar do zero; tudo se constrói diretamente sobre o que foi instalado aqui.
