Synapse to Fabric migration: what moves and what breaks

A Synapse to Fabric migration is 3 migrations that share a workspace: dedicated SQL pools become a Fabric Data Warehouse, Spark pools, notebooks and lake databases become Fabric environments, notebooks and a lakehouse, and Synapse pipelines become Fabric Data Factory pipelines. Each has its own tool, and each tool leaves part of the job to you. Microsoft's own guide calls the Spark part "a copy-and-adapt process rather than a direct in-place move".

Your data does not have to move first. Files in ADLS Gen2 can stay where they are behind OneLake shortcuts, which is why the order of work below starts with code, not copying.

What goes where

A Synapse workspace usually has all of these, wired together. Move them in the order they depend on each other, and run the old and new side by side until the numbers match.

Part 1: dedicated SQL pools to a Fabric warehouse

The Fabric Migration Assistant takes a DACPAC file or a live connection to the pool. It converts and creates tables, views, functions, stored procedures and security objects: roles, GRANT, REVOKE, DENY and dynamic data masking. Scripts it cannot convert go into a Fix problems list, sorted so the objects others depend on come first, and Copilot can propose a fix for each one. It does not copy data; a copy job in Fabric Data Factory does.

What breaks is mostly data types. A Fabric warehouse stores its tables as Delta Parquet and supports fewer types; there is no Unicode string type in Parquet, for one. Microsoft's mapping:

datetimeoffset is the one to plan for: the offset has to go into a column of its own before the copy, or it is lost. The assistant converts the schema for the others.

Then 4 things that are not types:

• SQL logins do not exist in Fabric. Every user becomes a Microsoft Entra user.
• Column-level encryption, external tables and multi-statement table-valued functions are not supported. Move encryption into the application or use dynamic data masking.
• Indexes are not migrated. Fabric manages those optimisations itself.
• IDENTITY columns exist but behave differently from SQL Server's; test any code that relies on the values being dense or in order.

For the data, Microsoft's fastest route on large fact tables is to extract with CETAS to Parquet in ADLS Gen2, then load with COPY INTO or a Data Factory copy. Parquet loads 2.5 times faster than text, because Fabric skips the conversion. For small dimension tables, the Data Factory copy assistant does schema and data in one go.

Part 2: Spark to Fabric notebooks and a lakehouse

In a Fabric workspace, Migrate opens a guided workflow (public preview) that copies Spark pools, notebooks, Spark job definitions and lake databases from a Synapse workspace you pick. Lake databases become schemas in a lakehouse, the default database becoming dbo, and managed Delta tables appear as shortcuts to their files. It writes a migration report for every run.

Read its limits before you rely on it:

• A Synapse workspace inside a virtual network cannot be migrated with it.
• Spark settings, custom libraries and executor settings are not moved. Recreate them in a Fabric environment.
• Non-Delta tables are not supported. Parquet or CSV tables in a lake database need their own plan.
• It copies items, never data, and without a gateway connection it skips the databases.

The copied notebooks still carry Synapse code. Microsoft's guide lists the patterns to search for before you run anything. Paste a cell from your own notebook, or a table from your SQL pool, into this checker:

Try itWhat Fabric needs changed in your Synapse code

Spark notebookSQL pool table

Code to checkfrom notebookutils import mssparkutils key = mssparkutils.credentials.getSecretWithLS("kv_sales", "api-key") orders = spark.read.synapsesql("dwpool.sales.orders") raw = spark.read.parquet("abfss://raw@salesdata.dfs.core.windows.net/user/trusted-service-user/events") print(spark.catalog.currentDatabase()) spark.catalog.registerFunction("clean_sku", clean_sku) orders.write.format("delta").saveAsTable("silver.orders")

1. 1from notebookutils import mssparkutils

   mssparkutilsnotebookutils (most calls are the same)

2. 2key = mssparkutils.credentials.getSecretWithLS("kv_sales", "api-key")

   Secret through a linked servicenotebookutils.credentials.getSecret(vaultUrl, secretName)

   mssparkutilsnotebookutils (most calls are the same)

3. 3orders = spark.read.synapsesql("dwpool.sales.orders")

   Synapse SQL connectorRead the table as Delta from OneLake: spark.read.format("delta").load(...)

4. 4raw = spark.read.parquet("abfss://raw@salesdata.dfs.core.windows.net/user/trusted-service-user/events")

   Synapse-managed pathA OneLake path or a shortcut path

   ADLS Gen2 pathCan stay; a OneLake shortcut to it avoids copying the data

