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/connector-refactoring.md

Connector-Specific Refactoring — Kusto, Cosmos DB, Token Library, ADLS OAuth

Detailed before/after patterns for migrating Synapse connector code to Fabric. These go beyond the general linked-service replacement covered in connectivity-migration.md.

Pre-check: Run the pre-refactoring audit to find affected notebooks. The search patterns below map to specific connectors.

Azure Data Explorer (Kusto) Connector

Search pattern: kusto.spark.synapse or spark.synapse.linkedService.*DataExplorer

Reading from Kusto

# ❌ BEFORE — Synapse: Kusto via linked service
kustoDF = (spark.read
    .format("com.microsoft.kusto.spark.synapse.datasource")
    .option("spark.synapse.linkedService", "AzureDataExplorer1")
    .option("kustoCluster", "https://mycluster.kusto.windows.net")
    .option("kustoDatabase", "mydb")
    .option("kustoQuery", "MyTable | take 100")
    .load())

# ✅ AFTER — Fabric: Kusto via access token
kustoDF = (spark.read
    .format("com.microsoft.kusto.spark.synapse.datasource")
    .option("accessToken", notebookutils.credentials.getToken("https://mycluster.kusto.windows.net"))
    .option("kustoCluster", "https://mycluster.kusto.windows.net")
    .option("kustoDatabase", "mydb")
    .option("kustoQuery", "MyTable | take 100")
    .load())

Writing to Kusto

# ❌ BEFORE — Synapse
(df.write
    .format("com.microsoft.kusto.spark.synapse.datasource")
    .option("spark.synapse.linkedService", "AzureDataExplorer1")
    .option("kustoCluster", "https://mycluster.kusto.windows.net")
    .option("kustoDatabase", "mydb")
    .option("kustoTable", "MyTargetTable")
    .option("tableCreateOptions", "CreateIfNotExist")
    .mode("Append")
    .save())

# ✅ AFTER — Fabric
(df.write
    .format("com.microsoft.kusto.spark.synapse.datasource")
    .option("accessToken", notebookutils.credentials.getToken("https://mycluster.kusto.windows.net"))
    .option("kustoCluster", "https://mycluster.kusto.windows.net")
    .option("kustoDatabase", "mydb")
    .option("kustoTable", "MyTargetTable")
    .option("tableCreateOptions", "CreateIfNotExist")
    .mode("Append")
    .save())

Changes:

Remove .option("spark.synapse.linkedService", "...")
Add .option("accessToken", notebookutils.credentials.getToken("<cluster_url>"))
All other options (kustoCluster, kustoDatabase, kustoQuery, kustoTable) remain unchanged

Cosmos DB Connector (OLTP)

Search pattern: cosmos.oltp or spark.synapse.linkedService.*Cosmos or getSecretWithLS.*cosmos

Reading from Cosmos DB

# ❌ BEFORE — Synapse: Cosmos DB via linked service
cosmosDF = (spark.read
    .format("cosmos.oltp")
    .option("spark.synapse.linkedService", "CosmosDbLS")
    .option("spark.cosmos.container", "mycontainer")
    .option("spark.cosmos.read.inferSchema.enabled", "true")
    .load())

# ✅ AFTER — Fabric: Cosmos DB via Key Vault secret
cosmos_key = notebookutils.credentials.getSecret(
    "https://mykeyvault.vault.azure.net/", "cosmos-account-key"
)

cosmosDF = (spark.read
    .format("cosmos.oltp")
    .option("spark.cosmos.accountEndpoint", "https://mycosmosaccount.documents.azure.com:443/")
    .option("spark.cosmos.accountKey", cosmos_key)
    .option("spark.cosmos.database", "mydb")
    .option("spark.cosmos.container", "mycontainer")
    .option("spark.cosmos.read.inferSchema.enabled", "true")
    .load())

Writing to Cosmos DB

# ❌ BEFORE — Synapse
(df.write
    .format("cosmos.oltp")
    .option("spark.synapse.linkedService", "CosmosDbLS")
    .option("spark.cosmos.container", "mycontainer")
    .option("spark.cosmos.write.strategy", "ItemOverwrite")
    .mode("Append")
    .save())

