Comment installer ora2pg sur Ubuntu et générer un rapport d'évaluation de migration

TL;DR : L'installation d'ora2pg sur Ubuntu 24.04 nécessite trois composants : Oracle Instant Client 19c (pour les bibliothèques de connexion Oracle), le module Perl DBD::Oracle (qui se lie à ces bibliothèques) et ora2pg lui-même (installé à partir des sources — il n'est pas sur CPAN). Une fois installés, une seule commande se connecte à votre base de données Oracle, analyse chaque objet du schéma et produit un rapport HTML avec un score de complexité et une estimation de l'effort en jours-homme. Ce post couvre l'installation complète et la commande de génération de rapport.

La façon la plus rapide de savoir si une migration d'Oracle vers PostgreSQL est un travail d'une semaine ou un projet de trois mois est de générer le rapport de migration ora2pg avant d'ouvrir une feuille de calcul.

Le rapport se connecte à Oracle, compte chaque objet par type, évalue le schéma de A (simple) à C (complexe) et produit une estimation de l'effort en jours-homme.

Cela prend environ vingt minutes à installer et soixante secondes à exécuter.

Table des matières

Ce que le Rapport de migration produit

La commande ora2pg SHOW_REPORT se connecte à votre base de données Oracle, analyse chaque objet du schéma et produit un tableau avec cinq colonnes : type d'objet, nombre d'objets, nombre d'objets invalides, coût de migration estimé en unités et commentaires sur ce que fera ora2pg avec chaque type.

La dernière ligne donne un coût total et une estimation d'effort lisible par l'homme : “22,40 unités de coût de migration signifient approximativement 1 jour(s)-homme.".

L'unité de migration était réglée sur 5 minute(s).”

Le score se compose de deux parties : une lettre et un chiffre.

La lettre reflète une complexité globale :

A — migration qui peut être largement automatisée
B — Migration avec réécriture de code ; coût estimé jusqu'à 10 jours-homme
C — migration avec réécriture de code ; coût estimé supérieur à 10 jours-homme

Le nombre reflète la difficulté technique :

1 — aucune fonction stockée, aucun déclencheur
2 — déclencheurs présents, aucune réécriture manuelle requise
3 — fonctions stockées et/ou déclencheurs, aucune réécriture manuelle requise
4 — déclencheurs ou vues nécessitant une réécriture de code
5 — fonctions stockées et/ou déclencheurs qui nécessitent une réécriture du code

Un schéma sans code stocké obtient un score A-1. Un schéma avec des packages PL/SQL, des déclencheurs et des vues spécifiques à Oracle obtient généralement un score B-4 ou B-5.

Le niveau C est déclenché lorsque l'effort estimé dépasse 10 jours-personne (réglable avec --journées_humaines_limite).

Exécutez le rapport avant de vous engager sur un calendrier.

Le nombre qu'il produit est le seul nombre à connaître avant le début du projet.

Prérequis

Trois choses sont nécessaires, dans l'ordre de dépendance :

Client Oracle Instant 19c — les bibliothèques C (libclntsh.so et associés) auxquels le pilote Perl se lie au moment de la compilation et qu'il charge au moment de l'exécution. Sans eux, aucune connexion Oracle n'est possible, quel que soit l'accès réseau.
DBD::Oracle — le module Perl qui fournit le pilote Oracle. Il se compile avec les en-têtes d'Instant Client lors de l'installation — le paquet devel est requis, pas seulement le runtime de base.
ora2pg 25.0 — installé à partir des sources via son fichier tarball de version GitHub. ora2pg n'est pas disponible sur CPAN ; cpanm ora2pg échouera.

Vous avez également besoin d'un accès réseau depuis la machine Ubuntu à la base de données Oracle sur le port 1521 et d'un utilisateur de base de données disposant des privilèges suffisants pour analyser le schéma (détails dans la FAQ ci-dessous).

Si votre serveur Oracle n'est pas dans le DNS, ajoutez-le au /etc/hosts sur la machine Ubuntu avant de continuer :

sudo vi /etc/hosts
# Add: 192.168.x.x   your-oracle-host.localdomain   your-oracle-host

Vérifiez la résolution de nom avant de continuer :

ping -c 2 your-oracle-host.localdomain

Si le ping échoue, les tests de connectivité de l'étape 3 échoueront également — réparez le DNS ou /etc/hosts premier.

Étape 1 : Installer Oracle Instant Client sur Ubuntu 24.04

Oracle distribue Instant Client sous forme de paquets RPM uniquement.

Ubuntu utilise des paquets DEB.

Le étranger l'outil convertit les RPM en DEB — il gère la traduction des métadonnées du paquet afin que les fichiers se retrouvent dans les bons chemins et que le gestionnaire de paquets suive l'installation.

Téléchargez trois paquets depuis Téléchargements d'Oracle Instant Client page — utilisez les RPM génériques Linux x86-64 pour la version 19.30, pas les variantes OL8 ou OL9 (celles-ci sont compilées pour les systèmes de la famille Red Hat et ont des dépendances différentes) :

oracle-instantclient19.30-basic-*.rpm — les bibliothèques partagées d'exécution complète (libclntsh.so, libnnz19.so, et autres)
oracle-instantclient19.30-développeur-*.rpm — fichiers d'en-tête et le sdk/ répertoire requis pour compiler DBD::Oracle
oracle-instantclient19.30-sqlplus-*.rpm le sqlplus64 binaire pour tester la connectivité Oracle indépendamment d'ora2pg

Transférez les trois RPM sur votre machine Ubuntu, puis exécutez :

# libaio1t64: the async I/O library required by Oracle Instant Client at runtime
# On Ubuntu 24.04 the package name is libaio1t64, not libaio1 -- the name changed in this release
# alien: converts RPM packages to DEB format for installation with dpkg
sudo apt-get install -y libaio1t64 alien

# Convert each RPM to DEB and install in one step (-i: convert and install immediately)
sudo alien -i oracle-instantclient19.30-basic-*.rpm
sudo alien -i oracle-instantclient19.30-devel-*.rpm
sudo alien -i oracle-instantclient19.30-sqlplus-*.rpm

Correction de lien symbolique Ubuntu 24.04 : Ubuntu 24.04 expédie la bibliothèque d'E/S asynchrones comme libaio.so.1t64 dans le cadre de la transition vers time_t 64 bits.

Oracle Instant Client a été compilé sur des systèmes Red Hat et utilise en dur libaio.so.1 dans son binaire ELF.

Sans lien symbolique, sqlplus64 échoue immédiatement avec impossible d'ouvrir le fichier d'objet partagé : libaio.so.1.

Créez le lien symbolique avant de tester :

sudo ln -s /usr/lib/x86_64-linux-gnu/libaio.so.1t64 /usr/lib/x86_64-linux-gnu/libaio.so.1

Définissez les trois variables d'environnement requises et enregistrez-les de manière persistante pour ~/.bashrc:

export ORACLE_HOME=/usr/lib/oracle/19.30/client64
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
export PATH=$ORACLE_HOME/bin:$PATH

echo 'export ORACLE_HOME=/usr/lib/oracle/19.30/client64' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$ORACLE_HOME/lib' >> ~/.bashrc
echo 'export PATH=$ORACLE_HOME/bin:$PATH' >> ~/.bashrc

ORACLE_HOME indique à DBD::Oracle et ora2pg où le client instantané est installé — les deux outils lisent ceci au moment de la construction et au moment de l'exécution.

LD_LIBRARY_PATH indique à l'éditeur de liens dynamique de Linux où trouver les bibliothèques partagées d'Oracle — sans cela, tout binaire qui se lie à libclntsh.so échoue avec “erreur lors du chargement des bibliothèques partagées”.

CHEMIN ajoute le répertoire bin d'Instant Client pour sqlplus64 est disponible sur la ligne de commande.

Vérifier l'installation :

sqlplus64 -V
# Expected: SQL*Plus: Release 19.30.0.0.0 Production

Si cette commande échoue avec une erreur de bibliothèque après le lien symbolique, vérifiez que LD_LIBRARY_PATH est exportée (pas seulement définie) dans le shell actuel.

Étape 2 : Installer DBD::Oracle et ora2pg

DBD::Oracle est le pilote de base de données Perl pour Oracle. C'est un module d'extension C — il se compile à partir des sources contre les en-têtes Instant Client lors de l'installation.

C'est pourquoi ORACLE_HOME doit être exporté avant l'exécution cpanm DBD::Oraclele script de compilation lit cette variable pour localiser les en-têtes et lier les bibliothèques partagées.

Installez d'abord les dépendances de compilation :

# perl: the Perl runtime (may already be present on Ubuntu 24.04)
# cpanminus: a lightweight CPAN module installer -- simpler than the full CPAN shell
# make, gcc: required to compile DBD::Oracle from C source
sudo apt-get install -y perl cpanminus make gcc

Puis installez DBD::Oracle — ORACLE_HOME et LD_LIBRARY_PATH doit être exporté dans le shell actuel avant d'exécuter ceci :

sudo cpanm DBD::Oracle

La compilation prend 2 à 3 minutes. Si elle échoue avec un message indiquant que des en-têtes sont manquants, vérifiez que le RPM de développement a été installé et que ORACLE_HOME pointe vers le répertoire correct.

Installez maintenant ora2pg à partir de la tarball de publication GitHub. ora2pg n'est pas disponible sur CPAN — cpanm ora2pg échouera avec “ module introuvable ”.

La seule installation prise en charge est à partir des sources :

wget https://github.com/darold/ora2pg/archive/refs/tags/v25.0.tar.gz
tar xzf v25.0.tar.gz
cd ora2pg-25.0

# Makefile.PL generates the Makefile based on the system Perl configuration
perl Makefile.PL

# make compiles and prepares the distribution
make

# make install copies the ora2pg script and Perl modules to the system Perl paths
sudo make install

cd ..

Vérifier :

ora2pg --version
# Expected: Ora2Pg v25.0

Étape 3 : Configurer la connexion

ora2pg lit /etc/ora2pg/ora2pg.conf par défaut.

L'installation crée /etc/ora2pg/ora2pg.conf.dist en tant que fichier de référence fortement commenté avec tous les paramètres disponibles documentés.

Copiez-le pour créer votre configuration de travail — le fichier dist sert de sauvegarde de base :

sudo cp /etc/ora2pg/ora2pg.conf.dist /etc/ora2pg/ora2pg.conf
sudo vi /etc/ora2pg/ora2pg.conf

Le fichier dist est long (plus de 1 000 lignes de commentaires et de paramètres).

Utilisation /ORACLE_DSN Dans vi, pour sauter directement à chaque paramètre — ne faites pas défiler manuellement.

Définissez ces cinq paramètres :

ORACLE_DSN     dbi:Oracle:host=YOUR_ORACLE_HOST;service_name=YOUR_PDB_NAME;port=1521
ORACLE_USER    system
ORACLE_PWD     YOUR_SYSTEM_PASSWORD
SCHEMA         YOUR_SCHEMA_NAME
OUTPUT_DIR     /home/YOUR_USER/ora2pg-output

ORACLE_DSN: Utilisation nom_du_service, pas sid. Oracle 19c organise les bases de données en bases de données conteneurs (CDB) avec une ou plusieurs bases de données enfichables (PDB). sid=ORCL se connecte à la racine de la CDB — votre schéma d'application n'y existe pas. service_name=VOTRE_NOM_PDB se connecte à la PDB où réside votre schéma. Le nom du service PDB est visible dans lsnrctl status sur le serveur Oracle.

ORACLE_USER: Connectez-vous en tant que SYSTEM ou un autre utilisateur DBA, et non en tant que propriétaire du schéma. Le propriétaire du schéma n'a généralement pas SELECT SUR v$base de données, ce qui provoque l'échec de la commande SHOW_REPORT. L'utilisation de SYSTEM évite les problèmes de privilèges pendant la phase d'évaluation.

Schéma: Limite l'analyse à un seul schéma. Sans cela, ora2pg analyse tous les schémas de la base de données, ce qui augmente considérablement le temps d'analyse et produit un rapport qui mélange tous les objets des schémas.

RÉPERTOIRE_DE_SORTIE: Le répertoire où ora2pg écrit les fichiers d'exportation. Ce répertoire doit exister avant de lancer toute commande ora2pg — ora2pg ne le crée pas automatiquement.

Créez le répertoire de sortie :

mkdir -p ~/ora2pg-output

Exécutez deux tests de connectivité avant de passer au rapport.

Les tests vérifient différentes couches de la pile — la réussite des deux confirme que l'ensemble de la chaîne, d'Ubuntu à Oracle, fonctionne correctement :

# Test 1: sqlplus64 -- verifies Instant Client libraries, network routing, and Oracle listener
sqlplus64 YOUR_USER/YOUR_PASSWORD@//YOUR_ORACLE_HOST:1521/YOUR_PDB_NAME
# Expected: Connected to: Oracle Database 19c Enterprise Edition ...
# Type "exit" to leave the SQL*Plus prompt

# Test 2: ora2pg SHOW_VERSION -- verifies ora2pg connects to Oracle via DBD::Oracle
ora2pg -t SHOW_VERSION
# Expected: Oracle Database 19c Enterprise Edition Release 19.x.x.x.x

# If test 1 fails: check the Oracle listener with "lsnrctl status" on the Oracle server
# and confirm port 1521 is open between the two machines.
# If test 2 fails but test 1 passes: check that LD_LIBRARY_PATH is exported (not just set)
# in the current shell.

Si la connectivité fonctionne mais que vous ne savez pas comment interpréter les résultats du rapport — ou si le score est de niveau C et que vous avez besoin d'un deuxième avis sur la portée — une évaluation à forfait couvre exactement cela

Étape 4 : Exécuter le Rapport d'Évaluation de la Migration

Avant d'exécuter le rapport, recueillez des statistiques fraîches sur le schéma Oracle. ora2pg dérive ses décomptes de lignes et ses estimations de coûts des statistiques stockées dans le dictionnaire de données d'Oracle.

Si les statistiques sont obsolètes — ce qui est courant sur les schémas qui n'ont pas été analysés récemment — les décomptes de lignes seront inexacts et l'estimation de l'effort sera peu fiable.

Exécutez ceci sur le serveur Oracle en tant que SYSTEM ou SYSDBA :

BEGIN
  DBMS_STATS.GATHER_SCHEMA_STATS('YOUR_SCHEMA');
  DBMS_STATS.GATHER_DATABASE_STATS;
  DBMS_STATS.GATHER_DICTIONARY_STATS;
END;
/
-- Expected: PL/SQL procedure successfully completed.

GATHER_SCHEMA_STATS met à jour les statistiques pour le schéma cible. RECUEILLIR_STATISTIQUES_BASE_DE_DONNÉES met à jour les statistiques de tous les objets de la base de données.

STATISTIQUES_RECUEILLIES_DICTIONNAIRE met à jour les vues du dictionnaire de données Oracle que ora2pg lit pendant l'analyse.

Sur une base de données volumineuse, ce bloc peut prendre plusieurs minutes alors que sur un schéma de petite taille comme HR, il s'exécute en quelques secondes.

Puis exécutez le rapport depuis Ubuntu :

# HTML version -- recommended for reading the report
ora2pg -t SHOW_REPORT --estimate_cost --dump_as_html > ~/ora2pg-output/migration_report.html
# SHOW_REPORT: connects to Oracle and counts every object by type in the schema
# --estimate_cost: calculates a complexity score and converts the total units to person-days
# --dump_as_html: formats the output as an HTML table -- open in a browser

# Plain text version -- useful for scripting or sending the report by email
ora2pg -t SHOW_REPORT --estimate_cost > ~/ora2pg-output/migration_report.txt

Ouvrir rapport_migration.html dans un navigateur.

La version texte brut est difficile à lire car les colonnes ne sont pas alignées — la version HTML formate le tableau proprement et c'est celle à partager avec les parties prenantes.

Étape 5 : Lire les résultats du rapport

Le rapport donne une ligne par type d'objet.

Les colonnes sont : type d'objet, nombre d'objets, nombre d'objets invalides, coût estimé en unités de migration, et un champ de commentaires expliquant ce que ora2pg fera avec chaque type.

Faites attention à quatre choses :

Le niveau de migration — indiqué en haut du rapport par une lettre et un chiffre (par exemple, B-5). Les schémas A-1 et A-2 n'ont pas de code stocké et migrent en grande partie automatiquement. Les schémas B-4 et B-5 ont des procédures stockées ou des déclencheurs qui nécessitent une réécriture manuelle en PL/pgSQL. Les schémas de niveau C dépassent le seuil de personnes-jour et nécessitent une portée de projet formelle avant de s'engager dans un calendrier.

Les lignes pour FUNCTION, PROCEDURE, PACKAGE et TRIGGER – c'est là que l'effort manuel se concentre. Les tables, les séquences et les index migrent avec un minimum de travail manuel. Le code stocké, non – chaque fonction, procédure et déclencheur doit être examiné et réécrit. Un schéma avec 200 tables et zéro procédure stockée migre plus rapidement qu'un schéma avec 50 tables et 30 procédures stockées. Les décomptes d'objets dans ces lignes sont les chiffres les plus importants du rapport.

Le nombre d'objets non valides — la troisième colonne du tableau. Tout objet qu'Oracle marque lui-même comme invalide (dépendances rompues, erreurs de compilation) ne sera pas exporté proprement. Corrigez les objets invalides dans Oracle avant d'exécuter une quelconque exportation — ne les intégrez pas dans la migration.

La colonne des commentaires — ora2pg explique ce qu'il fera avec chaque type d'objet et signale les problèmes connus. Lisez attentivement les commentaires TRIGGER : les triggers BEFORE INSERT basés sur des séquences (utilisés pour simuler l'auto-incrémentation dans Oracle) sont exportés en PL/pgSQL mais devraient être remplacés par PostgreSQL IDENTITÉ colonnes ou généré toujours comme identité, ce qui nécessite une décision délibérée lors de la migration.

Étape 6 : Ajuster l'estimation de l'effort

L'unité de coût par défaut est de 5 minutes par unité de migration.

Ce chiffre suppose qu'un consultant ayant de l'expérience avec PostgreSQL effectue le travail de réécriture.

C'est une base raisonnable pour l'évaluation, mais deux paramètres vous permettent de l'ajuster pour qu'elle corresponde à l'équipe réelle et à l'appétit pour le risque.

--valeur_unité_coût modifie le nombre de minutes par unité. La valeur par défaut est de 5. Pour une équipe interne qui effectue sa première migration Oracle → PostgreSQL, doubler à 10 minutes par unité est plus réaliste — les migrations pour la première fois prennent toujours plus de temps que ce que l'outil suggère en raison de la syntaxe inconnue, des cycles de test et des cas limites :

ora2pg -t SHOW_REPORT --estimate_cost --cost_unit_value 10 --dump_as_html > ~/ora2pg-output/migration_report.html
# --cost_unit_value 10: each unit = 10 minutes instead of 5
# The person-day total doubles -- use this when the team has no prior migration experience

--journées_humaines_limite définit le seuil au-dessus duquel le schéma est classé comme niveau C. La valeur par défaut est de 10 jours-homme. L'abaisser à 5 est utile lorsque vous souhaitez être plus prudent, par exemple, lorsque vous présentez le rapport à un client qui doit budgétiser les travaux :

ora2pg -t SHOW_REPORT --estimate_cost --human_days_limit 5 --dump_as_html > ~/ora2pg-output/migration_report.html
# --human_days_limit 5: any schema above 5 person-days is classified as C-level
# The underlying unit counts do not change -- only the letter classification changes

Les deux drapeaux peuvent être combinés :

ora2pg -t SHOW_REPORT --estimate_cost --cost_unit_value 10 --human_days_limit 5 --dump_as_html > ~/ora2pg-output/migration_report.html

Foire aux questions

Quels privilèges Oracle l'utilisateur ora2pg nécessite-t-il ?

Pour un utilisateur non-dba, les octrois minimums sont :

GRANT CONNECT TO ora2pg_user;
GRANT SELECT ANY DICTIONARY TO ora2pg_user;
GRANT SELECT ON v_$database TO ora2pg_user;

Sélectionner n'importe quel dictionnaire couvre le DBA_* vues de dictionnaire de données statiques qu'ora2pg interroge pour le nombre d'objets. SELECT ON v_$base de données couvre le V$ les vues de performance dynamique — il s'agit d'un type d'objet distinct dans Oracle et nécessitent une autorisation explicite même lorsque Sélectionner n'importe quel dictionnaire est déjà accordée. Les deux subventions sont requises; aucune n'en rend l'autre superflue.

Ensemble USER_GRANTS 1 en ora2pg.conf pour dire à ora2pg de requêter UTILISATEUR_* vues plutôt que DBA_* vues lors de la connexion en tant que propriétaire du schéma. Pour la plupart des évaluations, se connecter en tant que SYSTEM est plus simple et évite complètement les problèmes de privilèges.

Ora2pg fonctionne-t-il avec les bases de données enfichables Oracle 19c ?

Oui, mais vous devez utiliser nom_du_service dans la DSN, pas sid. sid=ORCL se connecte à la racine de la CDB où vos schémas d'application n'existent pas. Utiliser service_name=VOTRE_NOM_PDB — le nom du service PDB est visible dans lsnrctl status sur le serveur Oracle.

Le rapport révèle une estimation de coûts élevée. Qu'est-ce que cela signifie pour la migration ?

Une estimation élevée signifie que le schéma contient une quantité importante de PL/SQL — procédures stockées, packages et déclencheurs — qui nécessitent une réécriture manuelle. Le rapport ne signifie pas qu'une migration est impossible ; il signifie que le travail de réécriture doit être correctement cadré et doté des ressources nécessaires. D'après mon expérience, un schéma de type B-5 avec un effort estimé de 50 à 100 jours-homme représente un engagement de 6 à 8 semaines avec la bonne approche — pas une raison d'abandonner le projet. L'estimation est un point de départ pour le cadrage, pas une réponse définitive.

Puis-je exécuter le rapport sans me connecter à une base de données Oracle active ?

Non. SHOW_REPORT se connecte au dictionnaire de données Oracle pour compter les objets et lire les statistiques. Il ne peut pas fonctionner hors ligne ou avec un fichier d'exportation. La base de données doit être en cours d'exécution et accessible sur le port 1521 depuis la machine Ubuntu.

En résumé

L'installation d'ora2pg sur Ubuntu 24.04 nécessite trois composants dans l'ordre des dépendances : Oracle Instant Client 19.30 (installé via étranger des paquets RPM Oracle), DBD::Oracle (compilé depuis les sources via cpanminus), et ora2pg 25.0 (installé depuis l'archive GitHub — non disponible sur CPAN).

Une fois installé, la commande d'évaluation est sur une seule ligne :

ora2pg -t SHOW_REPORT --estimate_cost --dump_as_html > ~/ora2pg-output/migration_report.html

La sortie donne un score de complexité (A/B/C + 1–5) et une estimation de l'effort en jours-homme. Exécutez-la avant de vous engager sur un calendrier de migration – le numéro qu'elle produit est le chiffre unique qui détermine la portée et les ressources du projet.

Si le rapport revient au niveau B-5 ou C, et que vous avez besoin d'aide pour interpréter les résultats ou définir le travail manuel, prendre contact →