dms-schema-conversion

DMS 架构转换

概述

此技能涵盖 DMS 架构转换的完整生命周期——从首次设置到在现有项目上运行转换。

推荐使用 AWS MCP 服务，以简化执行流程、记录审计日志并实现可观测性。如果无法使用 MCP 服务，也可以直接通过 AWS CLI 执行所有操作。

关键文档：

• DMS 架构转换中的选择规则 — 将操作限定在特定对象范围内
• DMS 架构转换中的转换规则 — 在转换期间重命名架构、表和列

**全局约束：**在根据任何链接文档采取操作之前，你 MUST 获取并阅读该文档；不要依赖记忆处理任何引用的材料（选择规则、转换规则、故障排除指南、网络配置等）。不同引擎和 API 版本的文档包含的供应商特定细节会有所变化。

---

防护措施 — 此技能自身文件的位置（MCP 与本地安装）

此技能可以通过两种方式加载，它们会从不同位置解析技能自带的文件。读取参考文件之前，请先确定此技能的加载方式：

• **通过 AWS MCP retrieve_skill 工具加载：**此技能未安装在本地文件系统上。你 MUST 使用 retrieve_skill 并传入 file 参数获取每个参考文件（例如 file="references/setup-wizard.md"）。不要在本地对这些路径使用 file_read——它们在磁盘上不存在。
• 本地安装（例如 .kiro/skills/dms-schema-conversion/ 或 ~/.claude/skills/dms-schema-conversion/）：使用相对路径从本地技能目录读取文件。

此区别仅适用于技能自身打包的文件。用户数据和会话产物始终从用户的工作目录读取并写入其中。切勿通过 retrieve_skill 获取或写入客户数据。

---

验证依赖项

开始之前，请检查是否可以执行 AWS CLI 命令。

约束：

• 你 MUST 验证 AWS CLI 命令是否可以运行（通过 MCP 服务工具或直接通过 shell）
• 如果没有可用的执行方式，你 MUST 告知客户并询问是否继续
• 你 MUST 询问客户要使用哪个 AWS 区域——不要尝试从 STS 响应中推断区域（其中不包含区域字段）。如果客户不确定，建议检查 AWS_DEFAULT_REGION 环境变量或他们正在使用的 --region 标志。
• 在此技能中运行任何 AWS CLI 命令之前，你 MUST 将 AWS_EXECUTION_ENV 环境变量设为 AWSMCP-DMSSchemaConversion-Skill，以便在此 Agentic 工作流期间发出的调用能够通过 CloudTrail 的 userAgent 字段进行归因。可在整个会话中设置一次（export AWS_EXECUTION_ENV=AWSMCP-DMSSchemaConversion-Skill），或为每个命令添加前缀（AWS_EXECUTION_ENV=AWSMCP-DMSSchemaConversion-Skill aws dms ...）。AWS CLI 和 botocore 会将此值附加到请求的 User-Agent 中，格式为 exec-env/AWSMCP-DMSSchemaConversion-Skill。此值仅是尽力而为的归因标记，并非访问控制；它 MUST 不包含空格，以确保其保持为单个 User-Agent 令牌。

项目选择

检查是否存在迁移项目：

aws dms describe-migration-projects

• 如果恰好存在一个项目 → 询问客户：“找到迁移项目 <name>。您想使用它，还是创建一个新项目？”如果客户确认使用，则保存 migration_project_identifier 并继续前往操作菜单。如果客户想创建新项目，则运行设置向导。
• 如果存在多个项目 → 列出这些项目，并询问客户选择一个，或提出创建新项目。保存 migration_project_identifier，然后前往操作菜单。
• 如果不存在项目 → 询问：“未找到迁移项目。您想创建一个吗？”如果客户回答是，则加载 setup-wizard.md，并从第 1 阶段开始运行完整的设置向导。向导完成后，运行自动导入，然后前往操作菜单。

---

自动导入

此部分仅在设置向导创建新项目后运行。对于现有项目，请勿运行。

1. 构建选择规则，以从源服务导入所有架构。对于 server-name，使用数据提供程序标识符（ARN 中的短 ID，例如 JIFET2LUZJEJZPDYSOSGANOA2M），或数据提供程序设置中的字面值 ServerName（例如，离线数据源使用 "offline"）。对于 SQL Server，必须在对象定位符中包含 database-name。JSON 格式请参阅 DMS 架构转换中的选择规则。

