ora2pg-gap-report

Инструмент для оценки миграции Oracle → PostgreSQL Pro (Standard/Certified) до её начала.

Проблема

При миграции с Oracle на Postgres Pro в сегменте Standard/Certified (то есть без лицензии на Postgres Pro Enterprise и без проприетарной утилиты ora2pgpro) единственный доступный автоматический конвертер — открытый ora2pg. По независимым оценкам он закрывает в среднем ~80% задачи перевода PL/SQL → PL/pgSQL. Оставшиеся ~20% (пакеты, автономные транзакции, CONNECT BY, вызовы DBMS_*/UTL_*, составные триггеры) сейчас разбираются вручную и, как правило, обнаруживаются постфактум — когда что-то уже сломалось в проде.

Что делает этот инструмент

Сканирует схему Oracle до миграции и говорит: какие конкретно объекты ora2pg пропустит без предупреждения, недооценит по трудоёмкости или сконвертирует потенциально некорректно — и почему. Не замена ora2pg, а надстройка над ним: список того, что он реально не переносит, проверен эмпирически на открытом PL/SQL-коде (docs/research/step0-show-report-baseline.md), а не взят на веру.

Детекторы

Плюс ora2pg_wrapper.py — запуск ora2pg по типам объектов на выгруженном DDL с парсингом --estimate_cost, и oracle_connector.py/oracle_export.py — живая выгрузка PACKAGE BODY/TRIGGER прямо из Oracle-схемы через DBMS_METADATA.GET_DDL.

Установка и использование

pip install ora2pg-gap-report   # (или: pip install . из клона репозитория)

Сама детекторная библиотека (detectors/, models.py, report_generator.py) — чистый Python без единой внешней зависимости, её можно импортировать отдельно (например, в своих скриптах) вообще без установки чего-либо ещё. У CLI есть одна обязательная зависимость — rich, только ради приятного терминального вывода; ставится сама через pip install.

Сразу после установки доступна команда:

ora2pg-gap-report path/to/schema_dump.pkb another_file.sql

В интерактивном терминале по умолчанию — цветной отчёт: сводная панель (сколько найдено, разбивка по severity, грубая оценка часов), компактная таблица находок и пояснения под каждым сработавшим детектором. Для скриптов/redirect — --format markdown или --format json (тоже работают как формат по умолчанию, если stdout не терминал):

ora2pg-gap-report path/to/schema_dump.pkb --format json --output report.json
ora2pg-gap-report path/to/schema_dump.pkb --format markdown > report.md

# Опционально: линтинг сгенерированного ora2pg кода для CONNECT BY.
# Требует установленный ora2pg (см. https://github.com/darold/ora2pg) —
# единственная внешняя (не-Python) зависимость во всём проекте, и только
# для этой конкретной проверки.
ora2pg-gap-report path/to/schema_dump.pkb --check-connect-by

Файлы с DDL можно передавать как есть — один файл может содержать сразу несколько пакетов/триггеров, детекторы разбирают границы объектов сами.

Пример реального вывода на открытом пакете — docs/examples/logger-autonomous_tx-report.md.

Оценка трудозатрат в отчёте — грубая эвристика по severity (диапазон часов, не точечное число). Это ориентир для планирования, а не откалиброванная на реальных миграциях оценка — не стоит выдавать её клиенту как обязательство.

Выгрузка DDL прямо из Oracle (опционально)

Если под рукой живая Oracle-схема, а не уже готовый DDL-дамп:

pip install "ora2pg-gap-report[oracle]"   # добавляет python-oracledb, thin-режим, без Instant Client

ora2pg-gap-export --dsn host:1521/ORCLPDB1 --user hr --output-dir dumps/
# пароль — из переменной окружения ORACLE_PASSWORD, либо будет запрошен интерактивно

