Synapse Migration

MicrosoftOfficialPublished by Microsoft

Skill
Workflow
Software development
MIT
Low risk
Has scripts

From the author

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.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The synapse-migration skill provides a structured, phased workflow for transitioning Synapse Analytics workspaces to Microsoft Fabric. It covers the migration of Spark items, Lake Databases, Linked Services, and Dedicated SQL Pool schema and stored procedures. The skill emphasizes a dependency-ordered approach, requiring gap assessment and explicit approval before conversion. It distinguishes between migrating to a Fabric Lakehouse (schema and code only, no data movement) and a Fabric Warehouse, while providing specific routing for dependent pipeline callers.

What it does

Discovers and classifies Synapse workspace artifacts.
Converts Dedicated SQL Pool schema and stored procedures to Spark SQL notebooks or Warehouse objects.
Migrates Spark items, including notebooks and Spark Job Definitions, to Fabric equivalents.
Maps Linked Services to Fabric Data Connections or OneLake Shortcuts.
Manages the migration of approved dependent pipeline callers.
Validates persisted definitions and artifacts against established contracts.

When to use it

When migrating a full Synapse workspace to Microsoft Fabric.
When converting Dedicated SQL Pool schema and procedures to a Lakehouse or Warehouse.
When porting Spark pools, notebooks, or Spark Job Definitions to Fabric.
When replacing Synapse Linked Services with Fabric-native connectivity.

Advantages

Ensures dependency-ordered migration to maintain system integrity.
Provides clear routing for different workload types (Lakehouse vs. Warehouse).
Enforces strict validation and approval gates for behavior-changing decisions.
Supports incremental migration rather than high-risk big-bang cutovers.
Standardizes the conversion of T-SQL procedures to executable Spark SQL notebooks.

Usage examples

“Migrate this Dedicated SQL Pool DACPAC to a Fabric Lakehouse and convert the procedures.”: The agent will assess gaps, obtain approval for procedure-to-notebook mappings, create a migration manifest, convert schema/code artifacts, and validate the results.
“Migrate this Dedicated SQL Pool to Fabric Warehouse.”: The agent will assess DDL compatibility, remove unsupported distribution/index declarations, obtain provisioning consent, and prepare for potential data migration.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/microsoft/synapse-migration/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip synapse-migration.zip -d .agents/skills

Documentation by Microsoft

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 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
To find workspace details (including its ID) from a workspace name: list all workspaces, then use JMESPath filtering.
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.
Treat a source Dedicated SQL Pool as read-only. Do not run source DDL, DML, stored procedures, or create sample objects.
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.
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 once as the router, then load only the current phase reference.
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.
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.
Before executing a specialized Dedicated Pool workflow, read the matching contract in dedicated-pool-execution-contracts.md. Its validation, hashing, request-body, resume, and completion-language requirements are mandatory.
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.
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.
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

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

For full-workspace orchestration, read migration-orchestrator.md. For a Dedicated Pool-to-Lakehouse migration, use 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
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
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, enable Delta `columnMapping` selectively and only with approval."	dedicated-pool-execution-contracts.md
Large or complex stored procedure	For a complete offline contract, read only the audit resource once, use one run-local generator and one verifier, do not inspect implementation scripts or generated outputs, and stop after successful verification	dedicated-pool-large-procedure-audit.md
Spark pool	Convert configuration and libraries to a Fabric Environment	spark-pool-migration.md
Lake Database or HMS	Create or bind the target Lakehouse	lake-database-migration.md or external-hms-migration.md
Notebook or Spark Job Definition	Port code, bindings, parameters, and runtime settings	spark-item-migration.md
Linked Service	Choose a Fabric Data Connection for external services or a OneLake Shortcut for ADLS Gen2/Blob	connectivity-migration.md
Approved dependent procedure callers	Run the internal closure-preserving sub-flow after notebook readback	dedicated-pool-dependent-pipelines.md
Standalone pipeline migration	Delegate	`pipeline-migration`
Dedicated SQL Pool to Fabric Warehouse	Run the source extraction, DDL compatibility, approval, optional data, security, and validation route	dw-source-and-extraction.md, then the matching `dw-*` phase resource
Standalone Fabric Warehouse administration	Delegate	`sqldw-cli`
Synapse Link	Use Fabric Mirroring; not covered here	—

