JDBC Connector - ClickHouse Documentation

Este conector JDBC só deve ser usado se os seus dados forem simples e consistirem em tipos de dados primitivos, como int. Tipos específicos do ClickHouse, como maps, não são compatíveis.

Nos exemplos, usamos a distribuição Confluent do Kafka Connect. A seguir, descrevemos uma instalação simples, extraindo mensagens de um único tópico do Kafka e inserindo linhas em uma tabela do ClickHouse. Recomendamos o Confluent Cloud, que oferece um nível gratuito generoso para quem não tem um ambiente Kafka. Observe que um esquema é necessário para o JDBC Connector (não é possível usar JSON ou CSV simples com o conector JDBC). Embora o esquema possa ser codificado em cada mensagem, é altamente recomendável usar o registro de esquemas do Confluent para evitar a sobrecarga associada. O script de inserção fornecido infere automaticamente um esquema a partir das mensagens e o insere no registry; assim, esse script também pode ser reutilizado para outros datasets. Pressupõe-se que as keys do Kafka sejam Strings. Mais detalhes sobre esquemas do Kafka podem ser encontrados aqui.

Licença

O JDBC Connector é distribuído sob a Licença Comunitária da Confluent

Etapas

Reúna as informações da conexão

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.

1. Instale o Kafka Connect e o conector

Pressupomos que você já tenha baixado o pacote Confluent e feito a instalação local. Siga as instruções de instalação do conector, conforme documentado aqui. Se você usar o método de instalação confluent-hub, seus arquivos de configuração locais serão atualizados. Para enviar dados do Kafka para o ClickHouse, usamos o componente sink do conector.

2. Baixe e instale o driver JDBC

Baixe e instale o JDBC driver do ClickHouse clickhouse-jdbc-<version>-shaded.jar aqui. Instale-o no Kafka Connect seguindo as instruções aqui. Outros drivers podem funcionar, mas não foram testados.

Problema comum: a documentação sugere copiar o arquivo jar para share/java/kafka-connect-jdbc/. Se você tiver problemas para o Connect localizar o driver, copie-o para share/confluent-hub-components/confluentinc-kafka-connect-jdbc/lib/. Como alternativa, modifique plugin.path para incluir o driver — veja abaixo.

3. Prepare a configuração

Siga estas instruções para configurar uma instância do Connect adequada ao seu tipo de instalação, observando as diferenças entre um cluster standalone e um distribuído. Se estiver usando o Confluent Cloud, a configuração distribuída é a mais apropriada. Os parâmetros a seguir são relevantes para usar o conector JDBC com o ClickHouse. Uma lista completa de parâmetros pode ser encontrada aqui:

_connection.url_ - deve ter o formato jdbc:clickhouse://<clickhouse host>:<clickhouse http port>/<target database>
connection.user - um usuário com acesso de gravação ao banco de dados de destino
table.name.format- tabela do ClickHouse na qual inserir os dados. Ela deve existir.
batch.size - O número de linhas a serem enviadas em um único batch. Certifique-se de definir um valor adequadamente alto. De acordo com as recomendações do ClickHouse, o valor mínimo deve ser 1000.
tasks.max - O conector JDBC Sink oferece suporte à execução de uma ou mais tasks. Isso pode ser usado para aumentar o desempenho. Junto com o tamanho do batch, esse é o principal meio de melhorar o desempenho.
value.converter.schemas.enable - Defina como false se estiver usando um registro de esquemas, true se estiver incorporando os esquemas nas mensagens.
value.converter - Defina de acordo com o tipo de dado; por exemplo, para JSON, io.confluent.connect.json.JsonSchemaConverter.
key.converter - Defina como org.apache.kafka.connect.storage.StringConverter. Utilizamos chaves String.
pk.mode - Não é relevante para o ClickHouse. Defina como none.
auto.create - Não é compatível e deve ser false.
auto.evolve - Recomendamos false para essa configuração, embora ela possa vir a ser compatível no futuro.
insert.mode - Defina como “insert”. Outros modos não são compatíveis no momento.
key.converter - Defina de acordo com os tipos das suas chaves.
value.converter - Defina com base no tipo de dados no seu topic. Esses dados devem ter um esquema compatível: formatos JSON, Avro ou Protobuf.

Se estiver usando nosso dataset de exemplo para testes, certifique-se de definir o seguinte:

value.converter.schemas.enable - Defina como false, pois utilizamos um registro de esquemas. Defina como true se estiver incorporando o esquema em cada mensagem.
key.converter - Defina como “org.apache.kafka.connect.storage.StringConverter”. Utilizamos chaves String.
value.converter - Defina como “io.confluent.connect.json.JsonSchemaConverter”.
value.converter.schema.registry.url - Defina a URL do servidor de esquema, junto com as credenciais do servidor de esquema, por meio do parâmetro value.converter.schema.registry.basic.auth.user.info.

