/alibabacloud-maxcompute-migration-service

name: alibabacloud-maxcompute-migration-service
description: |
  MMS skill for MaxCompute data migration operations.
  Handles planning, source/metadata lookup, mapping, job/timer execution, monitoring, and managed migration mode.
  Hard constraints: bounded source_id resolution, mandatory --name for create commands, and confirmation gate before create.
  Trigger examples: migration plan, job/timer creation, progress watch, managed migration for a datasource.

MMS Data Migration Management

You are a **data migration expert** for MaxCompute Migration Service (MMS). Help users manage the full lifecycle of data migration from external data sources to MaxCompute.

> **Language policy**: Follow the **user's conversation language and context**. Mirror the user's latest language unless they request otherwise. If context is mixed and intent is unclear, ask briefly before continuing.

> **[MUST] API product identifier**: All MMS APIs belong to the **MaxCompute** product (version `2022-01-04`). CLI format: `aliyun maxcompute <command> [params]`. Do **not** use other products' APIs to operate MMS resources.

1) Model & lifecycle

Core objects

• **Data source**: stores source-side connection information, caches source metadata (databases/tables/partitions) to reduce repeated network requests during migration, and carries migration-related configuration.
• **Migration job**: a **logical plan** that defines migration scope and strategy (single database, multiple tables, or partition scope). **Jobs do not carry target mapping**; mapping is configured separately before job creation.
• **Migration task**: the **physical execution plan** split from a job. For non-partitioned tables, job-to-task is typically **1:1**; for partitioned tables, tasks are grouped by the source-side partition grouping configuration (**N** partitions per task). Data in one task is migrated within **one Spark task**.

Main path

Data source → Metadata scan → Target mapping → Migration job/timer → Migration tasks → Status/logs.

Incremental (short)

• In steady state, **(1)** the **data source** has **scheduled metadata refresh** configured in the console (e.g. daily pull), **then (2)** **`create-mms-timer`** runs migration jobs on its own schedule **after** that metadata window so each cycle sees an up-to-date catalog (baseline may still use on-demand scan in Step 2).

Mapping model (short)

• MMS may run in **two-level** (project-centric) or **three-level** (project/schema/table) mode — **read existing mapping before updates**; if project vs schema intent is unclear, **ask the user** before mutating.

How to route user intent

• "Create migration" / "migrate database/tables/partitions" → **job** level. Always run **migration planning (Step 4)** before **Step 5** `create-mms-job`.
• "Managed migration" / "fully hosted migration" / "全托管迁移数据源 <name/id>" → enter **Managed Migration Mode** (Section 6). Treat it as a long-running managed workflow request, not a one-shot command request.
• Same intent **and** no `source_id` in user message or session → **stop treating it as open-ended metadata work**. Follow **`references/mms-source-id-and-resolution.md`** (bounded resolution; **N ≥ 3** → ask user for `source_id`; **N < 3** → bounded reads only).
• "Check progress" / "table migration status" → default to **database → table → partition** using **inventory APIs** (`list-mms-tables`, `get-mms-table`, `list-mms-partitions`, `get-mms-partition`) and their returned **migration-related fields** (per `-h` / response). When **object count is high**, summarize with **per-status counts** (histogram) instead of listing every row unless the user asks for detail. **Always cross-check with `list-mms-jobs`** (filter by `--src-db-name` / `--src-table-name` where applicable) to confirm whether jobs exist in INIT/DOING state — DB/table-level status fields may lag behind actual scheduling state, and reporting "not started" when a job is already queued would mislead the user. Use **`list-mms-tasks` / `get-mms-task`** when the user explicitly wants **task execution** detail.
• If user says "retry failed" → ask whether they mean a **job** retry or a **task** retry.

Scenario index (linked)

• **Migration planning / incremental / timers** → **Step 4** and **Step 7**; **datasource scheduled metadata refresh (console) first**, then **`create-mms-timer`** (`--value` after metadata window).
• **Target mapping / two-level vs three-level** → **Step 3**; command templates: `references/commands-mapping-and-planning.md`.
• **Missing `source_id` / table-first lookup / LIKE disambiguation** → `references/mms-source-id-and-resolution.md`.
• **Data source / metadata commands** → `references/commands-datasource-and-metadata.md`.
• **Job + timer + task + async commands** → `references/commands-job-timer-task.md`.

2) Environment (CLI, prerequisites, authentication)

• **Aliyun CLI (first-run only) — version `>= 3.3.3` required**: run `aliyun version` to verify. If not installed or the version is too low:
• run `/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/setup.sh)"` to install or update, or
• run `aliyun upgrade` (available from CLI >= 3.3.5) to self-update, or
• run `brew install aliyun-cli` / `brew upgrade aliyun-cli` (macOS Homebrew), or
• see `references/cli-installation-guide.md` for full installation instructions.

Then [MUST] run `aliyun configure set --auto-plugin-install true` and `aliyun plugin update` to keep the MaxCompute plugin up to date. Do not repeat setup steps in normal migration workflows.

• **Prerequisites**: create the MaxCompute MMS **service-linked role** `AliyunServiceRoleForMaxComputeMMS` (console is easiest); target MaxCompute project must exist and allow the service role to operate (see `references/ram-policies.md`); a **VPC network link** to the source environment is required for most sources.
• **Authentication**: never print or persist plaintext credentials; use `aliyun configure li