Always report the Lake Database/HMS phase. If none is discovered, mark it NotApplicable (none discovered) while retaining the required target Lakehouse binding.

Load References On Demand

Do not preload all files. Load only the references needed for the current phase:

Need	Reference
Routing, phase order, API audiences, quick examples, troubleshooting, or post-migration handoff	workload-routing.md
Dedicated Pool execution variants and response contracts	dedicated-pool-execution-contracts.md
Dedicated Pool discovery	dedicated-pool-discovery.md
Gap assessment and mapping approval	dedicated-pool-gap-assessment.md
Procedure conversion and notebook shape	dedicated-pool-conversion.md
Schema/notebook deployment	dedicated-pool-deployment.md
Dedicated Pool validation	dedicated-pool-validation.md
Runtime/library compatibility	feature-parity.md and library-compatibility.md
`mssparkutils` and connector refactoring	utility-api-mapping.md, connector-refactoring.md, and code-patterns.md
Capacity planning	capacity-sizing.md
Dedicated Pool-to-Warehouse source discovery and extraction	dw-source-and-extraction.md
Warehouse DDL compatibility and deployment	dw-ddl-compatibility.md
Separately approved Warehouse data migration	dw-data-migration.md
Warehouse security and validation	dw-security-validation.md
Validation, reporting, and production readiness	validation-testing.md, migration-report.md, and security-governance.md

Use COMMON-CLI.md only for shared authentication and az rest mechanics not already covered by the phase resource. Use COMMON-CORE.md only for shared Fabric REST patterns.

Must

Preserve every stored-procedure input contract, source default, source decision, and approved target mapping.
Block conversion until gap dispositions, notebook names, dependency grouping, and target workspace placement are explicitly approved.
Use SqlPackage/DMVs for source discovery, Fabric REST for item management, and Fabric Livy statements for Lakehouse schema and Delta execution.
Run the maintained validators required by the selected execution contract; never replace them with ad hoc JSON or cell-shape checks.
Choose the Lakehouse or Warehouse target before loading implementation resources; never apply Warehouse data-movement rules to Lakehouse artifact conversion.
Before persisting any dependent-pipeline source definition, recursively inspect it for secret-bearing or uncertain properties; block the complete selected closure without writing the artifact or mutating a target when any are found.
In every dependent-pipeline response, including guidance-only and pre-approval explanations, state: "Use a TridentNotebook activity with exact target identities typeProperties.notebookId and typeProperties.workspaceId, and pass inputs through typeProperties.notebookParameters." Then state: "After deployment, read back each pipeline with POST /v1/workspaces/{workspaceId}/items/{dataPipelineId}/getDefinition and validate its canonical hash and structural bindings."
For every Linked Service response, first state both replacement classes: Fabric Data Connections for external databases/services and OneLake Shortcuts for ADLS Gen2/Blob storage; then identify which class applies.
Replace mssparkutils with notebookutils, Linked Services with the correct Fabric connection class, and spark.read.synapsesql() with a supported OneLake or JDBC pattern.
Externalize workspace and item IDs through parameters or Variable Libraries.
Keep phase status concise, emit bounded heartbeats for long operations, and persist per-object evidence in the manifest.

Prefer

OneLake Shortcuts over copying data.
Fabric Environments for reproducible libraries and Spark settings.
Incremental, dependency-ordered migration over big-bang cutover.
Parameterized notebooks and Variable Libraries for environment promotion.
Lakehouse SQL Endpoint for compatible Serverless SQL Pool read workloads.

Avoid

Do not execute generated notebooks or pipelines as part of artifact migration.
Do not broaden a selected dependent-pipeline closure or route that internal sub-flow to pipeline-migration.
Do not use sqlcmd against the target Fabric Warehouse; use the registered SQL endpoint tooling required by the Warehouse resource.
Do not preserve Synapse distribution/storage hints, PolyBase DDL, Linked Service connection strings, or pool-level library installation patterns verbatim.
Do not use target notebooks to orchestrate the migration itself.
Do not hardcode workspace IDs, item IDs, credentials, connection strings, or environment-specific paths.

Examples

Prompt: "Migrate this Dedicated SQL Pool DACPAC to a Fabric Lakehouse and convert the procedures."

Response behavior: Assess gaps first, present and obtain approval for the complete procedure-to-notebook mapping and workspace placement, create the manifest, convert approved schema/code artifacts without moving source rows, validate persisted definitions, and report the resolved Lakehouse and artifact evidence.