Arquivos de configuração de exemplo para os dados de amostra do GitHub podem ser encontrados aqui, considerando que o Connect está sendo executado no modo standalone e que o Kafka está hospedado no Confluent Cloud.

4. Crie a tabela do ClickHouse

Certifique-se de que a tabela tenha sido criada, removendo-a caso já exista de exemplos anteriores. Abaixo, é mostrado um exemplo compatível com o conjunto de dados reduzido do GitHub. Observe a ausência de tipos Array ou Map, que ainda não são compatíveis no momento:

CREATE TABLE github
(
    file_time DateTime,
    event_type Enum('CommitCommentEvent' = 1, 'CreateEvent' = 2, 'DeleteEvent' = 3, 'ForkEvent' = 4, 'GollumEvent' = 5, 'IssueCommentEvent' = 6, 'IssuesEvent' = 7, 'MemberEvent' = 8, 'PublicEvent' = 9, 'PullRequestEvent' = 10, 'PullRequestReviewCommentEvent' = 11, 'PushEvent' = 12, 'ReleaseEvent' = 13, 'SponsorshipEvent' = 14, 'WatchEvent' = 15, 'GistEvent' = 16, 'FollowEvent' = 17, 'DownloadEvent' = 18, 'PullRequestReviewEvent' = 19, 'ForkApplyEvent' = 20, 'Event' = 21, 'TeamAddEvent' = 22),
    actor_login LowCardinality(String),
    repo_name LowCardinality(String),
    created_at DateTime,
    updated_at DateTime,
    action Enum('none' = 0, 'created' = 1, 'added' = 2, 'edited' = 3, 'deleted' = 4, 'opened' = 5, 'closed' = 6, 'reopened' = 7, 'assigned' = 8, 'unassigned' = 9, 'labeled' = 10, 'unlabeled' = 11, 'review_requested' = 12, 'review_request_removed' = 13, 'synchronize' = 14, 'started' = 15, 'published' = 16, 'update' = 17, 'create' = 18, 'fork' = 19, 'merged' = 20),
    comment_id UInt64,
    path String,
    ref LowCardinality(String),
    ref_type Enum('none' = 0, 'branch' = 1, 'tag' = 2, 'repository' = 3, 'unknown' = 4),
    creator_user_login LowCardinality(String),
    number UInt32,
    title String,
    state Enum('none' = 0, 'open' = 1, 'closed' = 2),
    assignee LowCardinality(String),
    closed_at DateTime,
    merged_at DateTime,
    merge_commit_sha String,
    merged_by LowCardinality(String),
    review_comments UInt32,
    member_login LowCardinality(String)
) ENGINE = MergeTree ORDER BY (event_type, repo_name, created_at)

5. Inicie o Kafka Connect

Inicie o Kafka Connect no modo standalone ou distribuído.

./bin/connect-standalone connect.properties.ini github-jdbc-sink.properties.ini

6. Adicione dados ao Kafka

Insira mensagens no Kafka usando o script e a configuração fornecidos. Você precisará modificar o github.config para incluir suas credenciais do Kafka. No momento, o script está configurado para uso com o Confluent Cloud.

python producer.py -c github.config

Este script pode ser usado para inserir qualquer arquivo ndjson em um tópico do Kafka. Ele tentará inferir automaticamente um esquema para você. A configuração de exemplo fornecida inserirá apenas 10 mil mensagens - modifique aqui se necessário. Essa configuração também remove quaisquer campos Array incompatíveis do dataset durante a inserção no Kafka. Isso é necessário para que o conector JDBC converta as mensagens em instruções INSERT. Se você estiver usando seus próprios dados, certifique-se de inserir um esquema em cada mensagem (definindo _value.converter.schemas.enable _como true) ou garanta que seu cliente publique mensagens que façam referência a um esquema no registry. O Kafka Connect deve começar a consumir mensagens e inserir linhas no ClickHouse. Observe que os avisos sobre “[JDBC Compliant Mode] Transaction isn’t supported.” são esperados e podem ser ignorados. Uma consulta simples à tabela de destino “Github” deve confirmar a inserção dos dados.

SELECT count() FROM default.github;

| count\(\) |
| :--- |
| 10000 |

​Licença

​Etapas

​Reúna as informações da conexão

​1. Instale o Kafka Connect e o conector

​2. Baixe e instale o driver JDBC

​3. Prepare a configuração

​4. Crie a tabela do ClickHouse

​5. Inicie o Kafka Connect

​6. Adicione dados ao Kafka

​Leitura complementar recomendada

Licença

Etapas

Reúna as informações da conexão

1. Instale o Kafka Connect e o conector

2. Baixe e instale o driver JDBC

3. Prepare a configuração

4. Crie a tabela do ClickHouse

5. Inicie o Kafka Connect

6. Adicione dados ao Kafka

Leitura complementar recomendada