Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Crea un conector de fuente de PostgreSQL genérico

Un conector de fuente de PostgreSQL genérica te permite capturar cambios a nivel de fila de una base de datos de PostgreSQL y transmitirlos a temas en un clúster de Managed Service para Apache Kafka.

Entre los casos de uso típicos de este conector, se incluyen los siguientes:

Supervisa los cambios en la base de datos a nivel de fila en tiempo real.
Integrar eventos de cambio de base de datos en una arquitectura controlada por eventos
Responder a eventos de la base de datos, como inserciones o eliminaciones de filas
Copia los cambios de la base de datos en otros sistemas.
Replica o restablece tablas de PostgreSQL.

Para leer los cambios de una base de datos de Cloud SQL para PostgreSQL, usa el conector de origen de Cloud SQL para PostgreSQL.

Antes de comenzar

Antes de crear un conector de fuente de PostgreSQL genérico, asegúrate de tener lo siguiente:

Una base de datos de PostgreSQL.
Un clúster de Connect asociado con el clúster de Kafka.
Crea un secreto de Secret Manager que almacene la contraseña de la base de datos. Si tu configuración usa SSL de base de datos, también crea un Secret para la contraseña de SSL de la base de datos. Configura tu clúster de Connect con los secrets. Para obtener más información, consulta Recursos de Secret Manager.

Nota: No se admiten las contraseñas de texto simple. Solo se admiten rutas de acceso de Secrets en los parámetros de configuración database.password y database.sslpassword. El backend espera que estos parámetros de configuración usen el siguiente formato: ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

Roles y permisos requeridos

