你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

教程:将 Oracle 架构转换为 Azure PostgreSQL

本教程介绍如何使用具有 Microsoft Foundry 的 Visual Studio Code PostgreSQL 扩展生成和查看 PostgreSQL 定义,将 Oracle 数据库架构转换为Azure Database for PostgreSQL灵活服务器或 Azure HorizonDB。

它介绍了如何连接到 Oracle 源和所选 Azure PostgreSQL 服务上的架构验证数据库、配置 Microsoft Foundry、运行架构转换工作流以及查看生成的 PostgreSQL 项目。 Azure服务都支持架构验证和部署。 在开始之前,请确保具有 Oracle 源和架构验证数据库的网络访问和凭据,以及 Microsoft Foundry 部署。

以下是转换期间可以期待的内容:

  • 架构发现:该工具分析 Oracle 架构对象。
  • AI 处理:Microsoft Foundry 处理并转换兼容的对象。
  • 模式验证:该工具尝试进行编译,并执行可用的静态检查。 功能、数据和应用程序验证保持独立。
  • 对象查看:使用转换对象资源管理器检查结果并优化生成的 PostgreSQL 定义。
  • 输出生成:已转换的 PostgreSQL 对象文件保存在 postgres_ddl 中,以便通过安装体验进行评审和部署。

先决条件

架构转换工作流需满足以下先决条件。 在启动项目之前,安装满足以下要求的扩展版本。

系统要求

类别 详细信息
Visual Studio Code版本 1.95.2 或更高版本
PostgreSQL 扩展 版本 最新稳定版本
GitHub Copilot订阅 Pro+、Business 或 Enterprise。 使用 Ask 和 Fix 之前登录。

操作系统支持

以下要求适用于架构转换。 有关常规扩展支持,请参阅 PostgreSQL 扩展所支持的操作系统。

操作系统 架构转换要求
Windows x64 或 Arm64 体系结构。 Arm64 需要Windows 11。
Linux x64 或 Arm64 体系结构,glibc 2.35 或更高版本。
macOS macOS 13 或更高版本。

架构验证数据库要求

选择以下Azure服务之一来托管架构验证数据库:

Azure服务 特定于服务的要求
Azure Database for PostgreSQL 灵活服务器 PostgreSQL 版本 15 或更高版本。
Azure HorizonDB 支持的 PostgreSQL 版本和对群集的读写终结点的访问权限。

在所选服务上使用空或专用的未使用数据库。

对架构验证数据库和部署目标使用相同的 PostgreSQL 主版本。 在开始转换之前验证所选服务的扩展可用性。

AI 模型要求

配置以下模型进行自动架构转换。 GitHub Copilot用于辅助评审的登录与 Foundry 模型连接分开。

AI 组件 Model
Microsoft Foundry GPT-5.2 部署

Microsoft Foundry 部署配置

让具有模型部署权限的管理员创建使用gpt-5.2模型的Microsoft Foundry 部署,并安排你的资源访问权限。 Foundry 用户 提供使用访问权限,而不是管理模型部署或分配角色的权限。 请参阅 Microsoft Foundry 的基于角色的访问控制。

使用创建期间分配的部署名称;它不必与模型名称匹配。

从 Microsoft Foundry 复制模型部署的资源终结点,https://<resource>.openai.azure.com/例如。 使用为该资源提供的终结点,而不是构造备用主机名。 不要输入项目 URL 或将推理路由或 API 版本查询追加到资源终结点。

有关终结点格式和推理路由的详细信息,请参阅 Microsoft Foundry 模型的终结点。

对于容量规划,请遵循 Foundry 容量建议。 TPM 建议是调整大小指南,而不是模型版本要求。

如果通过 Azure API 管理 路由 Foundry 流量,请使用配置的网关终结点并从向导对其进行测试。 请参阅 在 Foundry 资源中配置 AI 网关。

所需的数据库特权