Prompt: "Migrate this ADF pipeline to Fabric."

Response behavior: Route to pipeline-migration. Keep it here only when the pipeline is an explicitly approved dependent caller discovered inside an active Dedicated Pool-to-Lakehouse migration.

Prompt: "Migrate this Dedicated SQL Pool to Fabric Warehouse."

Response behavior: Keep this inside synapse-migration, assess DDL compatibility, remove unsupported distribution and columnstore declarations, obtain provisioning consent, and ask separately before any restored-source data migration.

For code transformations and edge cases, load workload-routing.md and the phase-specific resource rather than expanding the main instructions.

Files

ATTRIBUTION.mdAdded by AutoGineer879 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md14.3 KiB
apm.yml597 B
references/dedicated-pool-execution-contracts.md14.5 KiB
references/workload-routing.md6.0 KiB
resources/capacity-sizing.md4.1 KiB
resources/code-patterns.md8.4 KiB
resources/connectivity-migration.md6.4 KiB
resources/connector-refactoring.md13.8 KiB
resources/dedicated-pool-conversion.md39.2 KiB
resources/dedicated-pool-dependent-pipelines.md23.3 KiB
resources/dedicated-pool-deployment.md20.0 KiB
resources/dedicated-pool-discovery.md17.8 KiB
resources/dedicated-pool-gap-assessment.md17.4 KiB
resources/dedicated-pool-large-procedure-audit.md24.5 KiB
resources/dedicated-pool-to-lakehouse.md17.9 KiB
resources/dedicated-pool-validation.md17.2 KiB
resources/dw-data-migration.md13.7 KiB
resources/dw-ddl-compatibility.md9.4 KiB
resources/dw-security-validation.md15.6 KiB
resources/dw-source-and-extraction.md8.0 KiB
resources/external-hms-migration.md20.2 KiB
resources/feature-parity.md5.4 KiB
resources/lake-database-migration.md34.8 KiB
resources/library-compatibility.md7.2 KiB
resources/migration-gotchas.md16.1 KiB
resources/migration-orchestrator.md63.0 KiB
resources/migration-planning-reference.md16.3 KiB
resources/migration-report.md16.9 KiB
resources/security-governance.md47.4 KiB
resources/spark-item-migration.md19.2 KiB
resources/spark-pool-migration.md16.3 KiB
resources/utility-api-mapping.md5.4 KiB
resources/validation-testing.md14.5 KiB
scripts/Invoke-DedicatedPoolTool.ps1Script941 B
scripts/dedicated-pool-tool/DedicatedPoolMessageSanitizer.csScript2.1 KiB
scripts/dedicated-pool-tool/DedicatedPoolTool.csproj346 B
scripts/dedicated-pool-tool/Program.csScript31.4 KiB
scripts/dedicated_pool_runtime.pyScript116.9 KiB
scripts/validate_dedicated_pool_spark.pyScript24.8 KiB

resources/migration-planning-reference.md

Migration Planning Reference

Load this reference only for cross-workload planning, target comparison, capacity planning, feature-parity review, troubleshooting, post-migration handoff, or the detailed Dedicated Pool contracts routed here from SKILL.md. Do not load it for a path-specific execution request whose focused resource already supplies the required contract.

Detailed Dedicated Pool Contracts

Live, Partially Specified, and Offline Artifact Contract

Before generating live or partially specified Dedicated Pool artifacts, read both dedicated-pool-to-lakehouse.md and dedicated-pool-conversion.md. A complete offline request that already supplies inventory, target binding, approvals, exact artifact schemas, and validation contracts is the exception: follow the Offline Lakehouse Artifact Fast Path. Transcribe every requested property name, value, and executable predicate exactly; do not substitute aliases. In expected-schema.json, the table discriminator is objectType and its identity is sourceStableId; do not emit type or sourceIdentifier. Character length remains part of sourceType and is not numeric precision: for every NVARCHAR(n) to STRING mapping, set precision and scale to JSON null, never to n. In manifest parameterMappings, the parameter identity property is sourceParameter; do not emit parameterName there. A parameterized notebook uses a first Python code cell tagged parameters, followed immediately by one validation-only Python bridge that includes its permitted imports and transports each scalar through a direct spark.conf.set call with the fully qualified configuration key. Never emit a %%configure cell or object-valued parameter map for this contract. Every later code cell begins with %%sql; a parameterless notebook starts directly with %%sql and has no parameter bridge. Use try_cast for pre-mutation type validation, but immediate CAST in transformation predicates, including CAST('${...IncludeInactive}' AS BOOLEAN) directly without LOWER. The verifier must assert every supplied property and reject aliases, plus validate notebook cells, typed substitutions, hashes, and contract cases rather than sampling representative fields. If verification fails, fix the generator and rerun generation and verification; never patch artifacts. For a completed offline Lakehouse conversion, start the response Fabric Lakehouse <name> migration: generated notebooks contain executable translated Spark SQL in %%sql cells; no source rows were moved.