# ✅ AFTER — Fabric
cosmos_key = notebookutils.credentials.getSecret(
    "https://mykeyvault.vault.azure.net/", "cosmos-account-key"
)

(df.write
    .format("cosmos.oltp")
    .option("spark.cosmos.accountEndpoint", "https://mycosmosaccount.documents.azure.com:443/")
    .option("spark.cosmos.accountKey", cosmos_key)
    .option("spark.cosmos.database", "mydb")
    .option("spark.cosmos.container", "mycontainer")
    .option("spark.cosmos.write.strategy", "ItemOverwrite")
    .mode("Append")
    .save())

Changes:

Remove .option("spark.synapse.linkedService", "...")
Add .option("spark.cosmos.accountEndpoint", "...")
Retrieve account key from Key Vault: notebookutils.credentials.getSecret(vaultUrl, secretName)
Add .option("spark.cosmos.accountKey", cosmos_key)
Add .option("spark.cosmos.database", "...") — linked service auto-resolved this; now explicit

Cosmos DB analytics connector (azure-cosmos-analytics-spark): This JAR is missing from Fabric Runtime 1.3. If your SJDs use com.azure.cosmos.spark with the analytics store, upload the JAR to your Fabric Environment. See library-compatibility.md.

Cosmos DB Connector — Spark Config Style

Some notebooks set Cosmos DB connection at the Spark config level rather than per-read/write:

# ❌ BEFORE — Synapse: Spark config with linked service
spark.conf.set("spark.cosmos.linkedService", "CosmosDbLS")
spark.conf.set("spark.cosmos.container", "events")

df = spark.read.format("cosmos.oltp").load()

# ✅ AFTER — Fabric: Spark config with direct credentials
cosmos_key = notebookutils.credentials.getSecret(
    "https://mykeyvault.vault.azure.net/", "cosmos-account-key"
)
spark.conf.set("spark.cosmos.accountEndpoint", "https://mycosmosaccount.documents.azure.com:443/")
spark.conf.set("spark.cosmos.accountKey", cosmos_key)
spark.conf.set("spark.cosmos.database", "mydb")
spark.conf.set("spark.cosmos.container", "events")

df = spark.read.format("cosmos.oltp").load()

ADLS Gen2 OAuth — LinkedServiceBasedTokenProvider → ClientCredsTokenProvider

Search pattern: LinkedServiceBasedTokenProvider or spark.storage.synapse or getPropertiesAsMap

This is the most common pattern for ADLS Gen2 access using a service principal through a Synapse linked service.

Python

# ❌ BEFORE — Synapse: OAuth via linked service token provider
spark.conf.set("spark.storage.synapse.linkedServiceName", "MyADLSLinkedService")
spark.conf.set(
    "fs.azure.account.oauth.provider.type.mystorageaccount.dfs.core.windows.net",
    "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider"
)

df = spark.read.parquet("abfss://[email protected]/data/")

# ✅ AFTER — Fabric: OAuth via standard ClientCredsTokenProvider
storage_account = "mystorageaccount"
client_id = notebookutils.credentials.getSecret("https://mykeyvault.vault.azure.net/", "sp-client-id")
client_secret = notebookutils.credentials.getSecret("https://mykeyvault.vault.azure.net/", "sp-client-secret")
tenant_id = notebookutils.credentials.getSecret("https://mykeyvault.vault.azure.net/", "tenant-id")