在运行架构转换之前,请与数据库管理员验证源元数据访问和架构验证数据库权限。 Oracle 帐户需要访问架构元数据和字典视图,而不是应用程序行数据。 PostgreSQL 帐户必须能够删除并重新创建匹配的架构,并创建用于验证的对象。 尽可能使用专用帐户,并遵循最低特权原则。

源 Oracle 特权

使用 受支持的 Oracle 版本。 源 Oracle 数据库需要以下权限:

权限 Purpose
CONNECT 基本数据库连接
SELECT_CATALOG_ROLE 访问数据字典视图
选择任意字典 读取系统元数据和字典对象
SELECT SYS.ARGUMENT$ 访问过程和函数参数信息
SELECT SYS.V_$RESOURCE_LIMIT 通过 V$RESOURCE_LIMIT 访问会话和进程利用率及限制

架构验证数据库权限

在所选架构验证数据库上配置以下访问权限。 数据库级别 CREATE 权限不授予删除另一角色拥有的架构的权限。

Access Purpose
数据库上的CONNECT 为转换和验证进行连接。
数据库上的CREATE 创建验证架构。
匹配架构的所有权,或经过适当授权的角色 在重新创建架构之前删除匹配的架构。
在验证架构中创建对象的权限 创建和编译转换后的定义。
扩展安装权限或管理员协助 安装转换和验证所需的扩展。

网络要求

  • 出站连接:Microsoft Foundry 终结点。
  • 数据库连接:源 Oracle 和所选Azure Database for PostgreSQL灵活服务器或 Azure HorizonDB 群集。
  • HTTPS 访问:Visual Studio Code扩展市场和GitHub Copilot服务。
  • GitHub存储库访问: https://github.com/microsoft/pgsql-tools/。

Oracle 即时客户端(用于厚客户端模式)

当扩展检测到可以加载的 Oracle 客户端库时,该扩展使用粗模式,并在未检测到任何客户端时使用精简模式。 检测到无法加载的客户端是配置错误,而不是成功的回退。 如果模式更改需要新进程,请重启Visual Studio Code。 请参阅 PostgreSQL 扩展发行说明。

Thin 模式不需要 Oracle 客户端库。 需要 Oracle 本机网络加密或校验和的连接需要使用厚模式。 使用 Oracle 数据库管理员查看源服务器的策略,并在运行Visual Studio Code的计算机上配置客户端。

Policy 源服务器设置 客户端设置
本机网络加密 SQLNET.ENCRYPTION_SERVER SQLNET.ENCRYPTION_CLIENT
数据完整性校验和 SQLNET.CRYPTO_CHECKSUM_SERVER SQLNET.CRYPTO_CHECKSUM_CLIENT

在 sqlnet.ora中, REQUIRED 拒绝无法满足策略的连接; REQUESTED 将服务与其他终结点协商。 这些设置不可互换。 不要通过削弱服务器策略来规避客户端配置错误。 请参阅 Oracle 网络加密和数据完整性。

准备 Thick 模式:

  1. 从 Oracle Instant Client downloads 下载适用于转换计算机操作系统和架构的 Oracle Instant Client Basic 或 Basic Light 软件包。
  2. 遵循 Oracle 特定于平台的依赖项、库搜索路径和网络配置文件的安装说明。
  3. 在继续操作之前,请重启Visual Studio Code并测试 Oracle 连接。

Microsoft Foundry 身份验证

为 Microsoft Foundry 配置以下身份验证方法之一:

身份验证方法 Requirements
API 密钥 提供同一 Foundry 资源的资源终结点和 API 密钥,且你的组织允许使用基于密钥的身份验证。 密钥不特定于一个部署。
Microsoft Entra ID 在托管部署的资源上具有 Foundry 用户角色(以前Azure AI 用户)的标识。 在向导中选择帐户和租户,并在出现提示时完成登录。

有关角色和身份验证详细信息,请参阅 Microsoft Foundry 中的身份验证和授权。 将资源密钥保留在源文件和共享报表中。

