Pular para o conteúdo principal
O ClickHouse pode ser compilado em Linux, FreeBSD e macOS. Se você usa Windows, ainda pode compilar o ClickHouse em uma máquina virtual com Linux, por exemplo, VirtualBox com Ubuntu.

​
Crie um repositório no GitHub

Para começar a desenvolver para o ClickHouse, você precisará de uma conta no GitHub. Gere também uma chave SSH localmente (caso ainda não tenha uma) e envie a chave pública para o GitHub, pois isso é um pré-requisito para contribuir com patches. Em seguida, faça um fork do repositório do ClickHouse na sua conta pessoal clicando no botão “fork” no canto superior direito. Para contribuir com alterações, por exemplo, uma correção para um problema ou uma funcionalidade, primeiro faça commit das suas alterações em uma branch do seu fork e, em seguida, crie um “Pull Request” com essas alterações para o repositório principal. Para trabalhar com repositórios Git, instale o Git. Por exemplo, no Ubuntu, execute:
Uma folha de referência do Git pode ser encontrada aqui. Um manual detalhado do Git está disponível aqui.

​
Clone o repositório na sua máquina de desenvolvimento

Primeiro, baixe os arquivos-fonte para sua máquina de trabalho, ou seja, clone o repositório:
Este comando cria um diretório ClickHouse/ contendo o código-fonte, os testes e outros arquivos. Você pode especificar um diretório personalizado para o checkout após a URL, mas é importante que esse caminho não contenha espaços em branco, pois isso pode quebrar a build mais adiante. O repositório Git do ClickHouse usa submódulos para incluir bibliotecas de terceiros. Os submódulos não são incluídos no checkout por padrão. Você pode
  • executar git clone com a opção --recurse-submodules,
  • se git clone for executado sem --recurse-submodules, execute git submodule update --init --jobs <N> para fazer explicitamente o checkout de todos os submódulos. (<N> pode ser definido, por exemplo, como 12 para paralelizar o download.)
  • se git clone for executado sem --recurse-submodules e você quiser usar shallow checkout de submódulos para omitir o histórico nos submódulos e economizar espaço, execute ./contrib/update-submodules.sh. Essa alternativa é usada pela CI, mas não é recomendada para desenvolvimento local, pois torna o trabalho com submódulos menos prático e mais lento.
Para verificar o status dos submódulos do Git, execute git submodule status. Se você receber a seguinte mensagem de erro
as chaves SSH para se conectar ao GitHub estão faltando. Essas chaves normalmente ficam em ~/.ssh. Para que as chaves SSH sejam aceitas, você precisa adicioná-las nas configurações do GitHub. Você também pode clonar o repositório via HTTPS:
Isso, no entanto, não permitirá que você envie suas alterações para o servidor. Ainda assim, você pode usá-lo temporariamente e adicionar as chaves SSH depois, substituindo o endereço remoto do repositório com o comando git remote. Você também pode adicionar o endereço do repositório original do ClickHouse ao seu repositório local para obter atualizações de lá:
Depois de executar este comando com sucesso, você poderá puxar atualizações do repositório principal do ClickHouse executando git pull upstream master.
Não use apenas git push; você pode acabar enviando para o remoto errado e/ou para o branch errado. É melhor especificar explicitamente os nomes do remoto e do branch, por exemplo, git push origin my_branch_name.

​
Escrevendo código

Abaixo estão alguns links rápidos que podem ser úteis ao escrever código para o ClickHouse:

​
IDE

Visual Studio Code e Neovim são duas opções que já funcionaram bem para desenvolver o ClickHouse. Se você usa o VS Code, recomendamos a extensão clangd para substituir o IntelliSense, pois ela oferece desempenho muito superior. CLion é outra ótima alternativa. No entanto, ele pode ser mais lento em projetos maiores, como o ClickHouse. Alguns pontos a ter em mente ao usar o CLion:
  • O CLion cria um caminho build por conta própria e seleciona automaticamente debug como tipo de build
  • Ele usa uma versão do CMake definida no CLion, e não a que você instalou
  • O CLion usa make para executar tarefas de build em vez de ninja (isso é normal)
Outras IDEs que você pode usar são Sublime Text, Qt Creator ou Kate.

​
Crie um pull request

Acesse o repositório do seu fork na UI do GitHub. Se você estiver desenvolvendo em uma branch, precisará selecionar essa branch. Haverá um botão “Pull request” na tela. Em essência, isso significa “criar uma solicitação para que minhas alterações sejam aceitas no repositório principal”. Um pull request pode ser criado mesmo que o trabalho ainda não esteja concluído. Nesse caso, coloque a palavra “WIP” (trabalho em andamento) no início do título; ela poderá ser alterada depois. Isso é útil para revisão colaborativa e discussão das alterações, bem como para executar todos os testes disponíveis. É importante que você forneça uma breve descrição das suas alterações, pois ela será usada posteriormente para gerar o changelog da versão. Os testes começarão assim que os funcionários da ClickHouse adicionarem ao seu PR a tag “can be tested”. Os resultados de algumas verificações iniciais (por exemplo, estilo de código) chegarão em alguns minutos. Os resultados da verificação de builds chegarão em cerca de meia hora. O conjunto principal de testes apresentará resultados em até uma hora. O sistema preparará builds binárias do ClickHouse especificamente para o seu pull request. Para obter essas builds, clique no link “Details” ao lado da entrada “Builds” na lista de verificações. Lá você encontrará links diretos para os pacotes .deb gerados do ClickHouse, que pode instalar até mesmo nos seus servidores de produção (se não tiver medo).

​
Escreva a documentação

Todo pull request que adicionar um novo recurso deve vir acompanhado da documentação adequada. Se você quiser visualizar as alterações na documentação, as instruções de como gerar a página de documentação localmente estão disponíveis no arquivo README.md aqui. Ao adicionar uma nova função ao ClickHouse, você pode usar o modelo abaixo como guia:

​
Usando dados de teste

Ao desenvolver o ClickHouse, muitas vezes é necessário carregar conjuntos de dados realistas. Isso é particularmente importante para testes de desempenho. Temos um conjunto especialmente preparado de dados anonimizados de análise de tráfego da web. Isso requer cerca de 3 GB adicionais de espaço livre em disco.
No clickhouse-client:
Importe os dados:
Última modificação em 1 de julho de 2026