2. 使用 --origin SOURCE --refresh 以及第 1 步中的选择规则运行 start-metadata-model-import。从响应中提取 RequestIdentifier。

3. 使用 DMS 等待器等待导入完成：

   aws dms wait metadata-model-imported \
     --migration-project-identifier <migration_project_identifier> \
     --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>'
   

   如果等待器失败或不可用，则改为每 30 秒使用 --filter Name=request-id,Values=<RequestIdentifier> 轮询 describe-metadata-model-imports。终止状态：SUCCESS（继续）或 FAILED（通过响应中的 Error 字段检查错误）。

4. **显示发现的架构：**成功后，在根级别调用 describe-metadata-model-children 并传入 --origin SOURCE，以列出已导入的架构/数据库。向客户展示发现的名称，以便他们确认已建立正确的数据库连接：

   “导入完成。我找到了以下架构/数据库：<list>。看起来正确吗？”

5. 前往操作菜单。

---

操作菜单

如果可用，请使用结构化选择工具（例如 AskUserQuestion）展示操作菜单，以便客户通过点击或选择来做出选择。

对于 SQL Server → PostgreSQL/Aurora PostgreSQL 项目（以单选问题“您想要执行什么操作？”的形式展示）：

1. 转换数据库 — 将架构对象转换为目标引擎（还会生成转换评估报告）
2. 评估数据库 — 运行兼容性评估（还会生成转换评估报告）
3. 转换语句 — 转换一条 SQL 语句
4. 清理 — 删除迁移项目及相关 DMS 资源

对于所有其他引擎组合（以单选问题“您想要执行什么操作？”的形式展示）：

1. 转换数据库 — 将架构对象转换为目标引擎（还会生成转换评估报告）
2. 评估数据库 — 运行兼容性评估（还会生成转换评估报告）
3. 操作树 — 浏览元数据模型树
4. 清理 — 删除迁移项目及相关 DMS 资源

客户也可以随时通过“其他”输入自定义请求（例如“操作树”“显示数据库统计信息”或“退出”）。如果客户选择“其他”并描述了此技能涵盖的操作，请按相应方式处理。

每项操作完成后，都返回此菜单并再次展示相同的选择。

元数据加载说明： start-metadata-model-import（使用 Refresh=false）、start-metadata-model-assessment 和 start-metadata-model-conversion 都会加载所选对象的源树。如果当前会话中已导入某个子树的元数据，则无需重新导入；这些操作会使用已加载的内容。

转换数据库

1. 询问要转换的内容： 询问客户想转换什么（例如“所有架构”、“架构 public”、“以 PROD_ 开头的表”）。

2. 构建选择规则： 将客户的自然语言转换为选择规则 JSON。有关格式、通配符和特定供应商的定位符，请参阅 DMS 架构转换中的选择规则。

3. 运行转换： 使用迁移项目和选择规则调用 start-metadata-model-conversion。从响应中提取 RequestIdentifier。

4. 等待完成： 使用 DMS 等待器等待：

   aws dms wait metadata-model-converted \
     --migration-project-identifier <migration_project_identifier> \
     --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>'
   

   如果等待器失败或不可用，则改为每 30 秒轮询一次 describe-metadata-model-conversions，并使用 --filter Name=request-id,Values=<RequestIdentifier>。终止状态：SUCCESS（继续）或 FAILED（检查错误）。

5. 导出转换评估报告： 转换成功后，使用选择规则调用 export-metadata-model-assessment，并设置 rule-action: "explicit"（此 API 要求使用显式规则，而不是 include）。向客户提供 PDF 和 CSV 报告的 S3 链接（PdfReport.S3ObjectKey 和 CsvReport.S3ObjectKey）。

6. 显示摘要： 使用 aws s3 cp s3://<bucket>/<CsvReport.S3ObjectKey> ./Summary.csv 从 S3 下载摘要 CSV。向客户展示其内容，包括每个类别的对象数量、自动转换的数量，以及各复杂度级别下包含操作项的数量。

