---

name: synapse-migration description: "Converts Azure Synapse workloads to Fabric: Dedicated SQL Pool schemas and procedures to Lakehouse Spark SQL artifacts or Warehouse targets, plus Spark, Lake Database, and Linked Service migration. Excludes standalone Fabric Warehouse administration, Databricks source code, and pipelines. Triggers: Dedicated SQL Pool to Lakehouse, Dedicated SQL Pool to Fabric Warehouse, convert Synapse stored procedure, offline Synapse artifacts."

Telemetry — MANDATORY. Every api.fabric.microsoft.com call must carry x-ms-fabric-skill: synapse-migration (az rest: --headers "x-ms-fabric-skill=synapse-migration"), including every LRO poll, fabric_lro and retry. Snippets omit it — add it anyway.

OFFLINE LAKEHOUSE ARTIFACT FAST PATH — DECIDE FIRST. For a no-live-call request with complete supplied inputs and contracts, load only the fast path; do not load migration-planning-reference.md, dedicated-pool-conversion.md, or implementation scripts. Use one generator for expected-schema.json, artifacts, and final-byte hashes, then one verifier. Do not manually edit artifacts or reread resources. Do not inspect generated files or run post-pass spot checks. Stop when verification passes or fails. Do not use this path for a Warehouse target; incomplete and large-procedure requests use their own routes.

CRITICAL NOTES

1. To find workspace details (including its ID) from a workspace name: list all workspaces, then use JMESPath filtering
2. To find item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace, then use JMESPath filtering
3. mssparkutils and notebookutils share the same API surface in most cases — the namespace is the primary change
4. Linked Services have no direct REST API equivalent in Fabric — name both replacement categories when explaining the migration: Fabric Data Connections for external databases/services and OneLake Shortcuts for storage mounts. mssparkutils.credentials.getConnectionStringOrCreds is unavailable in Fabric; for a Key Vault-backed secret, show notebookutils.credentials.getSecret(keyVaultUrl, secretName).
5. The Dedicated SQL Pool-to-Fabric-Lakehouse path is source- and feature-driven. You MUST complete these phases in strict order:
   1. Gap Assessment (MANDATORY FIRST): Run compatibility assessment using dedicated-pool-gap-assessment.md to identify unsupported features, blockers, and migration risks BEFORE attempting any conversion.
   2. User Approval (REQUIRED): After assessment, present 1:1, N:1, and N:N stored-procedure-to-notebook mapping strategies and require the user to explicitly approve the complete mapping, target names, dependency grouping, and workspace placement. Wait for explicit approval before proceeding.
   3. Manifest Creation (REQUIRED): Create migration-manifest.json to track all objects, approved mappings, conversion status, and deployment checkpoints. Update manifest atomically after every phase.
   4. Conversion: Generate artifacts only after approval is recorded in manifest. The 1:1, N:1, and N:N mapping applies ONLY to stored procedures, NOT to views. Views are schema objects like tables and are deployed via Livy as SQL view definitions; they never convert to notebooks. Preserve every procedure as an independently traceable source decision under any approved strategy. Stored-procedure transformation logic must use readable Spark SQL %%sql cells, not PySpark or the DataFrame API. Generated notebooks are outputs, not orchestration dependencies.
