O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar um conector de origem genérico do PostgreSQL

Este documento descreve como criar um conector de origem genérica do PostgreSQL.

Um conector de origem genérica do PostgreSQL é uma instância de um conector do PostgreSQL do Debezium. Ele lê as mudanças no nível da linha de um banco de dados do PostgreSQL e as grava em tópicos em um cluster do Serviço Gerenciado para Apache Kafka.

Os casos de uso desse conector incluem:

Monitorar as mudanças no nível da linha do banco de dados em tempo real.
Integrar eventos de mudança de banco de dados em uma arquitetura orientada a eventos.
Responder a eventos de banco de dados, como inserções ou exclusões de linhas.
Copiar mudanças de banco de dados para outros sistemas.
Replicar ou restaurar tabelas do PostgreSQL.

Antes de começar

Antes de criar um conector de origem genérica do PostgreSQL, verifique se você tem o seguinte:

Um banco de dados do PostgreSQL.
Um cluster do Connect associado ao cluster do Kafka.
Crie um secret do Secret Manager que armazene a senha do banco de dados. Se a configuração usar SSL do banco de dados, crie também um secret para a senha SSL do banco de dados. Configure o cluster do Connect com os secrets. Para mais informações, consulte Recursos do Secret Manager.

Observação: senhas de texto simples não são aceitas. Somente caminhos de secret são aceitos nas configurações database.password e database.sslpassword. O back-end espera que essas configurações usem o seguinte formato: ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

Papéis e permissões necessárias

Para ter as permissões necessárias para criar um conector, peça ao administrador para conceder a você o papel do IAM de editor de conectores do Kafka gerenciado (roles/managedkafka.connectorEditor) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para criar um conector. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para criar um conector:

Criar um conector: managedkafka.connectors.create

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Conceder permissões para acessar secrets do Secret Manager

A conta de serviço do Kafka gerenciado precisa de permissão para visualizar e acessar os secrets armazenados no Secret Manager. Conceda os seguintes papéis do IAM à conta de serviço:

Visualizador do Secret Manager (roles/secretmanager.viewer)
Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor)

A conta de serviço do Kafka gerenciado tem o seguinte formato: service-PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com, em que PROJECT_NUMBER é o número do projeto do cluster do Connect.

Se o cluster do Connect estiver em um projeto diferente do cluster do Serviço Gerenciado para Apache Kafka cluster, consulte Criar um cluster do Connect em um projeto diferente.

Configure o banco de dados do PostgreSQL

Para permitir que o conector leia eventos de mudança de dados do seu banco de dados, configure as seguintes configurações.

Defina o wal_level do servidor como logical.
```
ALTER SYSTEM SET wal_level = logical;
```
Reinicie o servidor para aplicar a configuração.
Crie um usuário do banco de dados para que o conector faça a autenticação no PostgreSQL. O usuário do banco de dados precisa ser um papel de replicação, permitindo que ele se conecte ao servidor no modo de replicação.
```
CREATE ROLE ROLE_NAME WITH REPLICATION LOGIN PASSWORD 'ROLE_PASSWORD';
```
Substitua:
- ROLE_NAME: o nome do usuário, por exemplo, debezium_user.
- ROLE_PASSWORD: a senha do usuário.
Crie uma publicação para as tabelas que você quer capturar. O conector se inscreve na publicação para receber eventos de mudança de dados.
```
CREATE PUBLICATION dbz_publication FOR TABLE "SCHEMA_NAME"."TABLE_NAME";
```
Substitua:
- SCHEMA_NAME: o esquema da tabela.
- TABLE_NAME: o nome da tabela.
Recomendamos incluir o esquema e os nomes das tabelas entre aspas duplas, conforme mostrado, para evitar erros de sintaxe se os nomes contiverem caracteres especiais ou letras maiúsculas.