模式转换过程

本部分逐步讲解转换工作流。 安装扩展、初始化项目、连接到 Oracle、查看“发现”,并配置架构验证数据库和 Microsoft Foundry。 转换会尝试编译,并执行架构验证数据库中可用的静态检查。 然后,查看并优化输出,将其部署到所选的数据库,并独立验证其行为。

该扩展的 UI 在此工作流中使用诸如 迁移、创建迁移Project 和 Migrate 之类的标签。 这些标签并不意味着架构转换会迁移行数据。

以下屏幕截图显示了不同迁移运行的示例。 Project名称和对象计数在图像之间可能有所不同。

步骤 1:安装 PostgreSQL Visual Studio Code 扩展

  1. 打开Visual Studio代码。

  2. 转到 “扩展 ”视图(Ctrl+Shift+X)。

  3. 搜索 PostgreSQL 并打开由 Microsoft 发布的 PostgreSQL 扩展的详细信息。

  4. 将扩展安装或更新到最新的稳定版本。

    在 Visual Studio Code 中安装 PostgreSQL 扩展的屏幕截图。

  5. 使用与订阅关联的帐户登录GitHub Copilot。 打开Copilot 对话助手并确认组织的策略允许辅助评审功能。 请参阅Visual Studio Code中的设置GitHub Copilot。

Copilot 登录不会配置 Foundry 资源,并且 Foundry API 密钥不能让你登录 Copilot。 在将架构定义发送到任一服务之前,请查看 成本和数据处理常见问题解答 。

步骤 2:创建架构验证数据库连接

使用此连接进行架构验证。 使用空数据库或专用的未使用数据库,其中不包含任何需要保留的内容。 运行安装程序时,可以选择部署目标。

  1. 在 PostgreSQL 扩展面板中,创建与托管架构验证数据库的Azure Database for PostgreSQL灵活服务器或 Azure HorizonDB 群集的连接。 对于 Azure HorizonDB,请使用群集的读写终结点。

  2. 输入连接详细信息(主机、数据库、用户名、密码)。

  3. 测试并保存连接。 有关连接选项,包括浏览 Azure,请参阅“连接和标识”。

    添加新Azure Database for PostgreSQL连接的屏幕截图。

步骤 3:打开新工作区

  1. 在本地计算机上为架构转换项目新建一个文件夹。

  2. 在 Visual Studio Code 中以 new workspace 的形式打开文件夹。

    在Visual Studio Code中添加新工作区的屏幕截图。

步骤 4:创建架构转换项目

  1. 打开 PostgreSQL 扩展。

  2. 转到迁移面板。

  3. 选择 创建迁移项目。

    创建新迁移项目的屏幕截图。

步骤 5:配置项目设置

  1. 在 迁移向导中,输入 项目名称。

  2. 选择下一步继续操作。

    项目名称的屏幕截图。

    此屏幕截图中的先决条件列表适用于 API 密钥身份验证。 还可以使用Microsoft Entra ID身份验证。

步骤 6:配置 Oracle 连接

  1. 输入 Oracle 连接详细信息:

    领域 Description
    Oracle 主机名 源服务器的主机名或 IP 地址。
    Oracle 端口 侦听器端口,通常为 1521。
    Oracle SID 或服务名称 源数据库的 SID 或服务名称。
    Oracle 用户名 具有所需元数据权限的用户。
    Oracle 密码 源用户的密码。

    在连接之前,在运行Visual Studio Code的计算机上准备 Oracle 客户端配置。 客户端检测选择模式;此页面不提供手动薄/厚选择器。

  2. 选择 加载架构。 该工具测试 Oracle 连接,从 Oracle 视图 ALL_USERS 读取架构名称,并从选择列表中排除系统架构。

  3. 选择要转换为 Azure PostgreSQL 的一个或多个应用程序架构。

  4. 选择 “下一步:发现”。

    Oracle 连接与所选架构的屏幕截图,以及“下一步:发现”按钮。连接值已隐藏。