ora2pg-gap-report dumps/*.sql

ora2pg-gap-export — отдельная команда, не флаг у ora2pg-gap-report, специально: выгрузка требует сетевого доступа к Oracle, анализ — никогда. В закрытом контуре это часто две разные машины (jump host с доступом к БД и изолированная рабочая станция для анализа) — единственное, что должно пересечь границу между ними, это уже выгруженные .sql файлы.

Установка без интернета (закрытый контур)

Целевая аудитория этого инструмента — как раз изолированные сети без выхода наружу, поэтому pip install там обычно не вариант. Решение — собрать самодостаточный архив на машине с интернетом, перенести его любым доступным способом (scp/sftp/через jump host/на флешке) и поставить на целевой машине уже совсем без сети:

# На машине с интернетом, из клона репозитория:
python scripts/build_offline_bundle.py --oracle   # --oracle опционально, --dev для pytest
# → ora2pg-gap-report-offline.tar.gz (пакет + rich + всё транзитивно,
#   включая oracledb и его зависимости, если указан --oracle)

scp ora2pg-gap-report-offline.tar.gz user@jump-host:/tmp/
# ...дальше как получится добраться до целевой машины в контуре —
# sftp, ещё один jump host, физический перенос

# На целевой машине БЕЗ интернета:
tar xzf ora2pg-gap-report-offline.tar.gz
cd ora2pg-gap-report-offline
./install.sh oracle        # или: python3 install.py oracle

install.sh/install.py вызывают pip install --no-index --find-links=./wheels ... — pip ставит целиком из положенных рядом .whl-файлов, ни одного обращения в сеть.

rich и его зависимости (markdown-it-py, pygments, mdurl) — чистый Python, один набор wheel-файлов работает везде. oracledb (только при --oracle) собирает платформозависимые wheel — если машина сборки отличается от целевой по ОС/архитектуре/версии Python, передайте --platform/--python-version/--abi в build_offline_bundle.py (см. --help), чтобы скачать wheel именно под целевую платформу, а не под ту, где запущен скрипт.

Архитектура

ora2pg SHOW_REPORT целиком не имеет офлайн-режима — он требует живого подключения к Oracle (ORACLE_DSN). Офлайн от DDL-дампа работает только анализ отдельных типов объектов (-t PACKAGE, -t TRIGGER, -t FUNCTION, …) — именно так работает ora2pg_wrapper.py, а не через SHOW_REPORT. Это принципиально для целевой аудитории — закрытые контуры, air-gapped среды, госсектор.

Три из четырёх детекторов (autonomous_tx, compound_triggers, dbms_utl_calls) анализируют Oracle-исходник напрямую и не требуют установленного ora2pg — чистый Python, без внешних зависимостей. Четвёртый (connect_by) устроен иначе: он линтит сгенерированный ora2pg-код, а не исходник (ora2pg сам неплохо считает CONNECT BY — ценность не в обнаружении, а в проверке качества конвертации), поэтому ему нужен реальный ora2pg и он подключается только через --check-connect-by.

pyproject.toml                 # единственный источник правды по зависимостям/точкам входа
ora2pg_gap_report/
├── models.py                  # Finding — общая структура находки для всех детекторов
├── plsql_lex.py                # общая инфраструктура: маскирование строк/комментариев
│                               # (включая q-quote), сопоставление блоков BEGIN/CASE/IF/LOOP...END,
│                               # разбор идентификаторов — используется всеми детекторами
├── oracle_connector.py         # живая выгрузка PACKAGE BODY/TRIGGER через DBMS_METADATA.GET_DDL
├── oracle_export.py            # консольная команда ora2pg-gap-export
├── detectors/
│   ├── autonomous_tx.py        # PRAGMA AUTONOMOUS_TRANSACTION в PACKAGE BODY
│   ├── compound_triggers.py    # COMPOUND TRIGGER — тихий провал парсинга у ora2pg
│   ├── dbms_utl_calls.py       # классификатор конкретных DBMS_*/UTL_* функций
│   └── connect_by.py           # линтинг сгенерированного WITH RECURSIVE (нужен ora2pg)
├── ora2pg_wrapper.py            # запуск ora2pg по типам объектов, парсинг --estimate_cost
├── cli.py                      # консольная команда ora2pg-gap-report
├── effort_estimator.py          # грубая эвристика по severity, диапазон часов
├── report_generator.py          # JSON + Markdown (машиночитаемые форматы)
└── terminal_report.py           # цветной вывод через rich (единственная зависимость;
                                 #  библиотеки-детекторов не касается, только CLI)
tests/
├── fixtures/                   # реальные захваченные прогоны ora2pg — тесты парсера не требуют
│                               # установленного ora2pg, кроме нескольких live-тестов
│                               # (пропускаются автоматически, если ora2pg не найден в PATH)
docs/research/                  # эмпирическая проверка предпосылок, реальные PL/SQL примеры
docs/examples/                  # примеры вывода детекторов на реальных данных
scripts/
├── build_offline_bundle.py     # сборка автономного архива для установки без интернета
├── oracle-test-compose.yml     # Oracle Free 23ai в Docker для живой проверки
├── setup_oracle_test_schema.sql
└── verify_against_live_oracle.py
.github/workflows/tests.yml     # CI: pytest на 3.10-3.13 + сборка и smoke-test пакета

Тестирование

pip install -e ".[dev]"   # editable-режим + pytest
pytest

Детекторы и лексер проверены на реальном открытом PL/SQL-коде (Logger, alexandria-plsql-utils, составной триггер из Apress), а не только на синтетических примерах.

Проверка на живой Oracle

Юнит-тесты oracle_connector.py идут на fake-соединении (tests/fakes/fake_oracle.py) — быстро, детерминированно, не требует Oracle. Живой путь ("подключился к настоящей Oracle → выгрузил через DBMS_METADATA.GET_DDL → проанализировал") ими не покрыт — для него нужна настоящая база:

docker compose -f scripts/oracle-test-compose.yml up -d
docker compose -f scripts/oracle-test-compose.yml logs -f   # ждать "DATABASE IS READY TO USE"

pip install -e ".[oracle]"
ORACLE_DSN=localhost:1521/FREEPDB1 ORACLE_USER=testuser ORACLE_PASSWORD=testpass1 \
  python scripts/verify_against_live_oracle.py

Скрипт создаёт пару служебных таблиц (scripts/setup_oracle_test_schema.sql — триггерам, в отличие от пакетов, нужна реально существующая целевая таблица), заливает реальные фикстуры из docs/research/samples/ как есть, выгружает их обратно живым DBMS_METADATA.GET_DDL, прогоняет детекторы и сверяет счётчики с уже независимо проверенными на этих же файлах как на тексте (tests/). Если в PATH есть ora2pg — заодно прогоняет SHOW_REPORT против живого подключения.

gvenzl/oracle-free:23-slim — контейнерный пакет официального бесплатного дистрибутива Oracle (тот же движок), просто с более удобной для CI/тестов оберткой, чем прямой образ Oracle Container Registry.

Лицензия

MIT, см. LICENSE.