Configurer Oracle pour l'ingestion dans Databricks

info

Bêta

Cette fonctionnalité est en Bêta. Les administrateurs du Workspace peuvent contrôler l’accès à cette fonctionnalité depuis la page Aperçus . Voir Gérer les aperçus Databricks.

Cette page décrit les tâches de base de données source requises pour l'ingestion d'Oracle vers Databricks Lakeflow Connect.

Le connecteur Oracle utilise LogMiner en mode de transaction non validée pour lire les changements depuis les logs redo en ligne et les logs d'archive.

Exigences

• Version d’Oracle 12c ou supérieure (12c, 18c, 19c, 21c, 23ai et 26ai).
• Mode de Logs d'archive activé.
• Journalisation supplémentaire activée pour les tables que vous souhaitez répliquer. La journalisation supplémentaire de clé primaire est le minimum ; une journalisation supplémentaire complète est requise pour les tables qui reçoivent des instructions UPDATE sur les colonnes de clé primaire ou de clé unique. Une journalisation supplémentaire minimale n'est pas suffisante seule. Voir Quelle méthode de journalisation supplémentaire dois-je choisir ?.
• Une base de données primaire (non secondaire). Oracle RAC et les données chiffrées avec Transparent Data Encryption (TDE) avec un portefeuille fermé ne sont pas pris en charge.
• Pour les bases de données multi-tenant, un utilisateur commun dans CDB$ROOT avec les privilèges requis.

Présentation de la configuration de la source

Effectuez les tâches suivantes dans Oracle avant d'ingérer des données dans Databricks. Exécutez chaque étape en tant qu'utilisateur SYSDBA, ou en tant qu'utilisateur ADMIN pour les bases de données Amazon RDS.

1. Vérifier le mode de log d'archivage et la conservation des logs.
2. Activer la journalisation supplémentaire.
3. Créez un utilisateur de réplication à l'aide du script de configuration.
4. Notez les détails de connexion, y compris le nom du service et le domaine de la base de données.

Étape 1 : Vérifier le mode archive log et la rétention des Logs

Le connecteur CDC intégré Oracle lit les archive Logs. La requête suivante doit renvoyer ARCHIVELOG:

SQL

SELECT LOG_MODE FROM V$DATABASE;

Si la query renvoie NOARCHIVELOG, activez le mode Logs d'archivage avant de continuer.

Étapes pour activer l'archivage des Logs

Non-RDS database

Pour les bases de données Oracle standard :

SQL

SHUTDOWN IMMEDIATE;
STARTUP MOUNT;
ALTER DATABASE ARCHIVELOG;
ALTER DATABASE OPEN;

Amazon RDS database

Pour Oracle sur AWS RDS, activez les sauvegardes automatiques.

Assurer la rétention des logs d'archivage

Databricks recommande de conserver les logs d’archive pendant au moins 48 heures. Si Oracle purge les Logs d’archive avant que le pipeline ne puisse les traiter, vous devez effectuer un refresh complet des tables concernées. Planifiez votre capacité de disque en conséquence pour stocker les fichiers Logs d’archive conservés.

Non-RDS database

Exécutez ce qui suit dans Recovery Manager (RMAN).

SQL

CONFIGURE RETENTION POLICY TO RECOVERY WINDOW OF 2 DAYS;

Amazon RDS database

Pour Oracle sur AWS RDS, consultez la documentation AWS.

SQL

BEGIN
    rdsadmin.rdsadmin_util.set_configuration(
        name  => 'archivelog retention hours',
        value => '48');
END;

Étape 2 : activer la journalisation supplémentaire

Le connecteur nécessite au moins une journalisation supplémentaire de clé primaire sur chaque table que vous répliquez. Une journalisation supplémentaire complète est requise pour les tables qui reçoivent des instructions UPDATE sur des colonnes de clé primaire ou de clé unique. Pour plus de détails, consultez Quelle méthode de journalisation supplémentaire dois-je choisir ?.

Vous pouvez activer la journalisation supplémentaire sur chaque table, ou au niveau de la base de données afin que chaque table en hérite. Les commandes diffèrent selon que votre base de données s'exécute sur Amazon RDS.

Pour activer la journalisation supplémentaire de la clé primaire au niveau de la table :

SQL

ALTER TABLE <schema>.<table> ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;

Pour activer la journalisation supplémentaire complète au niveau de la table :

SQL

ALTER TABLE <schema>.<table> ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

Pour activer la journalisation supplémentaire des clés primaires au niveau de la base de données (facultatif ; chaque table en hérite) :

Non-RDS database

SQL

ALTER DATABASE ADD SUPPLEMENTAL LOG DATA (PRIMARY KEY) COLUMNS;