步骤 7:查看发现结果

发现功能显示源清单和计划提取范围。 此阶段未提取 DDL。 有关摘要计数和范围的说明,请参阅架构转换概述中的发现。

  1. 等待 Discovery 完成。

  2. 在 源权限下,查看各项检查及其用途和结果。 与您的 Oracle 数据库管理员一起查看未通过的检查。 解决权限问题后,选择“ 刷新发现 ”并查看更新的结果。 有关所需权限,请参阅 源 Oracle 权限。

  3. 查看 已发现、待提取、已排除 和 无效对象 的摘要计数。

  4. 展开“支持的对象类型”以按类型查看“待提取”、“已排除”和“无效对象”的计数。 受支持的类型仍可以包含排除的对象;这些计数不是转换结果。

  5. 展开不支持的对象类型以查看源上发现的不支持类别。 有关支持详细信息和 PostgreSQL 替代项,请参阅 架构转换限制。

  6. 在依赖架构下,查看你未选择的被引用架构。 选择“ 显示关系图 ”以查看引用。 连接上的数字表示依赖项引用,而不是要提取或转换的对象计数。 如果要在此项目中转换引用的应用程序架构,请在所选内容中包含引用的应用程序架构。 否则,请计划如何在 Azure PostgreSQL 中提供或替换所需的定义。 图中显示的依赖项并不会自动成为已选中架构。

  7. 查看有关未转换的引用 Oracle 系统架构的单独通知。 不要将这些引用视为另外选定用于转换的应用程序架构。

  8. 如果需要更改架构选择,请选择 “上一步” 以返回到 “连接到 Oracle”,更新 “架构”,然后再次选择 “下一步:发现”。 在继续操作之前,请查看更新的范围说明。

  9. 选择我已查看对象、排除项和依赖架构。

  10. 选择 “下一步:PostgreSQL 连接”。

    “发现”的屏幕截图,其中包含权限检查、对象计数、依赖项、范围确认和下一步:PostgreSQL 连接。对连接详细信息进行了修订。

步骤 8:配置架构验证数据库

在 Azure Database for PostgreSQL flexible server 或 Azure HorizonDB 上使用空的或专用且未使用的架构验证数据库,无需保留任何对象或数据。 有关准备指南,请参阅 准备架构验证数据库。

Warning

转换会删除与之 DROP SCHEMA ... CASCADE 匹配的架构,并重新创建它们。 此操作会删除其现有对象和数据,并且可以删除其他模式中的依赖对象。 确认此操作之前,请验证所选连接和数据库。

  1. 选择目标平台,Azure HorizonDB 或 Azure Database for PostgreSQL 灵活服务器。

  2. 在 PostgreSQL 连接中,选择为该服务定义的连接。

  3. 在 PostgreSQL 数据库中,选择架构验证数据库。

  4. 在 数据库检查中查看自动结果,包括服务器兼容性和扩展。 在继续操作之前解决阻塞性错误。 对于缺少的扩展,请使用特定于服务的准备指南来允许并安装转换后的架构所需的扩展,然后选择再次检查。 缺少依赖项可能导致单个对象无法编译,即使警告不会阻止继续操作,也可能如此。

    深色模式下的架构验证数据库页的屏幕截图,其中已选中Azure HorizonDB、已通过数据库检查以及确认架构重新生成。

  5. 选中复选框,确认架构验证数据库中与所选 Oracle 架构匹配的架构将在转换期间删除并重新创建,删除其现有对象和数据。

  6. 选择“下一步:Microsoft Foundry 模型配置”。

步骤 9:配置 Microsoft Foundry 语言模型

对于转换吞吐量,建议的部署容量大于每分钟 1,000,000 个令牌(TPM)。 为该架构以及共享此部署的其他工作负载规划容量,并监视限制情况。 请参阅配置Microsoft Foundry 容量。 该示例显示 230 万 TPM;其可用配额特定于该环境。