Como alternativa, você pode criar uma publicação que replique as mudanças de todas as tabelas no banco de dados:
```
CREATE PUBLICATION dbz_publication FOR ALL TABLES;
```
Dependendo da configuração publication.autocreate.mode do conector, você pode criar a publicação manualmente ou permitir que o conector a crie automaticamente. Para mais informações, consulte Modo de publicação.
Para cada tabela, conceda privilégios SELECT na tabela ao usuário do banco de dados.
```
GRANT SELECT ON TABLE "SCHEMA_NAME"."TABLE_NAME" TO ROLE_NAME;
```
Como alternativa, você pode conceder a seleção em todas as tabelas de um esquema:
```
GRANT SELECT ON ALL TABLES IN SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```
Para cada tabela, conceda privilégios USAGE no esquema da tabela ao usuário do banco de dados. Você pode pular esta etapa se a tabela estiver no esquema public padrão.
```
GRANT USAGE ON SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```

Criar um conector de origem genérica do PostgreSQL

Para criar um conector de origem genérica do PostgreSQL, siga estas etapas.

Quando o conector é inicializado, ele realiza as seguintes ações:

Cria um snapshot inicial do banco de dados.
Cria um tópico do Kafka para cada tabela que tem linhas.
Para cada linha do banco de dados, envia um evento de mudança para o tópico correspondente.

Enquanto o conector está em execução, ele continua enviando eventos de mudança para os tópicos. Para mais informações sobre o snapshot inicial, consulte Snapshots na documentação do Debezium.

Console

No Google Cloud console, acesse a página Clusters do Connect.

Acessar clusters do Connect
Clique no cluster do Connect em que você quer criar o conector.
Clique em Criar conector.
Para o nome do conector, insira uma string.

Para conferir as diretrizes de nomeação de um conector, consulte Diretrizes de nomeação de um recurso do Serviço Gerenciado para Apache Kafka.
Em Plug-in do conector, selecione Origem genérica do PostgreSQL.
No campo Nome do host do banco de dados, insira o nome do host ou o endereço IP do servidor PostgreSQL.
No campo Nome do banco de dados, insira o nome do banco de dados.
No campo Usuário do banco de dados, insira o nome do papel da réplica. O conector faz a autenticação no servidor PostgreSQL usando esse papel.
No campo Prefixo do tópico, insira um prefixo a ser usado para os nomes dos tópicos do Kafka.
Na lista Secret, selecione o secret que contém a senha do banco de dados.
Opcional: na caixa Configurações, adicione propriedades de configuração ou edite as propriedades padrão. Para mais informações, consulte Configurar o conector.
Opcional: selecione a Política de reinicialização da tarefa. Para mais informações, consulte Política de reinicialização da tarefa.
Clique em Criar.

gcloud

No Google Cloud console, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do Google Cloud console, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Execute o gcloud managed-kafka connectors create comando:
```
gcloud managed-kafka connectors create CONNECTOR_ID \
    --location=LOCATION \
    --connect-cluster=CONNECT_CLUSTER_ID \
    --config-file=CONFIG_FILE
```
Substitua:
- CONNECTOR_ID: o ID ou nome do conector. Para conferir as diretrizes de nomeação de um conector, consulte Diretrizes de nomeação de um recurso do Serviço Gerenciado para Apache Kafka. O nome de um conector é imutável.
- LOCATION: o local em que você cria o conector. Precisa ser o mesmo local em que você criou o cluster do Connect.
- CONNECT_CLUSTER_ID: o ID do cluster do Connect em que o conector é criado.
- CONFIG_FILE: o caminho para o arquivo de configuração YAML do conector.
Confira um exemplo de arquivo de configuração para o conector de origem genérica do PostgreSQL:
```
connector.class: io.debezium.connector.postgresql.PostgresConnector
database.dbname: DATABASE_NAME
database.hostname: HOSTNAME
database.password: CREDENTIALS
database.user: DATABASE_USER
key.converter: org.apache.kafka.connect.json.JsonConverter
key.converter.schemas.enable: "false"
plugin.name: pgoutput
topic.prefix: TOPIC_PREFIX
value.converter: org.apache.kafka.connect.json.JsonConverter
value.converter.schemas.enable: "true"
```
Substitua:
- HOSTNAME: o nome do host do banco de dados do PostgreSQL a ser lido.
- DATABASE_NAME: o nome do banco de dados do PostgreSQL a ser lido.
- DATABASE_USER: o usuário do banco de dados do PostgreSQL a ser usado ao fazer a autenticação no banco de dados.
- CREDENTIALS: um caminho para o secret do Secret Manager que contém a senha do banco de dados. Especifique o secret usando o seguinte formato:
```
${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}
```
- TOPIC_PREFIX: um prefixo a ser usado para os nomes dos tópicos do Kafka.

