Cómo instalar ora2pg en Ubuntu y ejecutar un informe de evaluación de migración

En resumen La instalación de ora2pg en Ubuntu 24.04 requiere tres componentes: Oracle Instant Client 19c (para las bibliotecas de conexión de Oracle), el módulo Perl DBD::Oracle (que se vincula a esas bibliotecas) y ora2pg en sí (instalado desde el código fuente; no está en CPAN). Una vez instalado, un solo comando se conecta a su base de datos Oracle, escanea cada objeto en el esquema y produce un informe HTML con una puntuación de complejidad y una estimación de esfuerzo en días-persona. Esta publicación cubre la instalación completa y el comando de informe.

La forma más rápida de saber si una migración de Oracle a PostgreSQL es un trabajo de una semana o un proyecto de tres meses es ejecutar el informe de migración ora2pg antes de abrir una hoja de cálculo.

El informe se conecta a Oracle, cuenta cada objeto por tipo, califica el esquema de A (sencillo) a C (complejo) y produce una estimación de esfuerzo en días-hombre.

Lleva unos veinte minutos instalar y sesenta segundos ejecutar.

Índice

¿Qué produce el Informe de Migración

El comando ora2pg SHOW_REPORT se conecta a tu base de datos Oracle, escanea cada objeto en el esquema y produce una tabla con cinco columnas: tipo de objeto, cantidad de objetos, cantidad de objetos inválidos, costo estimado de migración en unidades y comentarios sobre lo que ora2pg hará con cada tipo.

La última línea da un costo total y una estimación de esfuerzo legible por humanos: “22.40 unidades de costo de migración significan aproximadamente 1 día(s) de persona.

La unidad de migración se estableció en 5 minuto(s).”

La puntuación consta de dos partes: una letra y un número.

La carta refleja una complejidad general:

A — migración que puede ser automatizada en gran medida
B — migración con reescritura de código; coste estimado hasta 10 días-persona
C — migración con reescritura de código; costo estimado superior a 10 días-persona

El número refleja la dificultad técnica:

1 — sin funciones almacenadas, sin disparadores
2 — desencadenantes presentes, no se requiere reescritura manual
3 — funciones almacenadas y/o disparadores, no se requiere reescritura manual
4 — desencadenadores o vistas que requieren reescritura de código
5 — funciones y/o disparadores almacenados que requieren reescritura de código

Un esquema sin código almacenado puntúa A-1. Un esquema con paquetes PL/SQL, disparadores y vistas específicas de Oracle generalmente puntúa B-4 o B-5.

El nivel C se activa cuando el esfuerzo estimado supera las 10 personas-día (ajustable con --límite_días_humanos).

Ejecuta el informe antes de comprometerte con un cronograma.

El número que produce es el único número que vale la pena conocer antes de que comience el proyecto.

Requisitos previos

Se requieren tres cosas, en orden de dependencia:

