Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Créer un connecteur de source PostgreSQL générique

Ce document explique comment créer un connecteur source PostgreSQL générique.

Un connecteur source PostgreSQL générique est une instance d'un connecteur Debezium PostgreSQL. Il lit les modifications au niveau des lignes d'une base de données PostgreSQL et les écrit dans des sujets d'un cluster Managed Service pour Apache Kafka.

Voici quelques cas d'utilisation de ce connecteur :

Surveiller les modifications de la base de données au niveau des lignes en temps réel
Intégrer les événements de modification de la base de données dans une architecture basée sur des événements
Répondre aux événements de la base de données, tels que les insertions ou les suppressions de lignes
Copier les modifications de la base de données vers d'autres systèmes
Répliquer ou restaurer des tables PostgreSQL

Avant de commencer

Avant de créer un connecteur source PostgreSQL générique, assurez-vous de disposer des éléments suivants :

Une base de données PostgreSQL
Un cluster Connect associé au cluster Kafka.
Créez un secret Secret Manager qui stocke le mot de passe de la base de données. Si votre configuration utilise le protocole SSL de la base de données, créez également un secret pour le mot de passe SSL de la base de données. Configurez votre cluster Connect avec les secrets. Pour en savoir plus, consultez Ressources Secret Manager.

Remarque : Les mots de passe en texte brut ne sont pas acceptés. Seuls les chemins secrets sont acceptés dans les configurations database.password et database.sslpassword. Le backend s'attend à ce que ces configurations utilisent le format suivant : ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

Rôles et autorisations requis

Pour obtenir les autorisations nécessaires pour créer un connecteur, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de connecteurs Managed Kafka (roles/managedkafka.connectorEditor) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour créer un connecteur. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer un connecteur :

Créer un connecteur : managedkafka.connectors.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Accorder des autorisations pour accéder aux secrets Secret Manager

Le compte de service Managed Kafka a besoin d'une autorisation pour afficher et accéder aux secrets stockés dans Secret Manager. Attribuez les rôles IAM suivants au compte de service :

Lecteur Secret Manager (roles/secretmanager.viewer)
Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor)

Le compte de service Managed Kafka a le format suivant : service-PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com, où PROJECT_NUMBER est le numéro de projet du cluster Connect.

Si votre cluster Connect se trouve dans un projet différent de votre cluster Managed Service pour Apache Kafka cluster, consultez Créer un cluster Connect dans un autre projet.

Configurer votre base de données PostgreSQL

Pour permettre au connecteur de lire les événements de modification des données de votre base de données, configurez les paramètres suivants.

Définissez le wal_level du serveur sur logical.
```
ALTER SYSTEM SET wal_level = logical;
```
Redémarrez le serveur pour appliquer le paramètre.
Créez un utilisateur de base de données pour que le connecteur s'authentifie auprès de PostgreSQL. L'utilisateur de la base de données doit être un rôle de réplication, ce qui lui permet de se connecter au serveur en mode de réplication.
```
CREATE ROLE ROLE_NAME WITH REPLICATION LOGIN PASSWORD 'ROLE_PASSWORD';
```
Remplacez les éléments suivants :
- ROLE_NAME: nom de l'utilisateur, par exemple debezium_user.
- ROLE_PASSWORD : mot de passe de l'utilisateur.
Créez une publication pour les tables que vous souhaitez capturer. Le connecteur s'abonne à la publication pour recevoir les événements de modification des données.
```
CREATE PUBLICATION dbz_publication FOR TABLE "SCHEMA_NAME"."TABLE_NAME";
```
Remplacez les éléments suivants :
- SCHEMA_NAME : schéma de la table.
- TABLE_NAME : nom de la table.
Nous vous recommandons de mettre le schéma et les noms de table entre guillemets doubles, comme indiqué, pour éviter les erreurs de syntaxe si les noms contiennent des caractères spéciaux ou des lettres majuscules.