spark.conf.set(f"fs.azure.account.auth.type.{storage_account}.dfs.core.windows.net", "OAuth")
spark.conf.set(f"fs.azure.account.oauth.provider.type.{storage_account}.dfs.core.windows.net",
               "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set(f"fs.azure.account.oauth2.client.id.{storage_account}.dfs.core.windows.net", client_id)
spark.conf.set(f"fs.azure.account.oauth2.client.secret.{storage_account}.dfs.core.windows.net", client_secret)
spark.conf.set(f"fs.azure.account.oauth2.client.endpoint.{storage_account}.dfs.core.windows.net",
               f"https://login.microsoftonline.com/{tenant_id}/oauth2/token")

df = spark.read.parquet(f"abfss://container@{storage_account}.dfs.core.windows.net/data/")

Scala

// ❌ BEFORE — Synapse (Scala): linked service token provider
val linked_service_cfg = "MyADLSLinkedService"
val conexion = TokenLibrary.getPropertiesAsMap(linked_service_cfg)
val my_account = conexion("Endpoint").toString.substring(8)

spark.conf.set(s"fs.azure.account.oauth.provider.type.${my_account}.dfs.core.windows.net",
  "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider")
spark.conf.set("spark.storage.synapse.linkedServiceName", linked_service_cfg)

// ✅ AFTER — Fabric (Scala): standard OAuth
val storageAccount = "mystorageaccount"
val clientId = notebookutils.credentials.getSecret("https://mykeyvault.vault.azure.net/", "sp-client-id")
val clientSecret = notebookutils.credentials.getSecret("https://mykeyvault.vault.azure.net/", "sp-client-secret")
val tenantId = notebookutils.credentials.getSecret("https://mykeyvault.vault.azure.net/", "tenant-id")

spark.conf.set(s"fs.azure.account.auth.type.${storageAccount}.dfs.core.windows.net", "OAuth")
spark.conf.set(s"fs.azure.account.oauth.provider.type.${storageAccount}.dfs.core.windows.net",
  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set(s"fs.azure.account.oauth2.client.id.${storageAccount}.dfs.core.windows.net", clientId)
spark.conf.set(s"fs.azure.account.oauth2.client.secret.${storageAccount}.dfs.core.windows.net", clientSecret)
spark.conf.set(s"fs.azure.account.oauth2.client.endpoint.${storageAccount}.dfs.core.windows.net",
  s"https://login.microsoftonline.com/${tenantId}/oauth2/token")

Changes:

Remove spark.storage.synapse.linkedServiceName — not supported in Fabric
Remove TokenLibrary.getPropertiesAsMap() — not available in Fabric
Replace LinkedServiceBasedTokenProvider with ClientCredsTokenProvider
Configure client.id, client.secret, client.endpoint per storage account
Store credentials in Key Vault; retrieve via notebookutils.credentials.getSecret()

Preferred alternative: If the ADLS Gen2 data only needs to be read, create an OneLake Shortcut instead. This eliminates OAuth config entirely — the shortcut handles authentication. See connectivity-migration.md.

Token Library (Synapse-only)

Search pattern: TokenLibrary or getPropertiesAsMap

Synapse's TokenLibrary provides two capabilities, both replaced differently:

Token Acquisition

# ❌ BEFORE — Synapse: get access token via linked service
token = TokenLibrary.getAccessToken("https://database.windows.net/")

# ✅ AFTER — Fabric: use notebookutils
token = notebookutils.credentials.getToken("https://database.windows.net/")

Linked Service Property Extraction

// ❌ BEFORE — Synapse: extract linked service properties
val props = TokenLibrary.getPropertiesAsMap("MyLinkedService")
val endpoint = props("Endpoint")
val accountName = endpoint.toString.substring(8)

// ✅ AFTER — Fabric: no linked services — hardcode or parameterize
val accountName = "mystorageaccount"  // or read from notebook parameters
// If dynamic, store in Key Vault:
// val accountName = notebookutils.credentials.getSecret("https://myvault.vault.azure.net/", "storage-account-name")

Secret Retrieval via Linked Service

# ❌ BEFORE — Synapse: get secret via Key Vault linked service
secret = mssparkutils.credentials.getSecretWithLS("MyKeyVaultLS", "my-secret-name")
# or
secret = TokenLibrary.getSecret("MyKeyVaultLinkedService", "my-secret-name")

# ✅ AFTER — Fabric: reference Key Vault URL directly (no linked service)
secret = notebookutils.credentials.getSecret(
    "https://mykeyvault.vault.azure.net/",
    "my-secret-name"
)

Key change: In Fabric, getSecret() takes the full Key Vault URL as the first parameter, not a linked service name. The Key Vault must have an access policy granting your Fabric workspace identity Get permission on secrets.

`spark.read.synapsesql()` — Synapse SQL Connector

Search pattern: synapsesql

This Synapse-specific connector reads from Dedicated SQL Pool. It has no Fabric equivalent.

# ❌ BEFORE — Synapse: read from Dedicated SQL Pool
df = spark.read.synapsesql("mypool.dbo.FactSales")

# ✅ AFTER (Option A) — Fabric: read from migrated Lakehouse Delta table
df = spark.read.format("delta").load("Tables/FactSales")

# ✅ AFTER (Option B) — Fabric: read from Fabric Warehouse via JDBC
token = notebookutils.credentials.getToken("https://database.windows.net/")
jdbc_url = "jdbc:sqlserver://mywarehouse-endpoint.datawarehouse.fabric.microsoft.com:1433;database=mywarehouse"

df = (spark.read
    .format("jdbc")
    .option("url", jdbc_url)
    .option("accessToken", token)
    .option("dbtable", "dbo.FactSales")
    .load())

Decision guide:

Data migrated to Lakehouse (most common): Use Option A — direct Delta read, fastest
Data in Fabric Warehouse: Use Option B — JDBC with Entra ID token

Connector Refactoring Checklist

Search Pattern	Connector	What Changes
`spark.synapse.linkedService.*DataExplorer`	Kusto/ADX	Replace linked service with `accessToken` via `getToken()`
`spark.synapse.linkedService.*Cosmos`	Cosmos DB	Replace linked service with `accountEndpoint` + `accountKey` from Key Vault
`cosmos.oltp` + `getSecretWithLS`	Cosmos DB	Replace `getSecretWithLS()` with `getSecret(vaultUrl, name)`
`LinkedServiceBasedTokenProvider`	ADLS Gen2 OAuth	Replace with `ClientCredsTokenProvider` + SP creds from Key Vault
`spark.storage.synapse.linkedServiceName`	ADLS Gen2	Remove entirely — not supported in Fabric
`TokenLibrary.getPropertiesAsMap`	Any linked service	Remove; hardcode or parameterize values
`TokenLibrary.getSecret`	Key Vault	Replace with `notebookutils.credentials.getSecret(vaultUrl, name)`
`getSecretWithLS`	Key Vault	Replace with `getSecret(vaultUrl, name)` — use full vault URL
`synapsesql`	Dedicated SQL Pool	Replace with Delta read or JDBC with `accessToken`

DMTS note: DMTS Connections (Data Management Trusted Service) are supported in Fabric notebooks only — not yet in Spark Job Definitions. If your SJD code uses DMTS, refactor to direct endpoint authentication.

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

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Microsoft

Synapse Analytics to Microsoft Fabric Migration

Core Workflow

Scope Routing

Load References On Demand

Must

Prefer

Avoid

Examples

Files

resources/connector-refactoring.md

Connector-Specific Refactoring — Kusto, Cosmos DB, Token Library, ADLS OAuth

Azure Data Explorer (Kusto) Connector

Reading from Kusto

Writing to Kusto

Cosmos DB Connector (OLTP)

Reading from Cosmos DB

Writing to Cosmos DB

Cosmos DB Connector — Spark Config Style

ADLS Gen2 OAuth — LinkedServiceBasedTokenProvider → ClientCredsTokenProvider

Python

Scala

Token Library (Synapse-only)

Token Acquisition

Linked Service Property Extraction

Secret Retrieval via Linked Service

spark.read.synapsesql() — Synapse SQL Connector

Connector Refactoring Checklist

Requirements and compatibility

Security

Attribution and licence

Related skills

Implement Spec

MCP Builder

Schema

Postgresql Table Design

SQL Optimization Patterns

API Scaffolding Fastapi Pro

Download ZIP

`spark.read.synapsesql()` — Synapse SQL Connector