7. 转换后子菜单： 显示摘要后，提供选项。只有当目标是实时目标（而非虚拟目标）时，才显示“应用到目标”：

   “接下来您想做什么？

   1. 修复操作项 — 查看并修复转换评估报告中的操作项
   2. 导出为脚本 — 将转换后的 DDL 导出为 SQL 脚本到 S3
   3. 应用到目标 — 将转换后的对象应用到目标数据库 (仅限实时目标)
   4. 返回 — 返回操作菜单”

   • 修复操作项： 加载 action-items.md，并按照其中的修复工作流操作。
   • 导出为脚本： 运行 aws dms start-metadata-model-export-as-script --migration-project-identifier <migration_project_identifier> --origin TARGET --selection-rules '<json>'。提取 RequestIdentifier。使用 aws dms wait metadata-model-exported-as-script --migration-project-identifier <id> --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>' 等待。完成后提供 S3 链接。
   • 应用到目标： 运行 aws dms start-metadata-model-export-to-target --migration-project-identifier <migration_project_identifier> --selection-rules '<json>'。如果客户确认，可选传入 --overwrite-extension-pack。提取 RequestIdentifier。使用 aws dms wait metadata-model-exported-to-target --migration-project-identifier <id> --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>' 等待。完成后告知客户。
   • 返回： 返回操作菜单。

完成后，询问客户接下来想做什么。

---

评估数据库

评估会分析转换复杂度，并生成转换评估报告，但不会实际转换任何对象。当客户想在决定是否进行转换之前了解迁移工作量时，请使用此功能。

重要： 如果客户已针对相同范围运行过转换，则无需单独进行评估 — 转换已经生成了转换评估报告。请告知客户：“您之前运行的转换已生成转换评估报告。您想让我显示该报告，还是要针对其他范围重新运行评估？”

1. 询问评估范围： 询问客户想评估什么（例如“所有架构”“架构 pg_catalog”“以 PROD_ 开头的表”）。

2. 构建选择规则： 将客户的自然语言转换为选择规则 JSON。请参阅 DMS Schema Conversion 中的选择规则，了解格式、通配符和特定于供应商的定位符。

3. 运行评估： 使用迁移项目和选择规则调用 start-metadata-model-assessment。从响应中提取 RequestIdentifier。

4. 等待完成： 使用 DMS waiter 等待：

   aws dms wait metadata-model-assessed \
     --migration-project-identifier <migration_project_identifier> \
     --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>'
   

   如果 waiter 失败或不可用，则改为每隔 30 秒轮询一次 describe-metadata-model-assessments，并使用 --filter Name=request-id,Values=<RequestIdentifier>。终止状态：SUCCESS（继续）或 FAILED（检查错误）。

5. 导出转换评估报告： 成功后，使用相同的选择规则调用 export-metadata-model-assessment。向客户提供 PDF 和 CSV 报告的 S3 链接（PdfReport.S3ObjectKey 和 CsvReport.S3ObjectKey）。报告包含转换复杂度统计信息、操作项和预计工作量。

6. 显示摘要： 使用 aws s3 cp s3://<bucket>/<CsvReport.S3ObjectKey> ./Summary.csv 从 S3 下载摘要 CSV。向客户展示其内容 — 显示每个类别中的对象数量、可自动转换的数量，以及每个复杂度级别中包含操作项的数量。

7. 提供解决操作项的帮助： 询问客户：

   “您想让我帮忙解决这些操作项吗？”

   如果客户同意，则加载 action-items.md 并按照其中的解决工作流操作。

完成后，询问客户接下来想做什么。

---

查看操作项

加载 action-items.md 并按照其中的工作流操作。

完成后，询问客户接下来想做什么。

---

使用树

元数据树以分层结构表示数据库架构。它包含两种元素：

• 对象 — 实际的数据库对象（表、函数、视图、序列、索引），包含 SQL 定义
• 类别 — 虚拟分组容器（“架构”“表”“函数”），用于整理对象以便导航，但不包含 SQL 定义

树采用按需加载方式 — 仅在导入时才会从数据库中检索元数据。完整详情请参阅浏览元数据模型。

导航使用两个 API：

• describe-metadata-model-children — 返回给定节点的子节点，每个子节点都有自己的 SelectionRules，用于继续深入浏览
• describe-metadata-model — 返回特定对象的名称、类型和 SQL 定义