Feature-Risk Assessment and Workspace Projection Contract

For Dedicated Pool feature-risk assessments, address every material feature named in the request or discovered catalogs; when present, give distribution, multi-statement transactions, row-level security, workload management, and shared staging logic their own representative risk rows rather than collapsing them into generic categories. Record unsupported, redesign, and unknown dispositions instead of silently omitting a feature. Explicitly state that the Phase 2 approval gate in Note 5 blocks conversion until the customer approves the complete stored-procedure mapping. Before approval, compare candidate mapping scenarios and always calculate and state 1:1 projected notebook count = discovered procedure count; do not defer that projection because the final mapping or workspace placement is unknown. For N:1 and N:N, count distinct proposed target notebook components when supplied, otherwise mark those candidate counts unknown. Calculate each target workspace's projected total as current items plus planned non-notebook items, assigned notebooks, and reserved operational headroom; compare it with the documented 1,000-item limit and block an over-limit or unknown-capacity design until it is repartitioned or clarified.

Every feature-risk response must state: Conversion remains blocked until the customer approves the complete stored-procedure mapping. Spell out multi-statement transaction; do not abbreviate it as txn. Keep these statements explicit even when a risk matrix or closing approval sentence conveys the same meaning.

Lakehouse Publication and Hash Contract

For Dedicated Pool-to-Lakehouse outputs, explicitly narrate the migration to the Fabric Lakehouse target, publish notebook definitions with format: "ipynb", and compute each manifest contentHash from the final notebook bytes only after all writes are complete. Any later notebook change requires recomputing the hash before validation or publication.

API-Driven Migration Workflow

This skill supports programmatic migration of Synapse Spark items via REST APIs (no UI-based Migration Assistant required).

Authentication

Target	Token Audience
Synapse ARM (management plane)	`https://management.azure.com`
Synapse Data Plane	`https://dev.azuresynapse.net`
Fabric REST API	`https://api.fabric.microsoft.com`

Use the token-acquisition recipe in COMMON-CLI § Authentication Recipes with the audiences above.

Migration Phases (Execute in Order)

Phase	Synapse Source	Fabric Target	Resource
Phase 0	Spark Pool	Environment	spark-pool-migration.md
Phase 1	Lake Database (built-in HMS)	Lakehouse	lake-database-migration.md
Phase 1	External Hive Metastore	Lakehouse	external-hms-migration.md
Phase 1b	Ad-hoc `abfss://` storage paths	OneLake Shortcuts	migration-orchestrator.md (migrate-and-modernize only)
Phase 2	Notebooks	Notebook	spark-item-migration.md
Phase 3	Spark Job Definitions	SJD	spark-item-migration.md
Final	Validation & Testing	—	validation-testing.md
Optional	Security & Governance	—	security-governance.md

Phase order matters: Environments (Phase 0) must exist before notebooks/SJDs can bind to them. Lakehouses (Phase 1) must exist before notebooks can bind to them (Phase 2).

For the full execution flow with sub-steps, decision points, lift-and-shift vs. modernize paths, and error recovery, see migration-orchestrator.md.

REST API Quick Reference

All Synapse and Fabric API endpoints with request/response examples are in migration-orchestrator.md (Steps 2a–2e). Authentication tokens:

Target	Token Audience
Synapse ARM	`https://management.azure.com`
Synapse Data Plane	`https://dev.azuresynapse.net`
Fabric REST API	`https://api.fabric.microsoft.com`

API docs: Synapse ARM · Synapse Data Plane · Fabric Items · Fabric Shortcuts · Fabric Connections · Fabric Environments

Migration Workload Map

Use this table to determine the correct Fabric target for each Synapse component:

