/synapse-migration

name: synapse-migration
description: "Converts Synapse workspaces to Fabric: Spark items, Lake Databases, Linked Services, and Dedicated SQL Pool schema/procedures for Lakehouse or Warehouse. During Pool-to-Lakehouse migration only, can migrate approved dependent procedure callers after notebook readiness. Excludes standalone pipelines and Warehouse administration. Triggers: Synapse workspace to Fabric, Dedicated SQL Pool to Lakehouse, Dedicated SQL Pool to Fabric Warehouse."

> **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](resources/dedicated-pool-to-lakehouse.md#offline-lakehouse-artifact-fast-path); do not load `migration-planning-reference.md`, `dedicated-pool-conversion.md`, or implementation scripts. Use one generator for artifacts and final-byte hashes, then one verifier. Do not inspect generated files or run post-pass spot checks. For every optional non-null source default, set `missingValueBehavior` to `UseSourceDefault` and restore that default before validation. 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. Treat a source Dedicated SQL Pool as read-only. Do not run source DDL, DML, stored procedures, or create sample objects. > 4. Dedicated Pool-to-Lakehouse data movement is out of scope. Migrate schema and executable code artifacts only; do not copy source rows or run row-level/business-result equivalence queries. The separate Warehouse route may move data only from a separately approved restored export copy under its own consent gate and restored-source contract. > 5. For Dedicated Pool-to-Lakehouse requests, complete gap assessment, explicit mapping approval, manifest creation, conversion, deployment, and validation in order. Read [dedicated-pool-to-lakehouse.md](resources/dedicated-pool-to-lakehouse.md) once as the router, then load only the current phase reference. > 6. Stored-procedure `1:1`, `N:1`, and `N:N` mappings never apply to views. Views remain schema objects; procedures become traceable Spark SQL notebooks with executable `%%sql` transformation cells. > 7. Dependent ADF/Synapse callers are conditional scope, not automatic scope. Discover them during assessment, require a separate complete-closure approval, and migrate them only after notebook readiness. Route standalone pipeline requests to `pipeline-migration`. > 8. Before executing a specialized Dedicated Pool workflow, read the matching contract in [dedicated-pool-execution-contracts.md](references/dedicated-pool-execution-contracts.md). Its validation, hashing, request-body, resume, and completion-language requirements are mandatory. > 9. Keep Lakehouse and Warehouse paths separate. If the target is unclear, ask before loading path-specific resources. Lakehouse conversion never moves source rows; Warehouse data migration requires its own explicit consent gate and restored-source contract. > 10. 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. > 11. Run setup DDL and CETAS only against the separately approved restored export copy after proving it is not the original production source.

Synapse Analytics to Microsoft Fabric Migration

Core Workflow

1. **Discover** the Synapse workspace and classify every source artifact. 2. **Choose targets** using [workload-routing.md](references/workload-routing.md). 3. **Assess gaps before conversion**, including runtime, library, connectivity, T-SQL, security, and capacity constraints. 4. **Obtain approval** for behavior-changing decisions, target placement, and every stored-procedure-to-notebook mapping. 5. **Create or update `migration-manifest.json`** and persist approval, per-object status, hashes, and checkpoints atomically. 6. **Convert and deploy in dependency order**, loading only the current phase resource. 7. **Validate persisted definitions and artifacts** without executing generated notebooks or pipelines unless a separately approved workflow explicitly requires execution. 8. **Report** completed, blocked, skipped, and pending objects without exposing credentials or sensitive values.

For full-workspace orchestration, read [migration-orchestrator.md](resources/migration-orchestrator.md). For a Dedicated Pool-to-Lakehouse migration, use [dedicated-pool-to-lakehouse.md](resources/dedicated-pool-to-lakehouse.md) as the phase router. For a Warehouse target, load only the matching `dw-*` resource.

Scope Routing

| Request | Action | Load | |---|---|---| | Full Synapse workspace migration | Run phased discovery and migration | [migration-orchestrator.md](resources/migration-orchestrator.md) | | Dedicated SQL Pool schema/code to Lakehouse | Run the strict assessment-to-validation workflow. For guidance-only notebook publication, explicitly state: "The stored procedures were converted from T-SQL to Spark SQL before publication." | [dedicated-pool-to-lakehouse.md](resources/dedicated-pool-to-lakehouse.md) | | Guidance-only Dedicated Pool incremental deployment hardening | Answer directly from the focused checklist; do not search scripts or load phase resources. State: "For columns with special characters, en