Vous pouvez également créer une publication qui réplique les modifications pour toutes les tables de la base de données :
```
CREATE PUBLICATION dbz_publication FOR ALL TABLES;
```
Selon le paramètre publication.autocreate.mode du connecteur, vous pouvez créer la publication manuellement ou laisser le connecteur la créer automatiquement. Pour en savoir plus, consultez Mode de publication.
Pour chaque table, accordez des privilèges SELECT sur la table à l'utilisateur de la base de données.
```
GRANT SELECT ON TABLE "SCHEMA_NAME"."TABLE_NAME" TO ROLE_NAME;
```
Vous pouvez également accorder une sélection sur toutes les tables d'un schéma :
```
GRANT SELECT ON ALL TABLES IN SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```
Pour chaque table, accordez des privilèges USAGE sur le schéma de la table à l'utilisateur de la base de données. Vous pouvez ignorer cette étape si la table se trouve dans le schéma public par défaut.
```
GRANT USAGE ON SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```

Créer un connecteur source PostgreSQL générique

Pour créer un connecteur source PostgreSQL générique, procédez comme suit.

Lorsque le connecteur est initialisé, il effectue les actions suivantes :

Crée un instantané initial de la base de données.
Crée un sujet Kafka pour chaque table contenant des lignes.
Pour chaque ligne de la base de données, envoie un événement de modification au sujet correspondant.

Pendant l'exécution du connecteur, il continue d'envoyer des événements de modification aux sujets. Pour en savoir plus sur l'instantané initial, consultez Instantanés dans la documentation Debezium.

Console

Dans la Google Cloud console, accédez à la page Clusters Connect.

Accéder aux clusters Connect
Cliquez sur le cluster Connect dans lequel vous souhaitez créer le connecteur.
Cliquez sur Créer un connecteur.
Pour le nom du connecteur, saisissez une chaîne.

Pour obtenir des instructions sur la façon de nommer un connecteur, consultez Consignes de dénomination d'une ressource Managed Service pour Apache Kafka.
Pour Plug-in de connecteur, sélectionnez Source PostgreSQL générique.
Dans le champ Nom d'hôte de la base de données, saisissez le nom d'hôte ou l'adresse IP du serveur PostgreSQL.
Dans le champ Nom de la base de données, saisissez le nom de la base de données.
Dans le champ Utilisateur de la base de données, saisissez le nom du rôle de réplica. Le connecteur s'authentifie auprès du serveur PostgreSQL à l'aide de ce rôle.
Dans le champ Préfixe du sujet, saisissez un préfixe à utiliser pour les noms de sujets Kafka.
Dans la liste Secret, sélectionnez le secret contenant le mot de passe de la base de données.
(Facultatif) Dans la zone Configurations, ajoutez des propriétés de configuration ou modifiez les propriétés par défaut. Pour en savoir plus, consultez Configurer le connecteur.
(Facultatif) Sélectionnez la Règle de redémarrage des tâches. Pour en savoir plus, consultez Règle de redémarrage des tâches.
Cliquez sur Créer.

gcloud

Dans la Google Cloud console, activez Cloud Shell.

Activer Cloud Shell

En bas de la Google Cloud console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
Exécutez la gcloud managed-kafka connectors create commande :
```
gcloud managed-kafka connectors create CONNECTOR_ID \
    --location=LOCATION \
    --connect-cluster=CONNECT_CLUSTER_ID \
    --config-file=CONFIG_FILE
```
Remplacez les éléments suivants :
- CONNECTOR_ID : ID ou nom du connecteur. Pour obtenir des instructions sur la façon de nommer un connecteur, consultez Consignes de dénomination d'une ressource Managed Service pour Apache Kafka. Le nom d'un connecteur est immuable.
- LOCATION: emplacement où vous créez le connecteur. Il doit s'agir du même emplacement que celui où vous avez créé le cluster Connect.
- CONNECT_CLUSTER_ID: ID du cluster Connect dans lequel le connecteur est créé.
- CONFIG_FILE: chemin d'accès au fichier de configuration YAML du connecteur.
Voici un exemple de fichier de configuration pour le connecteur source PostgreSQL générique :
```
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"
```
Remplacez les éléments suivants :
- HOSTNAME: nom d'hôte de la base de données PostgreSQL à partir de laquelle effectuer la lecture.
- DATABASE_NAME: nom de la base de données PostgreSQL à partir de laquelle effectuer la lecture.
- DATABASE_USER: utilisateur de la base de données PostgreSQL à utiliser lors de l'authentification auprès de la base de données.
- CREDENTIALS : chemin d'accès au secret Secret Manager qui contient le mot de passe de la base de données. Spécifiez le secret au format suivant :
```
${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}
```
- TOPIC_PREFIX: préfixe à utiliser pour les noms de sujets Kafka.