Synapse Component	Fabric Target	Notes
Spark Pool (notebooks, jobs)	Fabric Environment + Notebook or Spark Job Definition	Migrate Spark configuration, libraries, and code using the Spark-specific resources in this skill.
Dedicated SQL Pool	Fabric Lakehouse (stored procedures → Spark SQL notebooks; tables/views → Lakehouse objects) or Fabric Warehouse	Lakehouse path: extract metadata with SqlPackage/catalog queries, assess projected workspace item demand, require the user to provide and approve a `1:1`, `N:1`, or `N:N` procedure-notebook mapping (applies ONLY to stored procedures, NOT views), then convert schema and code artifacts. Tables and views are deployed as Lakehouse schema objects via Livy; only stored procedures convert to notebooks. Source table rows are not migrated; see dedicated-pool-to-lakehouse.md. Warehouse migration path: use the `dw-*` resources in this skill; delegate only unrelated general Warehouse authoring to `sqldw-cli`.
Serverless SQL Pool	Lakehouse SQL Endpoint	Read-only Delta/Parquet queries; no DDL required
Synapse Pipelines	Fabric Data Pipelines	Activity types, triggers, and expressions are broadly compatible. Pipeline migration resource not yet available — separate migration track.
Synapse Link for Cosmos DB / SQL	Fabric Mirroring	Native mirroring replaces the Synapse Link connector pattern. Not covered by this skill.
Linked Services	Data Connections (external) / OneLake Shortcuts (storage)	See connectivity-migration.md
Integration Datasets	Fabric Pipeline source/sink config	Dataset definitions are inlined into pipeline activities in Fabric. Not covered by this skill.
Managed Virtual Networks	Fabric Managed Private Endpoints	Configure in Fabric capacity settings
Synapse Studio	Fabric workspace	All artifact types live in a single workspace with Git integration

Decision Tree: Which Fabric Spark Workload?

Synapse Spark workload
├── Interactive notebook with data exploration → Fabric Notebook (attached to Lakehouse)
├── Scheduled/production job → Spark Job Definition (SJD)
├── T-SQL over files/Delta → Lakehouse SQL Endpoint (no migration needed — just point to OneLake)
└── Real-time ingest → Fabric Eventstream + Lakehouse

T-SQL & Spark Configuration Differences

For Spark-oriented T-SQL surface gaps and Spark configuration mappings, see feature-parity.md. For a dedicated SQL pool migration assessment, use dw-ddl-compatibility.md.

Key actions: Replace PolyBase CREATE EXTERNAL TABLE with COPY INTO, and show an unmistakable OneLake/Fabric source such as https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.Lakehouse/Files/... when giving the replacement example. Replace spark.read.synapsesql() with OneLake shortcuts or JDBC. For Dedicated Pool-to-Warehouse migration, follow the dw-* resources in this skill; delegate only general Warehouse authoring outside that migration path to sqldw-cli.

Capacity Sizing Reference

For Synapse pool → Fabric SKU mapping tables, sizing decision guide, and cost model comparison, see capacity-sizing.md.

Quick guide: Dev/test = F8–F16 with Starter Pool; standard production = F32–F64; enterprise = F128+. Use Fabric Trial (free F64, 60 days) for migration validation.

Feature Parity Reference

Full Synapse → Fabric feature matrix (28 features), T-SQL surface area gaps, and Spark configuration differences are in feature-parity.md.

Key gaps (⚠️/❌): spark.read.synapsesql() replaced by JDBC/shortcuts · Linked Services redesigned as Data Connections/Shortcuts · External HMS partial (migrate as shortcuts) · mssparkutils.env renamed to notebookutils.runtime · Result set caching ❌ · Workload management ❌ · PolyBase → COPY INTO

Migration Gotchas — Quick Reference

The full troubleshooting guide with code examples and multi-option resolutions is in migration-gotchas.md. This summary surfaces the key issues for quick scanning during migration:

