/dms-schema-conversion

name: dms-schema-conversion
description: "Handles the full DMS Schema Conversion lifecycle including creating migration projects, converting database schemas to a target engine, running compatibility assessments, navigating metadata trees, exporting converted DDL to S3, applying schema changes to a target database, and converting SQL statements between database engines. Applies when migrating database schemas between heterogeneous engines using AWS DMS Schema Conversion."
version: 4

DMS Schema Conversion

Overview

This skill handles the full DMS Schema Conversion lifecycle — from first-time setup to running conversions on an existing project.

> The AWS MCP server is recommended for streamlined execution, audit logging, and observability. When the MCP server is not available, all operations can be performed via AWS CLI directly.

**Key documentation:**

• [Selection rules in DMS Schema Conversion](https://docs.aws.amazon.com/dms/latest/userguide/sc-selection-rules.html) — scoping operations to specific objects
• [Transformation rules in DMS Schema Conversion](https://docs.aws.amazon.com/dms/latest/userguide/sc-transformation-rules.html) — renaming schemas, tables, columns during conversion

**Global constraint:** You MUST fetch and read any linked documentation before acting on it — do NOT rely on memory for any referenced material (selection rules, transformation rules, troubleshooting guides, network configuration, etc.). Documentation contains vendor-specific details that change between engines and API versions.

---

Guardrail — where this skill's own files live (MCP vs local install)

This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference:

• **Loaded through the AWS MCP `retrieve_skill` tool:** The skill is not installed on the local filesystem. You MUST fetch each reference via `retrieve_skill` with the `file` parameter (e.g. `file="references/setup-wizard.md"`). Do NOT `file_read` these paths locally — they do not exist on disk.
• **Installed locally** (e.g. `.kiro/skills/dms-schema-conversion/` or `~/.claude/skills/dms-schema-conversion/`): Read files from the local skill directory using relative paths.

This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory. Never fetch or write customer data through `retrieve_skill`.

---

Verify Dependencies

Before starting, check that AWS CLI commands can be executed.

**Constraints:**

• You MUST verify that AWS CLI commands can be run (via MCP server tools or directly via shell)
• You MUST inform the customer if no execution method is available and ask whether to proceed
• You MUST ask the customer which AWS region to use — do NOT attempt to infer it from the STS response (it does not contain a region field). If the customer is unsure, suggest checking the `AWS_DEFAULT_REGION` environment variable or the `--region` flag they are using.
• You MUST set the `AWS_EXECUTION_ENV` environment variable to `AWSMCP-DMSSchemaConversion-Skill` before running any AWS CLI command in this skill, so that calls made during this agentic workflow are attributable in the CloudTrail `userAgent` field. The AWS CLI and botocore append this value to the request User-Agent as `exec-env/AWSMCP-DMSSchemaConversion-Skill`. Set it once for the session (`export AWS_EXECUTION_ENV=AWSMCP-DMSSchemaConversion-Skill`) or prefix each command (`AWS_EXECUTION_ENV=AWSMCP-DMSSchemaConversion-Skill aws dms ...`). The value is a best-effort attribution marker only — it is not an access control, and it MUST contain no spaces so it stays a single User-Agent token.

---

Project Selection

Check for existing migration projects:

aws dms describe-migration-projects

• **If exactly one project exists** → ask the customer: "Found migration project `<name>`. Would you like to use it, or create a new one?" If they confirm, store `migration_project_identifier` and proceed to [Actions Menu](#actions-menu). If they want a new one, run the setup wizard.
• **If multiple projects exist** → list them and ask the customer to pick one, or offer to create a new project. Store `migration_project_identifier`, proceed to [Actions Menu](#actions-menu).
• **If no projects exist** → ask: "No migration projects found. Would you like to create one?" If yes, load [setup-wizard.md](references/setup-wizard.md) and run the full setup wizard from Phase 1. After wizard completes, run [Auto Import](#auto-import), then proceed to [Actions Menu](#actions-menu).

---

Auto Import

> This section runs only after the setup wizard creates a new project. Do NOT run for existing projects.

1. Build selection rules to import **all schemas** from the source server. For `server-name`, use the data provider identifier (the short ID from the ARN, e.g., `JIFET2LUZJEJZPDYSOSGANOA2M`) or the literal `ServerName` value from the data provider settings (e.g., `"offline"` for offline sources). For SQL Server, you MUST include `database-name` in the object locator. See [Selection rules in DMS Schema Conversion](https://docs.aws.amazon.com/dms/latest/userguide/sc-selection-rules.html) for JSON format.

2. Run `start-metadata-model-import` with `--origin SOURCE --refresh` and the selection rules from step 1. Extract `RequestIdentifier` from the response.

3. Wait for import completion using the DMS waiter:

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

If the waiter fails or is unavailable, fall back to polling `describe-metadata-model-imports` every 30 seconds with `--filter Name=request-id,Values=<RequestIdentifier>`. Terminal statuses: **SUCCESS** (proceed) or **FAILED** (check error via the `Error` field in the response).