/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.
version: 2

DMS Schema Conversion

Overview

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

> Execute commands using available tools from the AWS MCP server when connected — it provides sandboxed execution, audit logging, and observability. When the MCP server is not available, fall back to the AWS CLI or shell as needed.

**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.

---

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.

---

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. Use the actual source server endpoint as `server-name`. 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.

3. Wait for import completion using the DMS waiter:

   aws dms wait metadata-model-imported \
     --migration-project-identifier <migration_project_identifier>

4. **Show discovered schemas:** On success, call `describe-metadata-model-children` with `--origin SOURCE` at the root level to list the imported schemas/databases. Present the discovered names to the customer so they can confirm the correct database connection was established: > "Import complete. I found the following schemas/databases: `<list>`. Does this look correct?"

5. Proceed to [Actions Menu](#actions-menu).

---

Actions Menu

Present the actions menu using a structured selection tool (e.g., `AskUserQuestion`) if available — this gives the customer a clickable/selectable list.

**For SQL Server → PostgreSQL/Aurora PostgreSQL projects** (present as a single-select question "What would you like to do?"):

1. **Convert database** — convert schema objects to the target engine (also produces an conversion assessment report) 2. **Assess database** — run a compatibility assessment (also produces an conversion assessment report) 3. **Convert statement** — convert a single SQL statement 4. **Clean up** — delete migration project and related DMS resources

**For all other engine combinations** (present as a single-select question "What would you like to do?"):

1. **Convert database** — convert schema objects to the target engine (also produces an conversion assessment report) 2. **Assess database** — run a compatibility assessment (also produces an conversion assessment report) 3. **Work with tree** — browse the metadata model tree 4. **Clean up** — delete migration project and related DMS resources

The customer can always type a custom request via "Other" (e.g., "work with tree", "show database statistics", or "exit"). If the customer selects "Other" and describes an action covered by this skill, handle it accordingly.

After each action completes, return to this menu by presenting the same selection again.

> **Note on metadata loading:** `start-metadata-model-import` (with `Refresh=false`), `start-metadata-model-assessment`, and `start-metadata-model-conversion` all load the source tree for the scoped objects. If metadata was already imported in the current session for a given subtree, it does not need to be re-imported — these operations will work with what is already loaded.

---

Convert Database

1. **Ask what to convert:** Ask the customer what they want to convert (e.g., "all schemas", "schema pub