#	Flag ID	Issue	Severity	Blocks?	Resolution Summary
G1	`SYNAPSESQL_NO_EQUIVALENT`	`spark.read.synapsesql()` has no Fabric equivalent	High	Yes	Replace with OneLake shortcut read, Warehouse JDBC, or Data Pipeline
G2	`LIBRARY_VERSION_CONFLICT`	Custom library version conflicts with Fabric Runtime	Medium	Maybe	Pin compatible version in Environment, or find Fabric-native alternative
G3	`DELTA_PROTOCOL_MISMATCH`	Delta protocol version incompatibility	High	Yes	Rewrite table with matching protocol (`delta.minReaderVersion`/`minWriterVersion`)
G4	`SECURITY_MODEL_INCOMPATIBLE`	Synapse managed identity / IP firewall not portable	Medium	Yes	Reconfigure as Workspace Identity + Fabric Managed Private Endpoints
G5	`GPU_POOL_UNSUPPORTED`	GPU-accelerated Spark pools not available in Fabric	High	Yes	Migration blocker — keep workload in Synapse or use Azure ML
G6	`DOTNET_SPARK_UNSUPPORTED`	.NET for Spark (C#/F# SJDs) not supported	High	Yes	Migration blocker — rewrite in PySpark or keep in Synapse
G7	`NULLABLE_POOL_REFERENCE`	`bigDataPool`/`targetBigDataPool` field is `null` (not missing) — causes `NoneType` crash	Medium	No	Use `(x.get("bigDataPool") or {}).get(...)` pattern
G8	`SESSION_CONFIG_IGNORED`	Some `%%configure` keys silently ignored in Fabric	Low	No	Remove unsupported keys; use Environment for pool-level config
G9	`SHORTCUT_CONNECTION_FAILED`	ADLS shortcut creation fails (connection/permission)	High	Partial	Verify connection credential type (Key > WorkspaceIdentity > OAuth2) and RBAC

Post-Migration: What's Next

After completing Spark Phases 0–3 or the dedicated SQL pool steps and validation, hand off to these companion skills for ongoing operations:

Agentic Exploration Workflow

Use this sequence only after a separately approved process has loaded data into Fabric Lakehouses. The Dedicated Pool to Lakehouse pattern in this skill migrates schema and code artifacts only, so it must stop after artifact validation and must not run this workflow.

For migrations that explicitly include approved data movement and data validation:

Discover → List schemas, tables, and row counts via Lakehouse SQL Endpoint (sqldw-cli)
Sample → SELECT TOP 5 on migrated tables to verify data integrity
Validate → Run validation checks from validation-testing.md (V1–V6)
Explore → Write Spark or T-SQL queries against migrated data using spark-cli or sqldw-cli
Build → Create Gold-layer aggregations with e2e-medallion-architecture (Bronze → Silver → Gold)
Consume → Build semantic models and reports with semantic-model-authoring

Companion Skill Cross-References

Post-Migration Task	Skill	When to Use
Interactive Lakehouse SQL queries	`sqldw-cli`	Exploring migrated data via SQL Endpoint
Interactive PySpark exploration	`spark-cli`	Ad-hoc Spark queries on migrated Lakehouses
Notebook & SJD authoring (new)	`spark-cli`	Creating new Spark items post-migration
Medallion architecture build-out	`e2e-medallion-architecture`	Structuring Bronze/Silver/Gold after lift-and-shift
Warehouse performance monitoring	`sqldw-cli`	Diagnosing slow queries on Fabric Warehouse
Semantic model creation	`semantic-model-authoring`	Building Power BI models over migrated data
Report consumption & DAX	`fabriciq`	Querying existing semantic models
KQL analytics	`eventhouse-cli`	If migrating real-time workloads to Eventhouse

Variable Library for Environment Promotion

After migration, avoid hardcoded workspace/item IDs by centralizing configuration in a Variable Library item:

# Read config from Variable Library — works in notebooks
lib = notebookutils.variableLibrary.getLibrary("MigrationConfig")
lakehouse_name = lib.lakehouse_name
workspace_id = lib.workspace_id

# ❌ WRONG — .get() does not exist
# notebookutils.variableLibrary.get("MigrationConfig", "lakehouse_name")

Use Value Sets (valueSets/dev.json, valueSets/prod.json) to promote across environments without code changes
Boolean values are returned as strings — compare with .lower() == "true", not bool()
In Data Pipelines, reference via @pipeline().libraryVariables.<name> (not @variables())
Full Variable Library patterns → see common/notebook-authoring/context-and-params.md § Variable Library

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Low risk

Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills-for-fabric · skills/synapse-migration · commit f8fac11

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

Also distributed in

microsoft/skills-for-fabric

AutoGineer is not affiliated with or endorsed by Microsoft or Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download synapse-migration.zip