5. 5print(spark.catalog.currentDatabase())

   Catalog APIspark.sql("SELECT CURRENT_DATABASE()")

6. 6spark.catalog.registerFunction("clean_sku", clean_sku)

   Catalog APIspark.udf.register()

The changes that take the most time are the linked services. In Synapse a notebook reads a secret or opens a connection by a linked service's name; Fabric has no linked services in notebooks. Each one becomes a Key Vault secret read with notebookutils.credentials.getSecret, or a token from getToken, which are the only credential calls Fabric's notebooks support. Most other mssparkutils calls carry over by renaming the module to notebookutils.

The runtime matters too. Fabric does not run Spark 2.4, 3.1 or 3.2, and its default is Runtime 2.0, so a pool on an old Synapse runtime is a Spark upgrade as well as a move. V-order and optimized write are on by default in Fabric (optimized write is off by default in Synapse), so check file sizes and write times after the move. Some things have no Fabric version at all:

• .NET for Spark (C# and F#): rewrite in Python or Scala.
• GPU-accelerated pools: none in Fabric.
• An external Hive Metastore in Azure SQL Database: Fabric has only the lakehouse's own metastore. Microsoft gives export and import notebooks that copy databases, tables and partitions, not functions, and warns they do not scale well to a large catalog.
• Git: Synapse saves notebooks as JSON, Fabric as .py, .scala or .ipynb, so a Fabric workspace cannot sit on the Synapse branch.

Sizing: from nodes to capacity

A Synapse Spark pool is a hard limit in nodes. In Fabric, a pool is only a template, and the limit is the capacity: 2 Spark vCores per capacity unit, with bursting up to 3 times. An F64 gives 128 Spark vCores, which is 32 Small (4 vCore) nodes running at once.

Microsoft's own example: jobs of 7 Small nodes each (1 driver and 6 workers). A 24-node Synapse pool runs 3 at once. An F16 also runs 3, using 84 of its 96 burst vCores, and an F32 runs 6. Size from how many jobs you run at the same time, not from the old pool's node count, and remember that other Fabric work in the same capacity draws on it too. Our Spark sizing calculator helps size the jobs themselves.

Part 3: pipelines to Fabric Data Factory

Fabric Data Factory runs the same kind of pipelines, but several building blocks change shape. From Microsoft's upgrade guide, which covers ADF and Synapse pipelines alike:

The schedules surprise teams most: a Synapse trigger that starts 20 pipelines becomes 20 schedules, or 1 orchestrating pipeline that invokes the others. Pipelines that run Synapse notebooks need to point at the new Fabric notebooks once those exist, which is one more reason to move Spark before pipelines.

Microsoft also publishes AI-assisted Synapse to Fabric migration skills (preview) in its open-source Skills for Fabric. They are instructions a coding agent such as Claude Code, GitHub Copilot CLI or Cursor reads, and they cover Spark pools, lake databases, notebooks, Spark job definitions and pipelines through Fabric's REST APIs, with a read-only assessment step first. Run the assessment before you let an agent change anything.

The order that works

1. Inventory. List pools, notebooks, job definitions, lake databases, linked services and pipelines, and run the code search above across every notebook. Notebooks with no matches move as they are.
2. Shortcuts to the data. Point a lakehouse at your ADLS Gen2 folders. Delta tables under the Tables area register on their own.
3. The warehouse. Schema with the Migration Assistant, fix the list, then CETAS and COPY INTO for the data.
4. Spark. Run the migration workflow, recreate environments, refactor the patterns, test on Fabric's runtime.
5. Pipelines last. They call everything above, so they can only be tested when it exists.
6. Run in parallel and compare row counts and report totals before you switch users over.

Where Fabric fits against Databricks on Azure, if that question is still open, is in Microsoft Fabric vs Databricks. The LakehouseLakehouseOne store for all of an organisation's data: cheap files in cloud storage, as in a data lake, with the tables, transactions and fast queries of a data warehouse on top. and Medallion ArchitectureMedallion ArchitectureOrganising a lakehouse in 3 layers of rising quality: bronze for raw data, silver for cleaned and joined data, and gold for tables shaped for reports and AI. concepts explain the layout Fabric expects your tables to settle into, and Data WarehouseData WarehouseA database built for analysis: cleaned, structured data from many systems, kept in one place and shaped for fast reports and dashboards. covers what the warehouse side is for.