Amazon RDS database

SQL

BEGIN
  rdsadmin.rdsadmin_util.alter_supplemental_logging(
    p_action => 'ADD',
    p_type   => 'PRIMARY KEY'
  );
END;

Consultez les documents AWS pour en savoir plus.

Étape 3 : Créer un utilisateur de réplication à l'aide du script de configuration

Databricks fournit un outil de configuration Oracle PL/SQL (dbx_oracle_setup_util) qui automatise la création d’utilisateurs et l’octroi de privilèges pour la CDC. Le package expose les procédures suivantes :

Procédure	Description
create_user(...)	Crée un utilisateur de réplication CDC avec un tablespace par default spécifié, un tablespace temporaire et un quota illimité sur le tablespace par default.
grant_permissions(...)	Accorde les privilèges système et d'objet requis pour LogMiner CDC. Voir Exigences relatives aux utilisateurs de base de données Oracle.
grant_select_permissions(...)	Accorde SELECT sur chaque table d'un schéma.
grant_select_on_table(...)	Accorde SELECT sur une table spécifique.
validate_setup(...)	Valide l'environnement de base de données, la configuration de base de données requise, l'utilisateur de réplication et les privilèges requis.
drop_user(...)	Supprime un utilisateur de réplication créé précédemment. Utilisez ceci pour nettoyer ou recréer l’utilisateur.

Procédure	Description
create_user(...)	Crée un utilisateur de réplication CDC avec un tablespace par default spécifié, un tablespace temporaire et un quota illimité sur le tablespace par default.
grant_permissions(...)	Accorde les privilèges système et d'objet requis pour LogMiner CDC. Voir Exigences relatives aux utilisateurs de base de données Oracle.
grant_select_permissions(...)	Accorde SELECT sur chaque table d'un schéma.
grant_select_on_table(...)	Accorde SELECT sur une table spécifique.
validate_setup(...)	Valide l'environnement de base de données, la configuration de base de données requise, l'utilisateur de réplication et les privilèges requis.
drop_user(...)	Supprime un utilisateur de réplication créé précédemment. Utilisez ceci pour nettoyer ou recréer l’utilisateur.

Installer l'outil de configuration

1. download the setup tool: dbx-oracle-setup-package.sql.