两者都需要 --origin SOURCE 或 --origin TARGET，且仅接受 explicit 选择规则。

1. 显示树根节点： 使用指向根级别的选择规则和 --origin SOURCE 调用 describe-metadata-model-children。如果树为空，则自动运行元数据导入（与自动导入相同），然后重新显示树根节点。

2. 导航： 响应中的每个子节点都有 MetadataModelName 和 SelectionRules。展示子节点并询问客户接下来想做什么：

   • 显示子节点 — 使用子节点的 SelectionRules 作为 --selection-rules 参数，调用 describe-metadata-model-children 以深入浏览该子节点
   • 显示定义 — 显示所选对象的 DDL（见步骤 3）。此选项仅适用于对象，不适用于类别。
   • 向上 — 返回父节点
   • 退出树 — 返回操作菜单

3. 显示定义： 使用子节点的 SelectionRules 和 --origin SOURCE 调用 describe-metadata-model。响应包含 Definition（SOURCE DDL）和 TargetMetadataModels（已转换的对应项列表，每项都有自己的 SelectionRules）。要获取 TARGET DDL，请使用 TargetMetadataModels[0] 中的 SelectionRules 和 --origin TARGET 再次调用 describe-metadata-model。清楚地标注并展示 SOURCE 和 TARGET。

4. 从数据库刷新： 如果客户要求刷新，则使用限定到当前树位置的选择规则以及 --origin SOURCE --refresh 运行 start-metadata-model-import。提取 RequestIdentifier。通过以下命令等待：aws dms wait metadata-model-imported --migration-project-identifier <id> --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>'。刷新完成后，重新显示当前节点的子节点。

完成后，询问客户接下来想做什么。

---

转换 SQL 语句

**限制：**此功能仅适用于 SQL Server → PostgreSQL/Aurora PostgreSQL 迁移项目。对于任何其他源/目标引擎组合，请勿提供或显示此选项。

1. **确定上下文：**浏览元数据树，找到目标位置。对于 SQL Server，路径为 server → database → schema；对于其他引擎，路径为 server → schema。使用 describe-metadata-model-children 逐层浏览节点，直到到达 schema 层级。让客户选择 schema（对于 SQL Server，则选择 database + schema）。如果树为空，请让客户手动提供位置。

2. **获取 SQL 语句：**询问客户要转换的 SQL 语句。

3. **为 schema 构建选择规则：**构建以 schema 位置为目标的选择规则。有关格式和特定供应商的定位符，请参阅 DMS Schema Conversion 中的选择规则。

4. **创建元数据模型：**生成唯一的模型名称（例如 statement-<timestamp>）。调用 start-metadata-model-creation，并提供：

   • --selection-rules — 第 3 步中的 schema 选择规则
   • --metadata-model-name — 生成的模型名称
   • --properties '{"StatementProperties": {"Definition": "<sql_statement>"}}'

   从响应中提取 RequestIdentifier。通过 aws dms wait metadata-model-created --migration-project-identifier <id> --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>' 等待操作完成。

5. **为语句构建选择规则：**构建以特定语句为目标的选择规则。请参阅 DMS Schema Conversion 中的选择规则，并将 statement-name 设为模型名称。

6. **转换已创建的模型：**调用 start-metadata-model-conversion，并提供第 5 步中的语句选择规则。提取 RequestIdentifier。通过 aws dms wait metadata-model-converted --migration-project-identifier <id> --filter 'Name=schema-conversion-operation-id,Values=<RequestIdentifier>' 等待操作完成。

7. **显示转换结果：**调用 describe-metadata-model，提供第 5 步中的语句选择规则以及 --origin SOURCE。从响应中提取 TargetMetadataModels[0].SelectionRules。然后调用 describe-metadata-model，提供这些目标选择规则以及 --origin TARGET。清楚地向客户展示 Definition 字段中的转换后 SQL。

8. 导出转换评估报告：调用 export-metadata-model-assessment，并提供第 5 步中的源选择规则。向客户提供 PDF 和 CSV 报告的 S3 链接。

完成后，询问客户接下来想做什么。

---

数据库统计信息

