Bibliotecas de terceiros

Página que descreve o uso de bibliotecas de terceiros no ClickHouse e como adicionar e manter bibliotecas de terceiros.

O ClickHouse utiliza bibliotecas de terceiros para diferentes finalidades, por exemplo, para se conectar a outros bancos de dados, para decodificar/codificar dados durante o carregamento/salvamento em disco ou para implementar determinadas funções SQL especializadas. Para não depender das bibliotecas disponíveis no sistema de destino, cada biblioteca de terceiros é importada como um Git submodule para a árvore de código-fonte do ClickHouse e compilada e vinculada ao ClickHouse. Uma lista de bibliotecas de terceiros e suas licenças pode ser obtida com a seguinte consulta:

SELECT library_name, license_type, license_path FROM system.licenses ORDER BY library_name COLLATE 'en';

Observe que as bibliotecas listadas são as que estão localizadas no diretório contrib/ do repositório do ClickHouse. Dependendo das opções de compilação, algumas dessas bibliotecas podem não ter sido compiladas e, por isso, sua funcionalidade pode não estar disponível em tempo de execução.

Exemplo

​

Adicionando e mantendo bibliotecas de terceiros

Cada biblioteca de terceiros deve ficar em um diretório dedicado dentro do diretório contrib/ do repositório ClickHouse. Evite simplesmente copiar código externo para o diretório da biblioteca. Em vez disso, crie um Git submodule para obter código de terceiros de um repositório upstream externo.

Todos os submodules usados pelo ClickHouse estão listados no arquivo .gitmodule.

• Se a biblioteca puder ser usada como está (o caso padrão), você pode referenciar diretamente o repositório upstream.
• Se a biblioteca precisar de patches, crie um fork do repositório upstream na organização ClickHouse no GitHub.

Neste último caso, nosso objetivo é isolar ao máximo os patches personalizados dos commits do upstream. Para isso, crie uma branch com o prefixo ClickHouse/ a partir da branch ou tag que você deseja integrar, por exemplo, ClickHouse/2024_2 (para a branch 2024_2) ou ClickHouse/release/vX.Y.Z (para a tag release/vX.Y.Z). Evite acompanhar branches de desenvolvimento do upstream, como master/ main / dev (isto é, branches com prefixo ClickHouse/master / ClickHouse/main / ClickHouse/dev no fork). Essas branches são alvos móveis, o que dificulta um versionamento adequado. As “branches com prefixo” garantem que pulls do repositório upstream para o fork não afetem as branches personalizadas ClickHouse/. Os submodules em contrib/ devem rastrear apenas branches ClickHouse/ de repositórios de terceiros com fork.

Os patches são aplicados apenas sobre branches ClickHouse/ de bibliotecas externas.

Há duas maneiras de fazer isso:

• você quer criar uma nova correção em uma branch com prefixo ClickHouse/ no repositório com fork, por exemplo, uma correção de sanitizer. Nesse caso, envie a correção como uma branch com prefixo ClickHouse/, por exemplo, ClickHouse/fix-sanitizer-disaster. Depois, crie um PR da nova branch para a branch personalizada de rastreamento, por exemplo, ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster, e faça merge do PR.
• você atualiza o submodule e precisa reaplicar patches anteriores. Nesse caso, recriar PRs antigos é exagero. Em vez disso, simplesmente faça cherry-pick de commits antigos para a nova branch ClickHouse/ (correspondente à nova versão). Fique à vontade para squash dos commits de PRs que tinham vários commits. No melhor cenário, já contribuímos os patches personalizados de volta para o upstream e podemos omitir os patches na nova versão.

Depois que o submodule for atualizado, atualize o submodule no ClickHouse para apontar para o novo hash no fork.

Crie patches para bibliotecas de terceiros tendo em mente o repositório oficial e considere contribuir com o patch de volta para o repositório upstream. Isso garante que outras pessoas também se beneficiem do patch e que ele não se torne um ônus de manutenção para a equipe do ClickHouse.