Oracle Instant Client 19c — las bibliotecas C (libclntsh.so (y relacionados) contra los que el controlador Perl se enlaza en tiempo de compilación y carga en tiempo de ejecución. Sin ellos, no es posible ninguna conexión con Oracle, independientemente del acceso a la red.
DBD::Oracle — el módulo de Perl que proporciona el controlador Oracle. Se compila contra las cabeceras de Instant Client durante la instalación — se requiere el paquete de desarrollo (devel), no solo el tiempo de ejecución básico.
ora2pg 25.0 — instalado desde el código fuente a través de su archivo tar de lanzamiento de GitHub. ora2pg no está disponible en CPAN; cpanm ora2pg fallará.

También necesita acceso de red desde la máquina Ubuntu a la base de datos Oracle en el puerto 1521 y un usuario de base de datos con privilegios suficientes para escanear el esquema (detalles en las preguntas frecuentes a continuación).

Si tu servidor Oracle no está en DNS, agrégalo a /etc/hosts en la máquina Ubuntu antes de continuar:

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

Verificar la resolución de nombres antes de continuar:

ping -c 2 your-oracle-host.localdomain

Si el ping falla, las pruebas de conectividad en el Paso 3 también fallarán; arregla DNS o /etc/hosts primero.

Paso 1: Instalar Oracle Instant Client en Ubuntu 24.04

Oracle distribuye Instant Client solo como paquetes RPM.

Ubuntu utiliza paquetes DEB.

En extraterrestre La herramienta convierte RPM a DEB. Maneja la traducción de metadatos del paquete para que los archivos aterricen en las rutas correctas y el administrado de paquetes rastree la instalación.

Descarga tres paquetes de Descargas de Oracle Instant Client página — use los RPM genéricos de Linux x86-64 para la versión 19.30, no las variantes OL8 u OL9 (esas están compiladas para sistemas de la familia Red Hat y tienen dependencias diferentes):

oracle-instantclient19.30-basic-*.rpm — las bibliotecas compartidas en tiempo de ejecución completas (libclntsh.so, libnnz19.so, y otros)
oracle-instantclient19.30-devel-*.rpm — archivos de cabecera y sdk/ directorio necesario para compilar DBD::Oracle
oracle-instantclient19.30-sqlplus-*.rpm el sqlplus64 binario para probar la conectividad de Oracle independientemente de ora2pg

Transfiere los tres RPM a tu máquina Ubuntu, luego ejecuta:

# 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

Solución de enlace simbólico de Ubuntu 24.04: Ubuntu 24.04 envía la biblioteca de E/S asíncrona como libaio.so.1t64 como parte de la transición a time_t de 64 bits.

Oracle Instant Client se compiló en sistemas Red Hat y codifica de forma rígida libaio.so.1 en su binario ELF.

Sin un enlace simbólico, sqlplus64 falla inmediatamente con no se puede abrir el archivo de objeto compartido: libaio.so.1.

Crea el enlace simbólico antes de hacer la prueba:

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

Establece las tres variables de entorno requeridas y persístelas en ~/.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 indica a DBD::Oracle y ora2pg dónde está instalado Instant Client; ambas herramientas leen esto tanto en tiempo de compilación como en tiempo de ejecución.

LD_LIBRARY_PATH le dice al enlazador dinámico de Linux dónde encontrar las bibliotecas compartidas de Oracle; sin esto, cualquier binario que se enlace con libclntsh.so falla con “error al cargar bibliotecas compartidas”.

RUTA agrega el directorio bin del Instant Client para sqlplus64 está disponible en la línea de comandos.

Verifique la instalación:

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

Si este comando falla con un error de biblioteca después del enlace simbólico, compruebe que LD_LIBRARY_PATH se exporta (no solo se establece) en el shell actual.

Paso 2: Instalar DBD::Oracle y ora2pg

DBD::Oracle es el controlador de base de datos de Perl para Oracle. Es una extensión C — se compila a partir de código fuente contra las cabeceras de Instant Client durante la instalación.

Por eso ORACLE_HOME debe ser exportado antes de ejecutar cpanm DBD::Oracle: el script de compilación lee esa variable para ubicar las cabeceras y enlazar contra las bibliotecas compartidas.

Instala primero las dependencias de compilación:

# 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

Luego instala DBD::Oracle ORACLE_HOME y LD_LIBRARY_PATH debe ser exportado en el shell actual antes de ejecutar esto:

sudo cpanm DBD::Oracle

La compilación tarda entre 2 y 3 minutos. Si falla con un mensaje sobre la falta de encabezados, verifique que el paquete RPM de desarrollo estuviera instalado y que ORACLE_HOME apunta al directorio correcto.

Ahora instala ora2pg desde el archivo tarball de lanzamientos de GitHub. ora2pg no está disponible en CPAN — cpanm ora2pg fallará con “módulo no encontrado”.

La única instalación admitida es desde el código fuente:

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 ..

Verificar

ora2pg --version
# Expected: Ora2Pg v25.0

Paso 3: Configurar la conexión

ora2pg lee /etc/ora2pg/ora2pg.conf por defecto.

La instalación crea /etc/ora2pg/ora2pg.conf.dist como un archivo de referencia con muchos comentarios y cada parámetro disponible documentado.

Cópialo para crear tu configuración de trabajo: el archivo dist sirve como tu copia de seguridad de referencia:

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

El archivo dist es largo (más de 1.000 líneas de comentarios y parámetros).

Utilice ORACLE_DSN en vi para saltar directamente a cada parámetro — no desplaces manualmente.

Establecer estos cinco parámetros:

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: Utilice nombre_del_servicio, no lado. Oracle 19c organiza las bases de datos como Bases de Datos Contenedor (CDB) con una o más Bases de Datos Conectables (PDB). sid=ORCL se conecta a la raíz de CDB; su esquema de aplicación no existe allí. nombre_del_servicio=TU_PDB_NAME se conecta a la PDB donde reside tu esquema. El nombre del servicio de la PDB es visible en lsnrctl status en el servidor de Oracle.

ORACLE_USUARIO: Conéctate como SYSTEM u otro usuario DBA, no como el propietario del esquema. El propietario del esquema normalmente carece de SELECCIONAR EN v$base de datos, lo que provoca que el comando SHOW_REPORT falle. El uso de SYSTEM evita problemas de privilegios durante la fase de evaluación.

ESQUEMA: Limita el escaneo a un esquema. Sin esto, ora2pg escanea todos los esquemas de la base de datos, lo que aumenta significativamente el tiempo de escaneo y produce un informe que mezcla todos los objetos de esquema.

DIRECTORIO_DE_SALIDA: El directorio donde ora2pg escribe los archivos de exportación. Este directorio debe existir antes de ejecutar cualquier comando de ora2pg; ora2pg no lo crea automáticamente.

Crea el directorio de salida:

mkdir -p ~/ora2pg-output

Ejecuta dos pruebas de conectividad antes de proceder al informe.

Las pruebas verifican diferentes capas de la pila. Pasar ambas confirma que la cadena completa de Ubuntu a Oracle funciona correctamente:

# 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 conectividad funciona pero no está seguro de cómo interpretar la salida del informe — o la puntuación es de nivel C y necesita una segunda opinión sobre el alcance — una evaluación a precio fijo cubre exactamente eso

Paso 4: Ejecutar el Informe de Evaluación de Migración

Antes de ejecutar el informe, recopile estadísticas actualizadas del esquema de Oracle. ora2pg deriva sus recuentos de filas y estimaciones de costos de las estadísticas almacenadas en Oracle en el diccionario de datos.

Si las estadísticas están obsoletas — lo que es común en esquemas que no se han analizado recientemente — los recuentos de filas serán inexactos y la estimación del esfuerzo no será fiable.

Ejecute esto en el servidor Oracle como SYSTEM o 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.

RECOPILAR_ESTADÍSTICAS_DEL_ESQUEMA actualiza las estadísticas para el esquema de destino. RECOPILAR_ESTADÍSTICAS_BASE_DE_DATOS actualiza estadísticas para todos los objetos de la base de datos.

RECOPILAR_ESTADÍSTICAS_DEL_DICCIONARIO actualiza las vistas del diccionario de datos de Oracle que ora2pg lee durante el escaneo.

En una base de datos grande este bloque puede tardar varios minutos; en un esquema pequeño como HR se completa en segundos.

Luego ejecuta el informe desde 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

Abrir informe_migracion.html en un navegador.

La versión de texto sin formato es difícil de leer porque las columnas no están alineadas; la versión HTML formatea la tabla limpiamente y es la que se debe compartir con los interesados.

Paso 5: Leer la salida del informe

El informe proporciona una fila por tipo de objeto.

Las columnas son: tipo de objeto, recuento de objetos, recuento de objetos no válidos, costo estimado en unidades de migración y un campo de comentarios que explica qué hará ora2pg con cada tipo.

Presta atención a cuatro cosas:

El nivel de migración — que se muestra en la parte superior del informe como una letra y un número (por ejemplo, B-5). Los esquemas A-1 y A-2 no tienen código almacenado y migran en gran medida de forma automática. Los esquemas B-4 y B-5 tienen procedimientos almacenados o desencadenadores que requieren una reescritura manual en PL/pgSQL. Los esquemas de nivel C superan el umbral de días por persona y requieren un alcance de proyecto formal antes de comprometerse a un cronograma.

Las filas de FUNCTION, PROCEDURE, PACKAGE y TRIGGER — aquí es donde se concentra el esfuerzo manual. Las tablas, secuencias e índices se migran con un mínimo de trabajo manual. El código almacenado no lo hace: cada función, procedimiento y disparador debe revisarse y reescribirse. Un esquema con 200 tablas y cero procedimientos almacenados se migra más rápido que un esquema con 50 tablas y 30 procedimientos almacenados. Los recuentos de objetos en estas filas son los números más importantes del informe.

El recuento de objetos no válidos - la tercera columna de la tabla. Cualquier objeto que el propio Oracle marque como no válido (dependencias rotas, errores de compilación) no se exportará limpiamente. Corrija los objetos no válidos en Oracle antes de ejecutar cualquier exportación - no los lleve a la migración.

La columna de comentarios — ora2pg explica qué hará con cada tipo de objeto y señala los problemas conocidos. Lea atentamente los comentarios de TRIGGER: los triggers BEFORE INSERT basados en secuencias (utilizados para simular auto-incremento en Oracle) se exportan como PL/pgSQL pero deben ser reemplazados con PostgreSQL. IDENTIDAD columnas o GENERADO SIEMPRE COMO IDENTIDAD, lo que requiere una decisión deliberada durante la migración.

Paso 6: Ajustar la Estimación de Esfuerzo

La unidad de costo predeterminada son 5 minutos por unidad de migración.

Esta cifra asume un consultor con experiencia en PostgreSQL realizando el trabajo de reescritura.

Es un punto de partida razonable para la delimitación, pero dos parámetros te permiten ajustarlo para que coincida con el equipo y el apetito de riesgo reales.

--valor_unidad_costo cambia el número de minutos por unidad. El predeterminado es 5. Para un equipo interno que realiza su primera migración de Oracle a PostgreSQL, duplicar a 10 minutos por unidad es más realista: las migraciones por primera vez siempre llevan más tiempo de lo que sugiere la herramienta debido a la sintaxis desconocida, los ciclos de prueba y los casos extremos:

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

--límite_días_humanos establece el umbral por encima del cual el esquema se clasifica como de nivel C. El valor predeterminado es 10 días-persona. Reducirlo a 5 es útil cuando se desea ser más conservador, por ejemplo, al presentar el informe a un cliente que necesita presupuestar el trabajo:

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

Ambas banderas se pueden combinar:

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

Preguntas frecuentes

Qué privilegios de Oracle necesita el usuario ora2pg

Para un usuario que no es DBA, las concesiones mínimas son:

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

SELECCIONAR CUALQUIER DICCIONARIO cubre el DBA_* vistas del diccionario de datos estáticas que consulta ora2pg para el recuento de objetos. SELECCIONAR EN v_$base de datos cubre el V$ vistas de rendimiento dinámico — estos son un tipo de objeto separado en Oracle y requieren un grant explícito incluso cuando SELECCIONAR CUALQUIER DICCIONARIO ya está concedido. Ambas concesiones son necesarias; ninguna hace que la otra sea redundante.

Configurar USUARIO_CONCESIONES 1 en ora2pg.conf para decirle a ora2pg que consulte USUARIO_* vistas en lugar de DBA_* vistas al conectarse como el propietario del esquema. Para la mayoría de las evaluaciones, conectarse como SYSTEM es más sencillo y evita completamente los problemas de concesión.

¿ora2pg funciona con bases de datos enchufables de Oracle 19c?

Sí, pero debes usar nombre_del_servicio en el DSN, no lado. sid=ORCL se conecta a la raíz de la CDB donde sus esquemas de aplicación no existen. Utilice nombre_del_servicio=TU_PDB_NAME — el nombre del servicio PDB es visible en lsnrctl status en el servidor de Oracle.

El informe muestra una estimación de alto costo. ¿Qué significa eso para la migración?

Una estimación alta significa que el esquema tiene una cantidad significativa de PL/SQL —procedimientos almacenados, paquetes y triggers— que requieren una reescritura manual. El informe no significa que la migración sea imposible; significa que el trabajo de reescritura necesita ser delimitado y recibir los recursos adecuados. Según mi experiencia, un esquema de nivel C con un esfuerzo estimado de 50 a 100 días-persona es una tarea de entre 6 y 8 semanas con el enfoque correcto, y no una razón para abandonar el proyecto. La estimación es un punto de partida para la delimitación, no una respuesta final.

¿Puedo ejecutar el informe sin conectarme a una base de datos Oracle activa?

No. SHOW_REPORT se conecta al diccionario de datos de Oracle para contar objetos y leer estadísticas. No puede operar sin conexión o contra un archivo de exportación. La base de datos debe estar en ejecución y accesible en el puerto 1521 desde la máquina Ubuntu.

En resumen

La instalación de ora2pg en Ubuntu 24.04 requiere tres componentes en orden de dependencia: Oracle Instant Client 19.30 (instalado a través de extraterrestre desde los RPM de Oracle, DBD::Oracle (compilado desde el código fuente a través de cpanminus), y ora2pg 25.0 (instalado desde el tarball de GitHub — no disponible en CPAN).

Una vez instalado, el comando de evaluación es una sola línea:

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

La salida proporciona una puntuación de complejidad (A/B/C + 1–5) y una estimación de esfuerzo en días-persona. Ejecútela antes de comprometerse con cualquier cronograma de migración; el número que produce es el único número que determina cómo se debe definir el alcance y los recursos del proyecto.

Si el informe resultante es de nivel B-5 o C y necesita ayuda para interpretar la salida o definir el alcance del trabajo manual, ponerse en contacto