当客户询问其源数据库统计信息（例如对象数量、对象类型、架构大小或总体概览）时，运行评估并以简明摘要呈现结果。

1. 根据客户的范围构建选择规则。 如果客户指定了特定架构或对象，请按其范围进行筛选。如果未指定范围，默认选择源服务器上的所有架构（通配符 %）。JSON 格式请参阅 DMS 架构转换中的选择规则。

2. 运行评估： 使用迁移项目和选择规则调用 start-metadata-model-assessment。执行详情请参阅 schema-conversion-operations.md。

3. 等待完成： 使用 DMS 等待器，或按照 schema-conversion-operations.md 中的说明进行轮询。

4. 导出转换评估报告： 使用相同的选择规则调用 export-metadata-model-assessment。

5. 下载并仅呈现客户要求的内容： 从 S3 下载摘要 CSV：

   aws s3 cp s3://<bucket>/<CsvReport.S3ObjectKey> ./Summary.csv
   

   报告包含许多数据点。仅呈现客户要求的信息，不要倾倒整个报告。例如：

   • 如果客户问“有多少张表？”→ 仅显示表数量
   • 如果客户询问特定架构 → 仅显示该架构的统计信息

6. 提供后续步骤： 询问客户是否想查看转换复杂度，或继续进行转换。

约束：

• 如果客户指定了范围，请按其范围执行；否则，默认选择所有架构。
• 仅呈现客户要求的内容，不要用未请求的数据造成信息过载。
• 以清晰的表格格式呈现统计信息。

完成后，询问客户接下来想做什么。

---

清理

删除迁移项目及其关联的 DMS 资源。必须按依赖顺序删除资源。

1. 向客户确认： 列出将要删除的资源并征求确认：

   aws dms describe-migration-projects --filter Name=migration-project-identifier,Values=<migration_project_identifier>
   

   显示项目名称、源/目标数据提供程序和实例配置文件。

2. 删除迁移项目：

   aws dms delete-migration-project \
     --migration-project-identifier <migration_project_identifier>
   

3. 删除数据提供程序： 删除源和目标数据提供程序：

   aws dms delete-data-provider \
     --data-provider-identifier <source_data_provider_identifier>
   aws dms delete-data-provider \
     --data-provider-identifier <target_data_provider_identifier>
   

4. 删除实例配置文件：

   aws dms delete-instance-profile \
     --instance-profile-identifier <instance_profile_identifier>
   

5. 删除子网组：

   aws dms delete-replication-subnet-group \
     --replication-subnet-group-identifier <subnet_group_identifier>
   

6. 确认完成： 告知客户所有 DMS Schema Conversion 资源均已移除。

约束：

• 删除任何资源前，必须获得客户的明确确认。
• 必须按以下顺序删除：先删除迁移项目，然后是数据提供程序、实例配置文件，最后是子网组——顺序错误会因依赖关系而导致删除失败。
• 不得删除底层基础设施（VPC、子网、安全组、RDS 实例、Secrets Manager 密钥）——这些不属于 DMS Schema Conversion 清理范围。

完成后，询问客户接下来想做什么。

---

取消注意事项

在任何正在运行的异步操作期间，如果客户要求取消，请参阅 cancel-operations.md，以了解正确的取消命令映射。

---

安全注意事项

• 凭证： 所有数据库凭证均存储在 AWS Secrets Manager 中。切勿将凭证嵌入数据提供方设置中，也不要将其记录到输出中。
• 静态加密： S3 存储桶使用 SSE-S3 加密（默认）。DMS Schema Conversion 不支持 SSE-KMS。
• 传输加密： 在线连接应使用 require 或更强的 SSL 模式。none 仅应在隔离的测试环境中使用。
• IAM 最小权限： 所有 IAM 角色都使用防止混淆代理的条件键（aws:SourceAccount、aws:SourceArn）和范围受限的资源 ARN。
• 网络访问： DMS 实例配置文件在 VPC 子网中运行，并受安全组限制。
• 如需更多指导，请参阅 DMS 安全最佳实践。

---

错误处理

当任何操作失败或返回错误时，请加载 troubleshooting.md 并遵循其中的指导来诊断和解决问题。用通俗易懂的语言向客户解释错误，并提供以下选项：重试、尝试其他操作或退出。