Configurer le connecteur

Cette section décrit certaines propriétés de configuration que vous pouvez définir sur le connecteur. Pour obtenir la liste complète, consultez Connecteur Debezium pour PostgreSQL dans la documentation Debezium.

Configurations du mot de passe et du mot de passe SSL

Seuls les chemins secrets sont acceptés dans les configurations database.password et database.sslpassword. Le backend s'attend à ce que ces configurations utilisent le format suivant : ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

Types d'adresses IP

La propriété driver.ipTypes spécifie le type d'adresse IP que le connecteur utilise pour se connecter à la base de données :

PRIVATE : adresse IP privée
PSC: Private Service Connect
PUBLIC : adresse IP publique

La propriété driver.ipTypes contient une liste de types d'adresses IP séparés par une virgule dans l'ordre de préférence . Par exemple, driver.ipTypes=PRIVATE,PUBLIC.

Mode de publication

Un connecteur source PostgreSQL générique diffuse les événements de modification d'une publication dans la base de données. Vous pouvez créer la publication manuellement ou laisser le connecteur la créer automatiquement.

Le publication.autocreate.mode paramètre spécifie comment et si le connecteur doit créer une publication.

filtered. Si la publication n'existe pas, le connecteur en crée une qui n'inclut que les tables capturées. L'utilisateur de la base de données doit disposer des autorisations CREATE sur la base de données et être le propriétaire des tables incluses.

Si la publication existe déjà, le connecteur la modifie pour inclure les tables capturées. Pour modifier une publication existante, l'utilisateur de la base de données doit être le propriétaire de la publication et des tables incluses.
all_tables. Si la publication n'existe pas, le connecteur en crée une à l'aide du paramètre FOR ALL TABLES. L'utilisateur de la base de données doit être un super-utilisateur.

Les rôles de super-utilisateur contournent toutes les vérifications d'autorisation dans une base de données. Il n'est donc pas recommandé d'accorder le rôle SUPERUSER à l'utilisateur de la base de données. Créez plutôt la publication manuellement ou définissez publication.autocreate.mode=filtered.
disabled. Si la publication n'existe pas, une erreur se produit. Le connecteur ne crée pas de publication.

La valeur par défaut est all_tables.

Titre de la publication

Par défaut, le connecteur tente de diffuser à partir d'une publication nommée dbz_publication. Pour spécifier une autre publication, ajoutez publication.name=PUBLICATION_NAME à la configuration, où PUBLICATION_NAME est le nom de la publication. Exemple : publication.name=my_publication.

Emplacements de réplication

PostgreSQL utilise des emplacements de réplication pour diffuser les modifications apportées aux tables de la base de données. Par défaut, le connecteur crée un emplacement de réplication nommé debezium. Pour utiliser un autre nom d'emplacement, définissez la propriété slot.name.

Si vous créez deux instances du connecteur pour la même base de données, vous devez spécifier un nom d'emplacement unique pour chaque connecteur.

Par défaut, le connecteur définit la propriété slot.drop.on.stop sur false pour éviter toute perte de données. Lorsque vous supprimez définitivement un connecteur, vous devez supprimer manuellement l'emplacement de réplication que le connecteur utilisait. Le nom de l'emplacement de réplication est défini par défaut sur debezium, sauf si vous le configurez différemment à l'aide de la slot.name propriété.

Nous vous recommandons de configurer des alertes pour surveiller l'utilisation du disque WAL sur votre serveur de base de données PostgreSQL source et de supprimer tous les emplacements de réplication inutilisés.

Filtre de table

Par défaut, le connecteur capture les données de modification de chaque table non système de la base de données. Pour filtrer les tables capturées, spécifiez un ou plusieurs des paramètres suivants :

schema.include.list : liste des schémas à inclure.
schema.exclude.list : liste des schémas à exclure. Ne peut pas être utilisé avec schema.include.list.
table.include.list : liste des tables à inclure.
table.exclude.list : liste des tables à exclure. Ne peut pas être utilisé avec table.include.list.

Noms de sujets

Par défaut, le connecteur crée des sujets Kafka avec la convention d'attribution de noms suivante : topic_prefix.schema.table_name, où topic.prefix est la valeur de la configuration topic.prefix.

Pour en savoir plus, consultez Noms de sujets dans la documentation Debezium.