synapse-migration

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.

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 — they are replaced by Data Connections (for external sources) and OneLake Shortcuts (for storage mounts)
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 source Dedicated Pool as read-only. Never create sample or synthetic data, schemas, tables, views, procedures, users, roles, or grants in the source. Do not run source DDL, DML, or stored procedures. Source operations in this workflow are limited to metadata discovery and metadata-based validation; route any requested source mutation to a separate, explicitly scoped workflow.
7. Dedicated Pool data migration is out of scope. Never export, stage, copy, upload, shortcut, transfer, or load source table rows, and never run row-level or business-result equivalence queries. This skill migrates schema and executable code artifacts only.
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 Dedicated Pool artifacts, read both resources/dedicated-pool-to-lakehouse.md and resources/dedicated-pool-conversion.md. In manifest parameterMappings, use sourceParameter for the discovered source name; parameterName is reserved for object-valued conf entries inside notebook %%configure.
11. A local or offline Dedicated Pool artifact request still requires this skill. For a large or complex procedure, also read resources/dedicated-pool-large-procedure-audit.md before generating artifacts.