6. Treat the original production Dedicated Pool as read-only. Never create sample or synthetic data, schemas, tables, views, procedures, users, roles, or grants there, and never run its DDL, DML, or stored procedures. Source operations against the original are limited to metadata discovery and metadata-based validation. The Warehouse data path may run narrowly scoped setup DDL and CETAS only against the separately approved restored export copy after its identity is validated as different from the original; cleanup remains separately reviewed and user-run.
7. Dedicated Pool data migration is out of scope only for the Lakehouse artifact-conversion path. That path must never export, stage, copy, upload, shortcut, transfer, or load source table rows, and must not run row-level or business-result equivalence queries. The Warehouse path has its own explicit post-DDL data consent gate and restored-source requirement.
8. Print regular migration status. Announce every step before it starts, report each object or checkpoint as it completes or fails, emit a concise heartbeat at least every 30-60 seconds during long-running operations, and close every phase with completed/failed/skipped/pending counts. Include the phase, step, object, state, elapsed time, and next action. Status output must exclude credentials, tokens, connection strings, and sensitive data values.
9. For large or complex stored procedures, prove conversion coverage with a deterministic source-block ledger and publish only from a hash-verified immutable deployment package. Every block must be converted, explicitly excluded with approval, or manually reviewed and approved; notebook syntax success alone is insufficient.
10. Before generating live or partially specified Dedicated Pool-to-Lakehouse artifacts, follow the exact Live, Partially Specified, and Offline Artifact Contract. For a complete offline fixture, use only the Offline Lakehouse artifact fast path.
11. An offline Dedicated Pool artifact request still requires this skill. For a complete large-procedure audit request, read resources/dedicated-pool-large-procedure-audit.md exactly once, then use one cwd-relative generator and the required generated verifier; do not load the standard conversion resources too. In generated JSON, store artifact-root-relative POSIX paths exactly as requested, never filesystem paths that include the output root. Keep separate constants for recorded relative paths and disk locations. Compute full deterministic block IDs before writing notebook markers or ledger mappings, and package attempt evidence for Converted blocks only.
12. Keep Spark, Dedicated Pool-to-Lakehouse, and Dedicated Pool-to-Warehouse execution paths separate. If the target is not explicit, ask the user to choose it before loading path-specific resources. For a Fabric Warehouse target, explicitly state that the complete DISTRIBUTION and CLUSTERED COLUMNSTORE INDEX declarations are removed because Fabric manages distribution, storage, and indexing; a bare mention of either source clause is insufficient.
13. For Spark workspace migration plans, preserve the canonical phase labels from this skill: Phase 0 Spark Pools to Environments, Phase 1 databases/storage to Lakehouses or shortcuts, Phase 2 notebooks, and Phase 3 Spark Job Definitions. Do not renumber discovery as Phase 0.
14. For Dedicated Pool feature-risk assessments and workspace item projections, follow the exact Feature-Risk Assessment and Workspace Projection Contract and load resources/dedicated-pool-gap-assessment.md; the Phase 2 approval gate in Note 5 remains blocking.
15. For Dedicated Pool-to-Lakehouse publication and hashes, follow the exact Lakehouse Publication and Hash Contract.

Synapse Analytics → Microsoft Fabric Migration

Prerequisite Knowledge

These companion documents provide general Fabric REST patterns. Do NOT read them upfront — reference only when a specific phase requires a pattern not already covered in this skill's resource files:

• COMMON-CORE.md — General Fabric REST API patterns, authentication & token audiences, item discovery via JMESPath
• COMMON-CLI.md — az rest / az login CLI patterns, authentication recipes
• SPARK-AUTHORING-CORE.md — Notebook/lakehouse creation (already covered in spark-item-migration.md and lake-database-migration.md)
• SQLDW-AUTHORING-CORE.md — Fabric Warehouse T-SQL; use it directly within the Dedicated Pool migration workflow, and delegate standalone Warehouse work to sqldw-cli

Auth, API endpoints, and item payloads are fully documented in this skill's own files. The common docs above are fallback references only.

---

Resource Routing

Load only the selected path. Do not read all resources upfront.

| Request | Load | |---|---| | Full workspace migration | migration-orchestrator.md | | Cross-workload planning, sizing, parity, troubleshooting, or handoff | migration-planning-reference.md | | Complete offline Dedicated Pool to Lakehouse fixture | dedicated-pool-to-lakehouse.md fast path only | | Live or incomplete Dedicated Pool to Lakehouse | dedicated-pool-to-lakehouse.md and dedicated-pool-conversion.md | | Dedicated Pool risk report or target-design approval | dedicated-pool-gap-assessment.md | | Large-procedure audit | dedicated-pool-large-procedure-audit.md only | | Publishing, updating, or verifying generated Dedicated Pool notebooks | dedicated-pool-deployment.md | | Dedicated Pool to Warehouse | The matching dw-* resource selected in the Warehouse route below | | Spark Pool, Lake Database, external HMS, Notebook, or SJD phase | spark-pool-migration.md, lake-database-migration.md, external-hms-migration.md, or spark-item-migration.md | | API/code/connectivity refactoring | utility-api-mapping.md, connector-refactoring.md, connectivity-migration.md, or code-patterns.md | | Validation, security, reporting, or runtime compatibility | validation-testing.md, security-governance.md, migration-report.md, or library-compatibility.md |

---

Choose Migration Path

Identify the workload before loading implementation resources:

| Source workload | Target | Route | |---|---|---| | Spark Pools, notebooks, Spark Job Definitions, Lake Databases, external HMS, Linked Services | Fabric Spark, Lakehouse, Environment, Data Connections, Shortcuts | Use migration-planning-reference.md and migration-orchestrator.md | | Dedicated SQL pool schema and code artifacts | Fabric Lakehouse and Spark SQL notebooks, without source rows | Use dedicated-pool-to-lakehouse.md and its phase resources | | Dedicated SQL pool in a Synapse workspace or standalone dedicated SQL pool | Fabric Warehouse, with optional separately approved data migration | Use the Warehouse