Para obtener los permisos que necesitas para crear un conector, pídele a tu administrador que te otorgue el rol de IAM de editor de conectores de Kafka administrados (roles/managedkafka.connectorEditor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear un conector. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear un conector:

Crea un conector: managedkafka.connectors.create

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Otorga permisos para acceder a los secretos de Secret Manager

La cuenta de servicio de Kafka administrada necesita permiso para ver y acceder a los secretos almacenados en Secret Manager. Otorga las siguientes funciones de IAM a la cuenta de servicio:

Visualizador de Secret Manager (roles/secretmanager.viewer)
Descriptor de acceso de secretos de Secret Manager (roles/secretmanager.secretAccessor)

La cuenta de servicio de Kafka administrado tiene el siguiente formato: service-PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com, en el que PROJECT_NUMBER es el número de proyecto del clúster de Connect.

Si tu clúster de Connect está en un proyecto diferente al de tu clúster de Managed Service para Apache Kafka, consulta Crea un clúster de Connect en un proyecto diferente.

Configura tu base de datos de PostgreSQL

Para permitir que el conector lea los eventos de cambio de datos de tu base de datos, establece los siguientes parámetros de configuración.

Establece el wal_level del servidor en logical.
```
ALTER SYSTEM SET wal_level = logical;
```
Reinicia el servidor para aplicar el parámetro de configuración.
Crea un usuario de base de datos para que el conector se autentique en PostgreSQL. El usuario de la base de datos debe tener un rol de replicación, lo que le permite conectarse al servidor en modo de replicación.
```
CREATE ROLE ROLE_NAME WITH REPLICATION LOGIN PASSWORD 'ROLE_PASSWORD';
```
Reemplaza lo siguiente:
- ROLE_NAME: Es el nombre del usuario, por ejemplo, debezium_user.
- ROLE_PASSWORD: Es la contraseña del usuario.
Crea una publicación para las tablas que deseas capturar. El conector se suscribe a la publicación para recibir eventos de cambio de datos.
```
CREATE PUBLICATION dbz_publication FOR TABLE "SCHEMA_NAME"."TABLE_NAME";
```
Reemplaza lo siguiente:
- SCHEMA_NAME: Es el esquema de la tabla.
- TABLE_NAME: el nombre de la tabla.
Te recomendamos que encierres los nombres de los esquemas y las tablas entre comillas dobles, como se muestra, para evitar errores de sintaxis si los nombres contienen caracteres especiales o letras mayúsculas.

Como alternativa, puedes crear una publicación que replique los cambios de todas las tablas de la base de datos:
```
CREATE PUBLICATION dbz_publication FOR ALL TABLES;
```
Según el parámetro de configuración publication.autocreate.mode del conector, puedes crear la publicación de forma manual o permitir que el conector la cree automáticamente. Para obtener más información, consulta Modo de publicación.
Para cada tabla, otorga privilegios SELECT en la tabla al usuario de la base de datos.
```
GRANT SELECT ON TABLE "SCHEMA_NAME"."TABLE_NAME" TO ROLE_NAME;
```
Como alternativa, puedes otorgar el permiso SELECT en todas las tablas de un esquema:
```
GRANT SELECT ON ALL TABLES IN SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```
Para cada tabla, otorga privilegios USAGE en el esquema de la tabla al usuario de la base de datos. Puedes omitir este paso si la tabla está en el esquema predeterminado public.
```
GRANT USAGE ON SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```

Crea un conector de origen de PostgreSQL genérico

Para crear un conector de fuente de PostgreSQL genérico, sigue estos pasos.

Cuando se inicializa el conector, realiza las siguientes acciones:

Crea una instantánea inicial de la base de datos.
Crea un tema de Kafka para cada tabla que tenga filas.
Para cada fila de la base de datos, envía un evento de cambio al tema correspondiente.

Mientras se ejecuta el conector, sigue enviando eventos de cambio a los temas. Para obtener más información sobre la instantánea inicial, consulta Instantáneas en la documentación de Debezium.

Console

En la consola de Google Cloud , ve a la página Conectar clústeres.

Ir a Conectar clústeres
Haz clic en el clúster de Connect en el que deseas crear el conector.
Haz clic en Crear conector.
Para el nombre del conector, ingresa una cadena.

Si necesitas ayuda para asignarle un nombre a un conector, consulta los Lineamientos para asignarles nombres a los recursos de Managed Service para Apache Kafka.
En Complemento del conector, selecciona Fuente de PostgreSQL genérica.
En el campo Nombre de host de la base de datos, ingresa el nombre de host o la dirección IP del servidor de PostgreSQL.
En el campo Nombre de la base de datos, ingresa el nombre de la base de datos.
En el campo Usuario de la base de datos, ingresa el nombre del rol de réplica. El conector se autentica en el servidor de PostgreSQL con este rol.
En el campo Prefijo del tema, ingresa un prefijo para usar en los nombres de los temas de Kafka.
En la lista Secret, selecciona el Secret que contiene la contraseña de la base de datos.
Opcional: En el cuadro Configuraciones, agrega propiedades de configuración o edita las propiedades predeterminadas. Para obtener más información, consulta Configura el conector.
Opcional: Selecciona la Política de reinicio de tareas. Para obtener más información, consulta Política de reinicio de tareas.
Haz clic en Crear.

gcloud

En la consola de Google Cloud , activa Cloud Shell.

Activa Cloud Shell

En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.
Ejecuta el comando gcloud managed-kafka connectors create:
```
gcloud managed-kafka connectors create CONNECTOR_ID \
    --location=LOCATION \
    --connect-cluster=CONNECT_CLUSTER_ID \
    --config-file=CONFIG_FILE
```
Reemplaza lo siguiente:
- CONNECTOR_ID: Es el ID o el nombre del conector. Si necesitas ayuda para asignarle un nombre a un conector, consulta los Lineamientos para asignarles nombres a los recursos de Managed Service para Apache Kafka. El nombre de un conector es inmutable.
- LOCATION: Es la ubicación en la que creas el conector. Debe ser la misma ubicación en la que creaste el clúster de Connect.
- CONNECT_CLUSTER_ID: Es el ID del clúster de Connect en el que se crea el conector.
- CONFIG_FILE: Es la ruta de acceso al archivo de configuración YAML del conector.
Este es un ejemplo de un archivo de configuración para el conector de origen de PostgreSQL genérico:
```
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"
```
Reemplaza lo siguiente:
- HOSTNAME: Es el nombre de host de la base de datos de PostgreSQL desde la que se leerá.
- DATABASE_NAME: Es el nombre de la base de datos de PostgreSQL de la que se leerá.
- DATABASE_USER: Es el usuario de la base de datos de PostgreSQL que se usará para autenticar en la base de datos.
- CREDENTIALS: Es una ruta de acceso al Secret de Secret Manager que contiene la contraseña de la base de datos. Especifica el Secret con el siguiente formato:
```
${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}
```
- TOPIC_PREFIX: Es un prefijo que se usará para los nombres de los temas de Kafka.

Configura el conector

En esta sección, se describen algunas propiedades de configuración que puedes establecer en el conector. Para obtener una lista completa, consulta Conector de Debezium para PostgreSQL en la documentación de Debezium.

Configuración de contraseñas y contraseñas de SSL

Solo se admiten rutas de acceso de Secrets en los parámetros de configuración database.password y database.sslpassword. El backend espera que estos parámetros de configuración usen el siguiente formato: ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

Tipos de dirección IP

La propiedad driver.ipTypes especifica el tipo de dirección IP que usa el conector para conectarse a la base de datos:

PRIVATE: IP privada
PSC: Private Service Connect
PUBLIC: IP pública

La propiedad driver.ipTypes contiene una lista separada por comas de tipos de IP en el orden preferido; por ejemplo, driver.ipTypes=PRIVATE,PUBLIC.

Modo de publicación

Un conector de fuente de PostgreSQL genérica transmite eventos de cambio desde una publicación en la base de datos. Puedes crear la publicación de forma manual o permitir que el conector la cree automáticamente.

El parámetro de configuración publication.autocreate.mode especifica cómo y si el conector debe crear una publicación.

filtered. Si la publicación no existe, el conector crea una nueva que incluye solo las tablas capturadas. El usuario de la base de datos debe tener permisos CREATE en la base de datos y ser el propietario de las tablas incluidas.

Si la publicación ya existe, el conector la modifica para incluir las tablas capturadas. Para modificar una publicación existente, el usuario de la base de datos debe ser el propietario de la publicación y de las tablas incluidas.
all_tables. Si la publicación no existe, el conector crea una nueva con el parámetro FOR ALL TABLES. El usuario de la base de datos debe ser un superusuario.

Los roles de superusuario omiten todas las verificaciones de permisos en una base de datos, por lo que no se recomienda otorgar SUPERUSER al usuario de la base de datos. En su lugar, crea la publicación de forma manual o establece publication.autocreate.mode=filtered.
disabled. Si la publicación no existe, se produce un error. El conector no crea una publicación nueva.

El valor predeterminado es all_tables.

Nombre de la publicación

De forma predeterminada, el conector intenta transmitir desde una publicación llamada dbz_publication. Para especificar una publicación diferente, agrega publication.name=PUBLICATION_NAME a la configuración, donde PUBLICATION_NAME es el nombre de la publicación. Ejemplo: publication.name=my_publication.

Ranuras de replicación

PostgreSQL usa ranuras de replicación para transmitir cambios en las tablas de la base de datos. De forma predeterminada, el conector crea una ranura de replicación llamada debezium. Para usar un nombre de espacio diferente, establece la propiedad slot.name.

Si creas dos instancias del conector para la misma base de datos, debes especificar un nombre de ranura único para cada conector.

De forma predeterminada, el conector establece la propiedad slot.drop.on.stop en false para evitar la pérdida de datos. Cuando borras un conector de forma permanente, debes descartar manualmente la ranura de replicación que usaba el conector. El nombre de la ranura de replicación se establece de forma predeterminada en debezium, a menos que se configure de manera diferente con la propiedad slot.name.

Te recomendamos que configures alertas para supervisar el uso del disco de WAL en tu servidor de base de datos de PostgreSQL de origen y que descartes las ranuras de replicación que no se usen.

Filtro de tabla

De forma predeterminada, el conector captura los datos de cambios de todas las tablas que no son del sistema en la base de datos. Para filtrar qué tablas se capturan, especifica uno o más de los siguientes parámetros de configuración:

schema.include.list: Es una lista de esquemas que se deben incluir.
schema.exclude.list: Es una lista de esquemas que se excluirán. No se puede usar con schema.include.list.
table.include.list: Es una lista de tablas que se deben incluir.
table.exclude.list: Es una lista de tablas que se excluirán. No se puede usar con table.include.list.

Nombres de los temas

De forma predeterminada, el conector crea temas de Kafka con la siguiente convención de nombres: topic_prefix.schema.table_name, en la que topic.prefix es el valor de la configuración de topic.prefix.

Para obtener más información, consulta Nombres de temas en la documentación de Debezium.

¿Qué sigue?

Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados en Estados Unidos y otros países.