使用 Modernize CLI(預覽版)將依賴 Oracle 的應用程式遷移至 PostgreSQL

使用 Modernize CLI 評估依賴 Oracle 的應用程式程式碼,並建立轉換成 PostgreSQL 的計畫。 此工作流程支援 Java 與 .NET 應用程式,使用應用程式來源及可選的匯出資料庫定義,取代連線至實際目標資料庫。

Important

Modernize CLI 中的 Oracle 到 PostgreSQL 應用程式遷移目前處於公開預覽階段。 此工作流程會變更應用程式程式碼;它不會遷移資料庫伺服器或客戶資料、部署雲端基礎架構,或建立正式上線準備。 本文中的工作流程使用本機執行。

支援的案例

評估識別應用程式提供者、設定、SQL、ORM 映射、序列及例行呼叫中的活躍 Oracle 依賴。 特定語言的轉換技能包括:

應用程式 轉換範圍的範例
JAVA Oracle JDBC、JPA/Hibernate 映射、SQL、序列、常式介面契約、測試以及驅動程式封裝。
.NET Oracle.DataAccess 與 Oracle.ManagedDataAccess、ADO.NET、Dapper、EF/EF 核心對應、SQL、常式合約、Npgsql、測試以及發佈輸出。

此工作流程不適用於僅支援 PostgreSQL 的應用程式、非 Oracle 原始碼遷移,或資料庫伺服器評估。 此工作流程針對應用程式程式碼或設定所使用的 Oracle 相依性。 僅在說明文件中或未使用的 Oracle 函式庫中找到的 Oracle 參考,並不足以識別遷移目標。

此以原始程式碼為基礎的工作流程支援 Java 與 .NET 應用程式,並可使用選用的 PostgreSQL DDL 匯出內容來協助轉換。 它不需要即時資料庫連線或應用程式停機時間,也不會自動新增 Azure 管理式識別或變更應用程式的驗證政策。 獨立的 Oracle 到 PostgreSQL Java 遷移體驗提供一項 Java 遷移任務,更新資料庫用戶端以進行管理身份驗證,並轉換 SQL,並可選擇使用資料庫結構轉換時產生的程式碼備註。

Prerequisites

  • Modernize CLI 及其 GitHub 驗證的先決條件。
  • Oracle 相依的 Java 或 .NET 應用程式本機原始碼副本。
  • Node.js 22 或更新版本,可作為 node 於你的 PATH 上使用。 這項要求適用於遷移協助者;Modernize CLI 內建的執行環境並不會取代它。 不需要 npm 執行時套件。
  • 轉換時,使用應用程式的 JDK 與建置工具,或其 .NET SDK 與建置工具。
  • 用於 PostgreSQL 執行階段驗證,需要可執行暫時性本機 PostgreSQL 容器的 Docker 引擎。
  • 在原始碼轉換前,附加的 Git 分支上需有已提交的應用程式基線。

評估不會建置或測試應用程式、執行 Docker、連接資料庫或變更應用程式來源。 執行前請先準備相依性;評估不會安裝工具或進行互動式驗證。

提供可選的資料庫定義

你可以僅根據應用程式程式碼進行評估與轉換。 若要提供目標結構契約,請在應用程式儲存庫 .github\modernize\oracle-postgres.json中新增此可選檔案:

{
  "postgres-ddl-folder": "database\\postgres",
  "options": ["tests"]
}

將這些設定與任何既有的組態合併,而不是取代原有組態。

Setting Purpose
postgres-ddl-folder 唯讀 PostgreSQL DDL 匯出,無論是單一物件檔案或僅結構模式的傾印。
oracle-ddl-folder 可選且獨立的原始 Oracle 定義,以協助保留來源行為。
oracle-schema 提供 Oracle DDL 資料夾時所使用的精確比對 Oracle 綱要選取器。
options 要明確啟用的轉換動作,如下表所述。
Option Purpose
tests 啟用基準支援、測試產生及故障測試修復。

轉換動作必須明確啟用。 省略的動作仍保持關閉狀態。