Configurar o conector

Esta seção descreve algumas propriedades de configuração que podem ser definidas no conector. Para uma lista completa, consulte Conector do Debezium para PostgreSQL na documentação do Debezium.

Configurações de senha e senha SSL

Somente caminhos de secret são aceitos nas configurações database.password e database.sslpassword. O back-end espera que essas configurações usem o seguinte formato: ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

Tipos de endereço IP

A propriedade driver.ipTypes especifica o tipo de endereço IP que o conector usa para se conectar ao banco de dados:

PRIVATE: IP particular
PSC: Private Service Connect
PUBLIC: IP público

A propriedade driver.ipTypes contém uma lista separada por vírgulas de tipos de IP na ordem preferencial . Por exemplo, driver.ipTypes=PRIVATE,PUBLIC.

Modo de publicação

Um conector de origem genérica do PostgreSQL transmite eventos de mudança de uma publicação no banco de dados. Você pode criar a publicação manualmente ou permitir que o conector a crie automaticamente.

A publication.autocreate.mode configuração especifica como e se o conector deve criar uma publicação.

filtered. Se a publicação não existir, o conector vai criar uma nova publicação que inclua apenas as tabelas capturadas. O usuário do banco de dados precisa ter permissões CREATE no banco de dados e ser o proprietário das tabelas incluídas.

Se a publicação já existir, o conector vai alterá-la para incluir as tabelas capturadas. Para alterar uma publicação atual, o usuário do banco de dados precisa ser o proprietário da publicação e das tabelas incluídas.
all_tables. Se a publicação não existir, o conector vai criar uma nova publicação usando o parâmetro FOR ALL TABLES. O usuário do banco de dados precisa ser um superusuário.

Os papéis de superusuário ignoram todas as verificações de permissão em um banco de dados. Portanto, não é recomendável conceder SUPERUSER ao usuário do banco de dados. Em vez disso, crie a publicação manualmente ou defina publication.autocreate.mode=filtered.
disabled. Se a publicação não existir, ocorrerá um erro. O conector não cria uma nova publicação.

O valor padrão é all_tables.

Nome da publicação

Por padrão, o conector tenta transmitir de uma publicação chamada dbz_publication. Para especificar uma publicação diferente, adicione publication.name=PUBLICATION_NAME à configuração, onde PUBLICATION_NAME é o nome da publicação. Exemplo: publication.name=my_publication.

Slots de replicação

O PostgreSQL usa slots de replicação para transmitir mudanças na tabela do banco de dados. Por padrão, o conector cria um slot de replicação chamado debezium. Para usar um nome de slot diferente, defina a propriedade slot.name.

Se você criar duas instâncias do conector para o mesmo banco de dados, especifique um nome de slot exclusivo para cada conector.

Por padrão, o conector define a slot.drop.on.stop propriedade como false para evitar a perda de dados. Ao excluir permanentemente um conector, é necessário descartar manualmente o slot de replicação que o conector estava usando. O nome do slot de replicação é debezium por padrão, a menos que seja configurado de maneira diferente usando a slot.name propriedade.

Recomendamos configurar alertas para monitorar o uso do disco WAL no servidor de banco de dados PostgreSQL de origem e descartar todos os slots de replicação não utilizados.

Filtro da tabela

Por padrão, o conector captura dados de mudança de todas as tabelas não relacionadas ao sistema no banco de dados. Para filtrar quais tabelas são capturadas, especifique uma ou mais das seguintes configurações:

schema.include.list. Uma lista de esquemas a serem incluídos.
schema.exclude.list. Uma lista de esquemas a serem excluídos. Não pode ser usado com schema.include.list.
table.include.list. Uma lista de tabelas a serem incluídas.
table.exclude.list. Uma lista de tabelas a serem excluídas. Não pode ser usado com table.include.list.

Nomes de tópicos

Por padrão, o conector cria tópicos do Kafka com a seguinte convenção de nomenclatura: topic_prefix.schema.table_name, em que topic.prefix é o valor da configuração topic.prefix.

Para mais informações, consulte Nomes de tópicos na documentação do Debezium.