Microsoft Foundry 部署详细信息的屏幕截图,其中“每分钟令牌速率限制”设置为 230 万。

返回 Visual Studio Code 中的向导以配置模型连接:

  1. 输入模型连接详细信息:

    领域 Value
    模型名称 gpt-5.2。
    Microsoft Foundry 终结点 部署的资源终结点。
    部署名称 分配给部署的名称;它可能与模型名称不同。
  2. 选择 身份验证方法:

    • API 密钥:输入托管部署的 Foundry 资源的 API 密钥。
    • Microsoft Entra ID:选择Azure帐户和租户,并在出现提示时完成登录。 将标识与 Microsoft Foundry 身份验证中所述的资源访问配合使用。
  3. 选择测试 Microsoft Foundry 连接以验证配置。

  4. 连接成功后,选择“创建迁移Project。

成功的连接测试无法确定有足够的容量可用于持续转换工作负荷。

步骤 10:运行架构转换

  1. 系统会转到主迁移向导页面。

  2. 选择 “迁移 ”以启动架构转换过程。

  3. 监视Visual Studio Code接口中的转换进度。

  4. 转换完成后,项目会显示 架构转换已完成 和 “审阅转换摘要 ”操作。

    已完成的架构转换的屏幕截图,其中显示了提取和转换进度以及查看转换摘要。

如果运行失败或中断,请保留项目并遵循 转换失败指南。 不要将不完整的运行视为已完成的转换。

步骤 11:查看模式转换报告

  1. 模式转换完成后,HTML 转换报表会自动打开。
  2. 查看发现、提取和转换结果以及对象级注释。
  3. 有关解释报表的指导,请参阅 查看用于 Oracle 架构转换的 HTML 报表。

步骤 12:查看和优化转换的对象

  1. 从已完成的架构转换项目中,选择“ 查看转换摘要”。

  2. 在“转换摘要”页面上,选择“转换对象浏览器”。

    Conversion 对象资源管理器 的屏幕截图,其中包含筛选器、状态、“Ask”、“Fix”、“Resolve”和“刷新”图标。

  3. 选择一个对象以打开其差异视图,比较其 Oracle 和 PostgreSQL 定义,并阅读其转换说明。

    Oracle 和 PostgreSQL 定义及转换说明并排显示的屏幕截图。

  4. 使用 Ask 来解释转换及其依赖项,或使用 Fix 对对象及其依赖对象进行 Copilot 辅助更正。 成功编译后会自动将已更正的依赖对象标记为已解决。

    在 PostgreSQL 扩展中配置多个连接时,通过 修复 执行 SQL 会打开连接选择提示。 选择架构验证连接,然后在数据库选择弹窗中选择包含已转换架构的数据库。

  5. 对于手动更正,请在postgres_ddl中编辑并保存匹配的工具生成的 PostgreSQL 文件。 检查该对象差异视图的 PostgreSQL 侧的每条语句。

    在选择“播放”之前,请验证活动连接和数据库。 如果需要,请切换到架构验证目标。 差异视图可以重复使用以前的连接和数据库,而无需提示。

    对于现有表, CREATE TABLE IF NOT EXISTS 不会更新其定义。 在查询编辑器中,针对同一个架构验证数据库,单独执行已审核的 ALTER TABLE 语句。 在匹配的工具生成的文件中 postgres_ddl保留更正的创建定义。

    在对象的差异视图中选择播放按钮,在 PostgreSQL 端执行所有 SQL。 选择文本不会限制执行。 如果出现提示,请选择架构验证连接,再选择包含转换后架构的数据库。

  6. 查看编辑和编译结果,包括对依赖对象的更改。 验证是否已在所选数据库中应用更正。 在相应的工具生成的文件中保存任何手动编辑或postgres_ddl更正,并查看设置输入和部署范围。

  7. 如果对象在更正后需要手动更新状态,请选择“解析”将其标记为“已转换”。

  8. 选择转换对象资源管理器 对象资源管理器 中的“刷新”,以使用修订后的状态更新转换报告。