2. Exécutez le script pour créer le package PL/SQL dbx_oracle_setup_util. Exécutez-le avec les privilèges SYSDBA (ou en tant qu'utilisateur ADMIN sur Amazon RDS).

   Pour une base de données multi-tenant, exécutez le script dans le conteneur CDB$ROOT.

Créer l'utilisateur de réplication

Créer un utilisateur de réplication dédié. Le nom d'utilisateur doit être en majuscules. Pour une base de données multi-tenant (CDB), le nom d'utilisateur doit start par C## afin qu'un utilisateur commun soit créé. Pour une base de données non-CDB, n'utilisez pas le préfixe C##.

L’exemple suivant crée un utilisateur nommé C##CDCREPL avec le tablespace default USERS et le tablespace temporaire TEMP:

SQL

BEGIN
  DBX_ORACLE_SETUP_UTIL.CREATE_USER('C##CDCREPL', '<password>', 'USERS', 'TEMP');
END;
/

remarque

N'utilisez pas l'utilisateur SYS ou SYSTEM pour la réplication.

Accorder des privilèges au niveau de la base de données

Accordez à l’utilisateur de réplication les privilèges requis pour la CDC LogMiner. L’outil choisit automatiquement la méthode d’octroi correcte pour votre environnement (octrois standard ou octrois Amazon RDS rdsadmin) et définit CONTAINER_DATA=ALL pour les bases de données multi-tenant.

SQL

BEGIN
  DBX_ORACLE_SETUP_UTIL.GRANT_PERMISSIONS('C##CDCREPL');
END;
/

Pour obtenir la liste complète des privilèges accordés par l'outil, consultez Oracle database user requirements.

Accorder des privilèges SELECT sur les tables

Accordez à l’utilisateur de réplication SELECT sur chaque table que vous répliquez. L’outil de configuration propose deux procédures pour cela :

SQL

BEGIN
  -- to grant SELECT on all tables in a schema
  DBX_ORACLE_SETUP_UTIL.GRANT_SELECT_PERMISSIONS('C##CDCREPL', '<schema_to_replicate>', '<container_name>');
  -- to grant SELECT on specific tables in the schema
  DBX_ORACLE_SETUP_UTIL.GRANT_SELECT_ON_TABLE('C##CDCREPL', '<schema_to_replicate>', '<table_name>', '<container_name>');
END;
/

Pour une base de données non CDB, omettez l'argument <container_name>.

Vous pouvez également accorder SELECT manuellement sur des tables individuelles :

SQL

GRANT SELECT ON <schema>.<table> TO C##CDCREPL;

L'UI ne peut afficher que les tables pour lesquelles l'utilisateur de réplication dispose de l'autorisation SELECT.

remarque

Le privilège SELECT ANY TABLE d'Oracle accorde un accès en lecture à chaque table de la base de données en une seule instruction. Évitez de l'utiliser en dehors d'une base de données de développement, car cela expose des tables que vous ne souhaitez peut-être pas que l'utilisateur de réplication lise.

Valider la configuration

Validez l'environnement de base de données, la configuration de base de données requise, l'utilisateur de réplication et les privilèges requis :

SQL

BEGIN
  DBX_ORACLE_SETUP_UTIL.VALIDATE_SETUP('C##CDCREPL');
END;
/

Étape 4 : Notez les détails de la connexion

Lorsque vous créez la connexion Unity Catalog, vous avez besoin des détails suivants concernant votre base de données Oracle. Voir Créer une connexion Oracle.

Nom du service

Le connecteur se connecte à Oracle à l'aide d'un nom de service .

• Pour une base de données single-tenant (non-CDB) , utilisez le nom de service de la base de données.
• Pour une base de données multi-tenant (CDB) , utilisez le nom de service CDB$ROOT. Le connecteur se connecte à CDB$ROOT pour lire les modifications de toutes les bases de données enfichables (PDB), puis résout automatiquement les noms de service des PDB. Voir Bases de données multi-tenant (CDB).

Domaine de base de données

Si votre base de données a le parameter d’initialisation DB_DOMAIN défini, Oracle enregistre chaque service auprès du processus d’écoute en utilisant un nom qualifié par le domaine (par exemple : FREEPDB1.example.com plutôt que FREEPDB1). Ceci est courant dans les environnements utilisant Oracle Connection Manager (CMAN) comme interface.

Lorsque DB_DOMAIN est défini, le nom du service CDB$ROOT que vous fournissez dans la connexion Unity Catalog doit inclure le suffixe de domaine (par exemple, newcorp.example.com). Pour vérifier la valeur actuelle :

SQL

SELECT value FROM v$parameter WHERE name = 'db_domain';

Le connecteur ajoute automatiquement le DB_DOMAIN découvert aux noms de service PDB. Vous devez uniquement fournir le nom de service CDB$ROOT qualifié par le domaine dans la connexion. Pour plus de détails, consultez Créer une connexion Oracle.

Bases de données multi-tenant (CDB)

Pour une base de données multi-tenant :

• Exécutez le script de configuration dans le conteneur CDB$ROOT.
• L'utilisateur de réplication doit être un utilisateur commun (préfixe C##).
• L'outil de configuration définit CONTAINER_DATA=ALL sur l'utilisateur afin qu'il puisse lire les données de modification sur tous les conteneurs.
• Dans la connexion Unity Catalog, utilisez le nom de service CDB$ROOT (qualifié par le domaine si DB_DOMAIN est défini).

Les instances Amazon RDS for Oracle multi-tenant ne sont pas prises en charge.

Sensibilité à la casse

By default, Oracle traite les identifiants non guillemetés comme insensibles à la casse et les convertit en majuscules. Si vous placez un identifiant entre guillemets lors de la création, Oracle en préserve la casse.

Lorsque vous créez la connexion Unity Catalog, utilisez un nom d’utilisateur en majuscules, sauf si la base de données le stocke en minuscules. Lorsque vous spécifiez des noms de schéma, de table et de colonne dans votre pipeline, la casse doit correspondre à la façon dont Oracle stocke l’identifiant.

Limitations de LogMiner

LogMiner ne prend pas en charge les types de données et attributs de stockage suivants. Si une table contient l’un de ces éléments, LogMiner ignore la table entière :

• BFILE
• Tables imbriquées et collections VARRAY
• Objets avec des tables imbriquées.
• Tables avec colonnes d'identité
• Colonnes de validité temporelle
• PKREF Colonnes
• PKOID colonnes (colonnes de type objet)
• Attributs de table imbriqués et colonnes de table imbriquées autonomes.

En outre :

• Les noms de table et de colonne ne peuvent pas dépasser 30 caractères.
• Les types de données et les fonctionnalités ajoutés après Oracle Database 12c Release 2 (12.2) ne sont pas pris en charge. Cela inclut BOOLEAN, VECTOR et JSON.

Mappages des types de données

Pour le mappage des types de données Oracle vers les types Databricks, consultez la référence du connecteur CDC intégré Oracle.

Étapes suivantes

• Passez en revue les exigences en matière de privilèges.
• Créer une connexion Oracle.