本教學將引導您使用 Visual Studio Code PostgreSQL 擴充功能和 Microsoft Foundry,將 Oracle 資料庫結構描述轉換為 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器或 Azure HorizonDB,並產生及檢閱 PostgreSQL 定義。
內容包括連線至 Oracle 來源資料庫及所選 Azure PostgreSQL 服務上的結構描述驗證資料庫、設定 Microsoft Foundry、執行結構描述轉換工作流程,以及檢閱所產生的 PostgreSQL 產出。 兩個 Azure 服務都支援結構驗證與部署。 開始之前,請確保您擁有 Oracle 來源與結構驗證資料庫的網路存取權限與憑證,以及 Microsoft Foundry 部署。
以下是你在轉換過程中可以期待的內容:
- 結構描述要探索:此工具會分析您的 Oracle 結構描述物件。
- AI 處理:Microsoft Foundry 會處理並轉換相容的物件。
- 結構描述驗證:該工具會嘗試進行編譯,以及可用的靜態檢查。 功能驗證、資料驗證與應用程式驗證仍維持各自獨立。
- 物件審查:使用 Conversion 物件總管 檢查結果,並調整產生的 PostgreSQL 定義。
-
輸出產生:轉換後的 PostgreSQL 物件檔案會儲存在
postgres_ddl,供使用 Setup Experience 進行檢視與部署。
先決條件
在結構描述轉換工作流程中使用這些先決條件。 在開始專案之前,請安裝符合下列需求的擴充功能版本。
系統需求
| 類別 | 詳細資料 |
|---|---|
| Visual Studio Code 版本 | 1.95.2 或更新版本 |
| PostgreSQL 擴充功能 版本 | 最新穩定版本 |
| GitHub Copilot 訂閱 | Pro+、商業或企業版。 在使用 Ask 和 Fix 之前,請先登入。 |
作業系統支援
架構轉換適用以下要求。 有關一般擴充套件支援,請參閱 PostgreSQL 擴充套件所支援的作業系統。
| 作業系統 | 結構描述轉換要求 |
|---|---|
| Windows | x64 或 Arm64 架構。 Arm64 需要 Windows 11。 |
| Linux | x64 或 Arm64 架構,且搭配 glibc glibc 2.35 或更新版本。 |
| macOS | macOS 13 或更新版本。 |
架構驗證資料庫需求
選擇下列 Azure 服務之一來託管結構驗證資料庫:
| Azure 服務 | 服務特定需求 |
|---|---|
| 適用於 PostgreSQL 的 Azure 資料庫 靈活伺服器 | PostgreSQL 版本 15 或更新版本。 |
| Azure HorizonDB | 支援的 PostgreSQL 版本 及叢集的讀寫端點存取權。 |
在您選擇的服務上使用空的或專用、未使用的資料庫。
架構驗證資料庫與部署目的地使用相同的 PostgreSQL 主要版本。 在開始轉換前,請確認所選服務的擴充功能可用性。
AI 模型需求
設定以下模型以進行自動化結構描述轉換。 GitHub Copilot 的協助審查登入與 Foundry 模型連線是分開的。
| AI 元件 | 型號 |
|---|---|
| Microsoft Foundry | GPT-5.2 部署 |
Microsoft Foundry 部署設定
請由具有模型部署權限的管理員建立一個使用 gpt-5.2 Microsoft Foundry 的部署,並安排您的資源存取權限。
Foundry User 提供使用權限,而非管理模型部署或指派角色的權限。 請參閱 Microsoft Foundry 的角色基礎存取控制。
使用建立時指定的部署名稱。它不一定要跟模型名稱相符。
例如,從 Microsoft Foundry 複製您模型部署的資源端點。 https://<resource>.openai.azure.com/ 請使用該資源所提供的端點,而非建立替代主機名稱。 不要在資源端點中輸入專案 URL,也不要附加推論路由或 API 版本查詢參數。
欲了解更多端點格式與推論路由資訊,請參見 Endpoints for Microsoft Foundry Models。
容量規劃請遵循 Foundry 容量建議。 TPM 建議是規模估算指引,而非模型版本的要求。
如果您透過 Azure API 管理 路由 Foundry 流量,請使用已設定的閘道端點,並從精靈中進行測試。 請參閱 「在您的 Foundry 資源中設定 AI 閘道」。
所需的資料庫權限
在執行結構轉換之前,請先與資料庫管理員確認來源元資料存取權及結構驗證資料庫權限。 Oracle 帳號需要存取結構的元資料和字典視圖,而不是應用程式列的資料。 PostgreSQL 帳號必須能夠刪除並重新建立相應的 schema,並建立用於驗證的物件。 盡可能使用專用帳號,並遵守最低權限原則。
源 Oracle 權限
請使用 支援的 Oracle 版本。 來源 Oracle 資料庫需要以下權限:
| 特權 | Purpose |
|---|---|
| 連線 | 基本資料庫連線 |
| SELECT_CATALOG_ROLE | 存取資料字典視圖 |
| SELECT ANY DICTIONARY | 讀取系統元資料與字典物件 |
SELECT SYS.ARGUMENT$ |
存取程序與函式參數資訊 |
SELECT SYS.V_$RESOURCE_LIMIT |
透過 V$RESOURCE_LIMIT 存取工作階段與程序使用率及限制 |
架構驗證資料庫權限
在選取的結構描述驗證資料庫上設定下列存取權限。 資料庫層級 CREATE 並不會授與捨棄其他角色擁有的結構描述的權限。
| 存取 | Purpose |
|---|---|
資料庫的 CONNECT |
連線以進行轉換與驗證。 |
資料庫的 CREATE |
建立驗證結構描述。 |
| 具備相符結構描述的所有權,或具備適當授權的角色 | 重新建立前,先刪除相符的 schema。 |
| 在驗證結構描述中建立物件的權限 | 建立並編譯轉換後的定義。 |
| 安裝擴充功能的權限,或管理員協助 | 安裝用於轉換與驗證所需的擴充功能。 |
網路要求
- 出站連線:Microsoft Foundry 端點。
- 資料庫連線:來源 Oracle 及所選 適用於 PostgreSQL 的 Azure 資料庫 靈活伺服器或 Azure HorizonDB 叢集。
- HTTPS 存取權限:Visual Studio Code Extensions Marketplace 與 GitHub Copilot 服務。
- GitHub 儲存庫存取:https://github.com/microsoft/pgsql-tools/。
Oracle Instant Client (用於完整用戶端模式)
當它偵測到可載入的 Oracle 用戶端函式庫時,擴充功能會使用厚模式;當偵測不到任何用戶端時,則採用薄模式。 偵測到無法載入的用戶端是設定錯誤,而非成功的備援。 如果模式變更需要新程序,請重新啟動 Visual Studio Code。 請參閱 PostgreSQL 擴充套件的發行說明。
精簡模式不需要 Oracle Client 函式庫。 需要 Oracle 原生網路加密或校驗和的連線需要 thick mode。 請與您的 Oracle 資料庫管理員一起檢視來源伺服器的政策,並在執行 Visual Studio Code 的機器上設定用戶端。
| 原則 | 來源伺服器設定 | 用戶端設定 |
|---|---|---|
| 原生網路加密 | SQLNET.ENCRYPTION_SERVER |
SQLNET.ENCRYPTION_CLIENT |
| 資料完整性校驗和 | SQLNET.CRYPTO_CHECKSUM_SERVER |
SQLNET.CRYPTO_CHECKSUM_CLIENT |
在 sqlnet.ora中, REQUIRED 拒絕無法符合政策的連線; REQUESTED 與另一端點協商服務。 這些設定不能互換。 不要為了繞過用戶端設定錯誤而削弱伺服器政策。 請參閱 Oracle 網路加密與資料完整性。
準備 Thick 模式:
- 從 Oracle Instant Client downloads 下載並安裝適用於轉換機器作業系統與架構的 Oracle Instant Client Basic 或 Basic Light 套件。
- 請依照 Oracle 針對相依性、函式庫搜尋路徑及網路設定檔的平台專用安裝指示操作。
- 重新啟動 Visual Studio Code 並測試 Oracle 連線後再繼續。
Microsoft Foundry 認證
為 Microsoft Foundry 設定以下其中一種認證方法:
| 驗證方法 | Requirements |
|---|---|
| API 金鑰 | 資源端點以及來自同一 Foundry 資源的 API 金鑰,且貴組織允許基於金鑰的驗證。 金鑰並非特定於某一部署。 |
| Microsoft Entra 身份識別 | 在承載部署的資源上,具有 Foundry User 角色(前稱 Azure AI 使用者)的身份。 在精靈中選擇帳戶和租戶,並在提示時完成登入。 |
有關角色與驗證的詳細資訊,請參閱 Microsoft Foundry 中的驗證與授權。 避免資源金鑰出現在原始檔案和共享報告中。
結構描述轉換程序
本節將帶您了解轉換流程。 您需要安裝擴充功能、初始化專案、連接 Oracle、檢視 Discovery,並設定結構驗證資料庫與 Microsoft Foundry。 轉換會嘗試在結構描述驗證資料庫中進行編譯及所有可用的靜態檢查。 接著你檢視並優化輸出,部署到你選擇的資料庫,並獨立驗證其行為。
在此工作流程中,此擴充功能的使用者介面會使用像 Migrations、Create Migration Project 和 Migrate 這樣的標籤。 這些標籤並不表示結構轉換會移動資料列。
以下螢幕截圖顯示不同移轉執行中的範例。 Project 名稱與物件數量在不同影像之間可能有所不同。
步驟 1:安裝 PostgreSQL Visual Studio Code 擴充功能
打開 Visual Studio 程式碼。
前往 擴充功能 檢視(
Ctrl+Shift+X)。搜尋 PostgreSQL,並開啟由 Microsoft 發佈的 PostgreSQL 擴充套件詳細資訊。
安裝或更新擴充功能至最新穩定版本。
使用與您訂閱相關聯的帳戶登入 GitHub Copilot。 開啟 Copilot Chat,確認貴組織的政策是否允許協助審查功能。 請參閱在 Visual Studio Code 中設定 GitHub Copilot。
Copilot 登入不會設定 Foundry 資源,而 Foundry API 金鑰也不會讓你登入 Copilot。 在將結構描述定義傳送給任一服務之前,請先參閱成本與資料處理常見問題。
步驟 2:建立結構描述驗證資料庫連線
使用此連線進行結構驗證。 使用一個空的或專用、未使用的資料庫,且不包含任何需要保留的資訊。 您執行安裝程式時會選擇部署目的地。
在 PostgreSQL 擴充面板中,建立連接至 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器或承載結構驗證資料庫的 Azure HorizonDB 叢集的連線。 對於 Azure HorizonDB,請使用叢集的讀寫端點。
輸入連線資訊(主機、資料庫、使用者名稱、密碼)。
測試並儲存連線。 有關連線選項,包括 Browse Azure,請參閱 連線與身分識別。
步驟三:開啟新工作區
步驟 4:建立結構轉換專案
步驟 5:設定專案設定
在 遷移精靈中輸入 你的專案名稱。
選取 下一步 以繼續。
此截圖中的先決條件清單適用於 API 金鑰驗證。 您也可以使用 Microsoft Entra ID 驗證。
步驟 6:設定 Oracle 連線
輸入您的 Oracle 連線資料:
Field Description Oracle 主機名稱 來源伺服器的主機名稱或 IP 位址。 Oracle 連接埠 聆聽埠,通常為 1521。Oracle SID 或服務名稱 來源資料庫的 SID 或服務名稱。 Oracle 使用者名稱 具有所需元資料權限的使用者。 Oracle 密碼 來源使用者的密碼。 在連線前,請在執行 Visual Studio Code 的機器上準備好 Oracle 用戶端設定。 用戶端偵測會選擇模式;本頁沒有提供手動的細/厚選擇器。
選擇 載入結構。 工具會
ALL_USERS測試 Oracle 連線,從 Oracle 檢視中讀取結構名稱,並將系統結構排除在選取清單之外。選取一個或多個要轉換至 Azure PostgreSQL 的應用程式結構描述。
選擇 下一步:探索。
步驟七:檢視 Discovery 結果
探索顯示來源清查及規劃的擷取範圍。 此階段不會提取 DDL。 關於摘要計數與範圍的說明,請參閱 結構描述轉換概觀中的探索部分。
等待 Discovery 完成。
在 來源權限下,檢視每項檢查、目的及結果。 請與您的 Oracle 資料庫管理員檢視未成功的檢查。 解決權限問題後,選擇 Refresh Discovery 並檢視更新後的結果。 關於所需權限,請參閱 來源 Oracle 權限。
檢視 已發現、 待擷取、 排除及 無效物件 的摘要計數。
展開 支援物件類型,以檢視 待擷取、排除 及 無效物件 的各類型計數。 支援型態仍可包含排除物件;這些計數並非轉換結果。
展開 「未支援物件類型 」以檢視來源中未受支援的類別。 有關支援細節及 PostgreSQL 替代方案,請參見 Schema conversion 限制。
在 [相依結構描述] 下方,檢閱您未選取但被參考的結構描述。 選取 [顯示圖表] 以檢視參考。 連線上的數字代表依賴性參考,而非需擷取或轉換的物件數量。 如果您打算在此專案中轉換應用程式結構描述,請在選取中包含被參照的應用程式結構描述。 否則,請規劃如何在 Azure PostgreSQL 中提供或取代所需的定義。 圖中顯示的相依性不會自動成為所選的 schema。
請檢閱有關未轉換之參照 Oracle 系統結構描述的個別通知。 請勿將這些參考當作選擇用於轉換的額外應用程式結構描述。
如果你需要更改結構描述選擇,請選擇上一頁以返回連線至 Oracle,更新結構描述,然後再次選擇下一步:探索。 在繼續前,請先檢視更新後的範圍。
選擇 我已檢視物件、排除項目和相依結構。
選擇 下一步:PostgreSQL 連線。
步驟 8:設定結構描述驗證資料庫
在 適用於 PostgreSQL 的 Azure 資料庫 靈活伺服器或 Azure HorizonDB 上使用空或專用、未使用的結構驗證資料庫,且不需要保留任何物件或資料。 如需準備指引,請參閱 「準備結構驗證資料庫」。
Warning
轉換會使用 DROP SCHEMA ... CASCADE,刪除相符的結構描述並重新建立。 此動作會刪除其現有物件與資料,並可移除其他結構描述中相依的物件。 在確認此操作之前,請先確認所選連線與資料庫。
選取目標平台:Azure HorizonDB 或 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器。
在 PostgreSQL 連線中,選取您為該服務定義的連線。
在 PostgreSQL 資料庫中,選取結構驗證資料庫。
檢視資料庫 檢查中的自動結果,包括伺服器相容性與擴充功能。 在繼續之前先解決阻斷性錯誤。 對於缺少的擴充功能,請依照服務專屬的準備指引,允許並安裝您轉換後結構所需的擴充功能,然後選取 再次檢查。 缺少相依關係可能會阻止個別物件編譯,即使警告並未阻止繼續。
勾選確認框,確認在轉換過程中,與所選 Oracle 架構相符的結構會被刪除並重新建立,並刪除其現有物件與資料。
選擇下一頁:Microsoft Foundry 模型配置。
步驟 9:配置 Microsoft Foundry 語言模型
為了達到轉換輸送量,建議的部署容量應大於 1,000,000 個權杖/分鐘 (TPM)。 請根據您的結構描述及共用此部署的其他工作負載調整容量,並監視節流情況。 請參見配置 Microsoft Foundry 容量。 範例顯示 230 萬 TPM;其可用配額是針對該環境而定的。
返回 Visual Studio Code 精靈以設定模型連線:
輸入模型連接細節:
Field Value 型號名稱 gpt-5.2。Microsoft Foundry 端點 您部署的資源端點。 部署名稱 您為部署指定的名稱;它可能與模型名稱不同。 選擇 認證方式:
- API 金鑰:輸入承載部署的 Foundry 資源中的 API 金鑰。
- Microsoft Entra ID:選擇您的 Azure 帳戶與租戶,並在提示時完成登入。 使用 Microsoft Foundry 驗證中所述具有資源存取權的身分。
選擇測試 Microsoft Foundry 連線以驗證設定。
連線成功後,選擇 Create Migration Project。
成功的連線測試並無法證明是否有足夠的容量來持續進行轉換工作負載。
步驟 10:執行結構描述轉換
系統會導覽至主要的 遷移精靈。
選擇 遷移 以開始架構轉換程序。
在 Visual Studio Code 介面中監控轉換進度。
轉換完成後,專案顯示 [結構描述轉換完成],以及 [檢閱轉換摘要] 動作。
如果執行失敗或中斷,請保留專案並遵循 轉換失敗指引。 不要把未完成的執行當成已完成的轉換。
步驟 11:檢視結構轉換報告
- 結構轉換完成後,HTML 轉換報告會自動開啟。
- 檢視發現、擷取與轉換結果及物件層級的備註。
- 關於如何解讀報告的指引,請參閱 「檢視 Oracle 架構轉換的 HTML 報告」。
步驟 12:檢閱並微調轉換後的物件
在已完成的結構描述轉換專案中,選取檢閱轉換摘要。
在 [轉換摘要] 頁面上,選取 [轉換物件總管]。
選取一個物件以開啟其 diff 檢視,比較其 Oracle 與 PostgreSQL 的定義,並閱讀其轉換說明。
請使用 Ask 來解釋轉換及其相依關係,或使用 Fix 以 Copilot 協助修正物件及其相依物件。 成功編譯後,已更正的相依物件會自動解決。
當 PostgreSQL 擴充套件中設定多個連線時,透過 Fix 執行 SQL 會開啟連線選擇提示。 選取結構驗證連線,然後在資料庫選擇快顯視窗中選取包含已轉換結構的資料庫。
若要手動修正,請編輯並儲存在
postgres_ddl中由工具產生的對應 PostgreSQL 檔案。 檢視物件 diff 視圖中 PostgreSQL 端的每個語句。在選擇 Play 前,請先確認目前的連線與資料庫。 如有需要,請切換至結構驗證目的地。 diff 檢視可在不提示的情況下重複使用先前的連線與資料庫。
對於現有的資料表,
CREATE TABLE IF NOT EXISTS則不會更新其定義。 在ALTER TABLE中,針對同一結構驗證資料庫分別套用經審查的 陳述式。 將修正後的建立定義保留在postgres_ddl中相符的工具產生檔案中。在物件的差異檢視中選取播放按鈕,以執行 PostgreSQL 端的所有 SQL。 選取文字不會限制執行。 若系統提示,請選擇結構驗證連線,然後選擇包含已轉換結構的資料庫。
檢視編輯與編譯結果,包括相依物件的變更。 確認修正已套用於所選資料庫。 將所有手動編輯或 修正 修正儲存在相應工具產生的檔案中,並
postgres_ddl檢視 設定輸入與部署範圍。如果物件更正後需要手動更新狀態,請選取解決,將其標記為已轉換。
在轉換物件總管中選取重新整理,以使用修訂後的狀態更新轉換報告。
以下轉換 摘要 範例顯示物件修正後更新的計數。 上方的 Conversion 物件總管 截圖顯示了這些修正前的狀態。
有關篩選、相依性修正、狀態更新及手動編譯步驟,請參閱在 Conversion 物件總管 中檢閱已轉換的物件。 「已轉換」狀態不會取代獨立驗證。
步驟 13:使用設定體驗準備部署
轉換工作流程完成後會自動產生設定檔案。 部署執行時,安裝程式會讀取工具產生的物件檔案 postgres_ddl中最新儲存的內容,包括在設定檔產生後所做的修正。 手動新增到 postgres_ddl 的檔案會被安裝程式忽略。 打開設定說明並不會啟動部署。
- 在已完成的架構轉換專案中,選擇檢視轉換摘要。
- 在 轉換摘要 頁面,選擇 設定說明。 當設定檔準備好時,這個動作就會啟用。
- 檢視產生的
setup_instructions.md檔案,該檔案會在編輯器中開啟。 Visual Studio Code 也會在檔案總管中顯示設定資料夾。 - 請依照「部署已轉換結構」的設定體驗,在 適用於 PostgreSQL 的 Azure 資料庫 彈性伺服器或 Azure HorizonDB 上準備您選擇的目標資料庫,執行準備檢查、部署轉換後的架構,並檢視部署結果。
步驟 14:在生產環境使用前驗證已部署的結構
選擇用於功能、資料及應用程式測試的資料庫。 確認其中包含您打算驗證的轉換後結構描述。
對於對現有資料表進行手動編輯, CREATE TABLE IF NOT EXISTS 則不會更新該資料表。 分別在ALTER TABLE中套用經過審查的 陳述式,並將修正後的建立定義儲存到 postgres_ddl 中由工具產生的對應檔案。
差異檢視中的播放按鈕會執行 PostgreSQL 端的所有 SQL。 選取文字不會限制執行。 diff 檢視可在不提示的情況下重複使用先前的連線與資料庫。
部署後對物件進行手動修正:
- 在 Conversion 物件總管 中,選取物件以開啟其差異檢視。
- 進行修正後,將相符的工具產生檔案儲存在
postgres_ddl中。 檢視差異檢視右側更新後的 PostgreSQL 定義。 - 檢視 Schema 參照以及 diff 檢視中 PostgreSQL 端的每個陳述式。
- 在選擇 Play 前,請先確認目前的連線與資料庫,如有需要即可更改。 若要在結構驗證資料庫中進行更正,請使用先前為結構驗證選取的連線與資料庫。 對於部署在其他位置的結構描述,請使用其連線和資料庫。
- 在差異檢視中選取播放按鈕。 若系統提示,請選擇預期連線,然後選擇包含已部署結構描述的資料庫。
- 在繼續前,請檢視執行輸出並解決錯誤。 驗證所選資料庫中已更新的物件定義。
- 將修正後的物件定義儲存在其工具產生的檔案中,位於
postgres_ddl下,以便未來部署使用測試過的修正。 編輯檔案本身不會將變更套用到已部署的資料庫。 - 如有需要,請在 Conversion 物件總管 中使用 Resolve 更新已修正物件的狀態,然後選擇「重新整理」以更新轉換報告。
使用具代表性的測試資料與應用程式工作負載,獨立驗證已部署的結構描述。 根據 Oracle 來源驗證相依、約束、業務邏輯和結果集,修正後再重新測試。 檢視任何未轉換或部署的物件,而非只測試成功的轉換。
Important
Foundry 負責產生初始轉換,Copilot 則協助審核與修正。 AI 輸出或成功編譯,都無法證明應用程式行為等效。 在正式部署前,獨立驗證轉換後的物件、手動修正及安全控管。
欲了解更多關於 Visual Studio Code 擴充功能的資訊,請造訪 Visual Studio Code 與 Cursor 的 PostgreSQL 擴充功能。