以下转换摘要示例显示了对象更正后的更新计数。 上面的Conversion 对象资源管理器屏幕截图显示了这些更正之前的状态。

更正后的转换摘要的屏幕截图,其中更新了转换计数和某些对象仍未转换。

有关筛选、依赖项更正、状态更新和手动编译步骤,请参阅在转换对象资源管理器 对象资源管理器 中查看转换后的对象。 转换后的状态并不能替代独立验证。

步骤 13:使用安装体验准备部署

转换工作流在完成时自动生成设置文件。 在部署运行期间,安装程序将读取 postgres_ddl 中工具生成的对象文件的最新保存内容,包括在生成设置文件后所做的更正。 安装程序将忽略手动添加到 postgres_ddl 的文件。 打开设置说明不会启动部署。

  1. 从已完成的架构转换项目中,选择“ 查看转换摘要”。
  2. 在转换摘要页面上,选择安装说明。 当安装文件准备就绪时,此操作将变为可用。
  3. 查看生成的 setup_instructions.md 文件,该文件会在编辑器中打开。 Visual Studio Code还会在资源管理器中显示设置文件夹。
  4. 按照“使用安装体验部署已转换的架构”在Azure Database for PostgreSQL灵活服务器或Azure HorizonDB 上准备所选的目标数据库,运行就绪情况检查,部署转换后的架构,并查看部署结果。

步骤 14:在生产使用之前验证已部署的架构

选择用于功能、数据和应用程序测试的数据库。 确认它包含要验证的已转换架构。

对于对现有表的手动编辑, CREATE TABLE IF NOT EXISTS 不更新表。 单独应用已审阅的 语句于 ALTER TABLE 中,并将更正后的创建定义保存在 postgres_ddl 中匹配的工具生成文件中。

差异视图中的播放按钮在 PostgreSQL 端执行所有 SQL。 选择文本不会限制执行。 差异视图可以重复使用以前的连接和数据库,而无需提示。

若要在部署后手动更正对象:

  1. 在Conversion 对象资源管理器中,选择对象以打开其差异视图。
  2. 进行更正,并将匹配的工具生成的文件保存到 postgres_ddl 中。 查看差异视图右侧更新的 PostgreSQL 定义。
  3. 查看差异视图 PostgreSQL 端的架构引用和每个语句。
  4. 在选择运行之前,请验证活动连接和数据库,并根据需要更改它们。 若要更正架构验证数据库中问题,请使用前面选择的连接和数据库进行架构验证。 对于在其他位置部署的架构,请使用其连接和数据库。
  5. 在差异视图中,选择播放按钮。 如果出现提示,请选择预期的连接,然后选择包含已部署架构的数据库。
  6. 在继续操作之前,请查看执行输出并解决错误。 验证所选数据库中更新的对象定义。
  7. 将更正的对象定义保存在 postgres_ddl 下其工具生成的文件中,以便将来的部署使用经过测试的更正。 编辑文件本身不会将更改应用到已部署的数据库。
  8. 如果需要,请在转换对象资源管理器 对象资源管理器 中使用“解析”来更新已更正对象的状态,然后选择“刷新”以更新转换报告。

使用具有代表性的测试数据和应用程序工作负载,独立验证已部署的模式。 根据 Oracle 源验证依赖项、约束、业务逻辑和结果集,并在更正后重新测试。 查看任何未转换或未部署的对象,而不是仅测试成功转换的对象。

Important

Foundry 生成初始转换,Copilot有助于审查和更正。 无论是 AI 输出还是成功编译,都不能证明应用程序行为是等效的。 在生产部署之前,独立验证转换的对象、手动更正和安全控制。

有关Visual Studio Code扩展的详细信息,请访问适用于 Visual Studio Code 和 Cursor 的 PostgreSQL 扩展。