所有設定及設定檔本身皆為選用。 相對路徑從應用程式根目錄解析。 省略僅程式碼操作的 DDL 設定;明確指定的缺少、空白或無效資料夾屬於錯誤,而非回退為僅程式碼評估。

使用專用且僅結構型的 UTF-8 匯出資料夾。 不要包含客戶資料、檔案系統連結或可執行的 SQL 客戶端包含內容。 支援的 PostgreSQL 檔案副檔名包括 .sql、.ddl、.psql、.trg、.pgsql、.fnc、.prc及 .vw。 文字和 Markdown 筆記會被忽略。 物件識別來自 DDL 宣告,而非檔名。

DDL 快照描述的是匯出的合約,而非即時資料庫的內容或權限。 匯出中缺失的物件並不代表在即時資料庫中不存在。 明確檢視模糊的常式多載與不支援的語法結構。

請勿在此設定中新增認證或即時連線設定檔。 持久目標寫入以及選項如 和 create-persistent-ddltest-target-writes 不支援。 DDL 路徑是儲存庫設定,而非新的 modernize assess 命令列旗標。

評估應用程式就緒狀態

額外的資料庫評估技能需要完整分析。 預設的 「僅問題」 設定不會執行它。

互動模式(TUI)

  1. 從您的應用程式目錄執行現代化代理程式:

    modernize
    
  2. 從主選單選擇 評估 。

  3. 選擇「目前資料夾」以評估您的應用程式,或選擇「手動輸入」以輸入本機應用程式的路徑。

  4. 選擇與您的應用程式相關的評估領域,然後繼續前往評估設定。

  5. 在 「一般/分析覆蓋範圍」 下,選擇 「完整分析」,然後選擇 「繼續」。

  6. 選擇 「本地評估」。

  7. 輸入輸出路徑或接受預設值,然後開始評估。

CLI 會使用儲存庫證據,在適用時選擇 Oracle 到 PostgreSQL 的應用程式評估。 如需有關互動式畫面的更多資訊,請參閱 「批次評估:互動模式」。

無頭模式

建立一個評估設定檔,例如 C:\configs\database-assessment.yml,並設定如下:

analysisCoverage: full

將此設定與任何現有設定合併,而非取代其他評估設定。 依照下列指令所示,將檔案傳遞至 --assess-config ,並以您自己的路徑取代來源、設定與輸出路徑:

modernize assess `
  --source C:\src\oracle-app `
  --assess-config C:\configs\database-assessment.yml `
  --output-path C:\reports\oracle-app `
  --format markdown `
  --delegate local `
  --no-tty `
  --prompt 'Assess Oracle-to-PostgreSQL application-code migration readiness.'

或者,在 Windows 上,透過設定 %USERPROFILE%\.modernize\assessment-config.yaml,更新位於 assessment-config.yaml 的現有使用者層級 analysisCoverage: full 檔案。 如果你使用該檔案,請在指令中省略 --assess-config。 明確指定的 --assess-config 路徑會優先於使用者層級檔案。

Note

選填 --prompt 欄位描述您對額外資料庫評估技能的目標或範圍。 這並不會改變 Modernize CLI 內建的 AI 分析功能。 使用儲存庫設定來設定 DDL 路徑與轉換選項;提示詞不會設定這些設定。

您可以省略 --prompt。 啟用 完整分析 時,CLI 會使用資料庫證據在適用時選擇 Oracle 對 PostgreSQL 應用程式的評估。 評估評估移民準備度;它不會轉換應用程式程式碼。 轉換作業會在計畫執行期間另外進行。

檢視評估報告

開啟產生的應用程式報告,並依照 Oracle 的 PostgreSQL 應用程式準備度。 外部報告會以獨立index.mdindex.html或獨立的形式發佈在目前儲存庫報告的externals\oracle-to-postgresql-app-assessment目錄下。

評估執行有界、唯讀靜態檢查。 完成的報告表示報告產生完成,而非應用程式轉換或執行時驗證通過。

  • 如果評估未發現 Oracle 應用程式的活躍使用,工作流程會跳過評估,而非製作遷移報告。
  • 若評估不完整,請在規劃轉換前檢視報告的範圍限制。
  • 如果你提供了無效的 DDL,請先修正並重新執行,而不要認定結果只會是純程式碼。

評估不會自動建立轉換任務。 接著制定並檢視現代化計畫。

建立轉換計畫

先從一次性、已提交的樣本或測試分支開始。 請使用一個將隔離的本地驗證與禁止存取客戶資料庫的請求區分開來:

$request = @'
Migrate this Oracle-dependent Java application to PostgreSQL using the offline
application adapter and the optional repository DDL and test configuration.
Allow disposable task-owned local PostgreSQL Docker containers for validation
of real application JDBC and ORM paths with synthetic data and cleanup.
Do not access customer or production databases, deploy cloud infrastructure,
change authentication policy, or perform unrelated framework upgrades.
'@

modernize plan create $request `
  --source C:\src\oracle-app `
  --language java `
  --plan-name oracle-postgres `
  --assess-file-path C:\reports\oracle-app\reports\report-<id>\index.md `
  --delegate local `
  --no-tty

請以您評估執行時實際列印的應用程式評估報告路徑取代該 --assess-file-path 值,包括任何儲存庫及版本化報告目錄。 不要字面上照抄佔位符 <id> 。

如需更多規劃選項,請參閱 「現代化 CLI 指令參考:規劃建立」。

對於 .NET 應用程式,請將請求變更為描述 .NET 應用程式及其 ADO.NET 或 ORM 路徑,並使用 --language dotnet。

執行前,請檢視產生的計畫與任務清單:

  • 對於 Java,請確認轉換任務是否使用 migration-oracle-to-postgresql-app-java。
  • 對於 .NET,請確認它使用 migration-oracle-to-postgresql-app-dotnet。
  • 將轉換控制在預期的應用程式邊界內,並保留無關的提供者與公開行為。
  • 允許由任務擁有的本機 PostgreSQL Docker 驗證。 不要強加僅限使用 mock 的限制,也不要將本地測試容器與雲端部署混淆。
  • 檢視基準、建置、測試、封裝和清理方面的需求。

現有的 Java migration-oracle-to-postgresql 技能是不同的工作流程。 不要用它來取代離線應用程式介面卡。

執行並驗證

檢視計畫後,執行:

modernize plan execute `
  --source C:\src\oracle-app `
  --language java `
  --plan-name oracle-postgres `
  --delegate local `
  --no-tty

使用 --language dotnet 作為 .NET 計劃。 Modernize CLI 管理任務排序、進度、分支與提交作業。

轉換利用應用程式證據更新提供者、設定、SQL、對應、例行合約及封裝,並在已審查的範圍內進行。 它不會進行無關的架構、框架或身分驗證變更。

執行時驗證使用真實應用程式的資料庫存取路徑,針對任務專屬的可拋棄 PostgreSQL 容器,並結合合成資料、斷言與清理。 光靠編譯和模擬物件,並不能證明與 PostgreSQL 相容。

若無法使用 Docker,依賴驗證將不完整。 這個工作流程預設不會安裝 Docker 或啟動 Docker 桌面版。 啟動已安裝的 Docker Desktop,需要在儲存庫組態中明確指定 start-docker-desktop 選項。

解讀轉換結果

在 oracle-postgres\<task-id> 的計畫工作資料夾下檢視任務證據,包括 conversion-report.md、conversion-state.json 及其後的項目。 檢查變更後的檔案、問題處置結果、原生測試結果、封裝、Docker 夾具清理及剩餘動作。

結果 Meaning
RUNTIME_VALIDATION_NEEDED 最強的離線轉換結果。 即使部分 Docker 測試通過,客戶目標驗證與生產準備檢查仍是必要的。
PARTIAL 所需行為被延後,或必要的驗證失敗或無法執行。 不要把這個結果當成已經完成的遷移。

這兩種結果都不代表正式環境 READY。 在正式部署部署前,驗證部署專屬的架構、權限、驗證、代表性工作負載及營運行為,並可於您自身受控環境中進行。 遷移資料庫資料與佈建目標服務是兩項分開的活動。