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://mp-staging.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/validation-testing.md

Post-Migration Validation & Testing

Systematic verification that all migrated items work correctly in Fabric before cutover.

Script pattern: Sections below show function signatures and key logic outlines. Generate the full runnable Python script on demand when the user needs it — this keeps the resource compact and reduces token load.

When to run: Validation is designed to run incrementally after each phase, not only at the end. Each phase resource includes an optional validation checkpoint that cross-references the relevant section below.
After Phase Run These Sections Gate
Phase 0 (Environments) V1 Do not proceed to Phase 1 until Environments publish and libraries import
Phase 1 (Lakehouses) V2 Do not proceed to Phase 2 until shortcuts are healthy and row counts match
Phase 2 (Notebooks) V3 Do not proceed to Phase 3 until critical notebooks execute successfully
Phase 3 (SJDs) V4, V5, V6 Do not cut over until SJDs pass and the full validation report is green
Auth token: Use the token-acquisition recipe in COMMON-CLI § Authentication Recipes with audience https://api.fabric.microsoft.com.

After Phase	Run These Sections	Gate
Phase 0 (Environments)	V1	Do not proceed to Phase 1 until Environments publish and libraries import
Phase 1 (Lakehouses)	V2	Do not proceed to Phase 2 until shortcuts are healthy and row counts match
Phase 2 (Notebooks)	V3	Do not proceed to Phase 3 until critical notebooks execute successfully
Phase 3 (SJDs)	V4, V5, V6	Do not cut over until SJDs pass and the full validation report is green

Validation Workflow

Validation:
├── V1: Environment validation (Phase 0 outputs)
├── V2: Data validation (Phase 1 outputs — Lakehouses, shortcuts, tables)
├── V3: Notebook execution testing (Phase 2 outputs)
├── V4: SJD execution testing (Phase 3 outputs)
├── V5: Query result comparison (Synapse vs. Fabric)
└── V6: Generate validation report

V1: Environment Validation

Verify that Fabric Environments created in Phase 0 are published and usable.

Check Environment Publish Status

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}

Check properties.publishDetails.state — must be "Success".

Validate Libraries

Run a test notebook attached to each Environment to confirm libraries are available:

# Verify critical libraries are importable
import_errors = []
# Map PyPI package names to importable module names where they differ
required_libs = {
    "pandas": "pandas",
    "scikit-learn": "sklearn",
    "httpx": "httpx",
}  # adjust to your Environment

for pkg, module in required_libs.items():
    try:
        __import__(module)
    except ImportError as e:
        import_errors.append(f"{pkg}: {e}")

if import_errors:
    print("❌ Missing libraries:")
    for err in import_errors:
        print(f"  {err}")
else:
    print("✅ All required libraries available")

Validate Spark Config

# Verify critical Spark properties carried over from Synapse pool
expected_configs = {
    "spark.sql.shuffle.partitions": "200",
    "spark.executor.memory": "8g",
    # add your expected configs
}

config_errors = []
for key, expected in expected_configs.items():
    actual = spark.conf.get(key, None)
    if actual != expected:
        config_errors.append(f"{key}: expected '{expected}', got '{actual}'")

if config_errors:
    print("❌ Spark config mismatches:")
    for err in config_errors:
        print(f"  {err}")
else:
    print("✅ All Spark configs match")

V2: Data Validation

Verify that Lakehouses, shortcuts, and tables from Phase 1 are accessible and data-complete.

Shortcut Health Check

# Check all shortcuts are accessible
import json

schemas = ["sales", "marketing", "staging"]  # adjust to your schemas

shortcut_errors = []
for schema in schemas:
    try:
        tables_files = notebookutils.fs.ls(f"Tables/{schema}/")
        files_files = notebookutils.fs.ls(f"Files/{schema}/")
        print(f"✅ {schema}: {len(tables_files)} table shortcuts, {len(files_files)} file shortcuts")
    except Exception as e:
        shortcut_errors.append(f"{schema}: {e}")

if shortcut_errors:
    print("❌ Shortcut errors:")
    for err in shortcut_errors:
        print(f"  {err}")

Row Count Comparison

Compare row counts between Synapse and Fabric for every migrated table.

Step 1 — Collect Synapse row counts (run in a Synapse notebook or via REST API):

# Run in Synapse notebook — collect row counts for all tables
synapse_counts = {}
databases = spark.sql("SHOW DATABASES").collect()

for db_row in databases:
    db = db_row.namespace
    tables = spark.sql(f"SHOW TABLES IN {db}").collect()
    for tbl_row in tables:
        table_name = f"{db}.{tbl_row.tableName}"
        count = spark.sql(f"SELECT COUNT(*) AS cnt FROM {table_name}").first().cnt
        synapse_counts[table_name] = count
        print(f"  {table_name}: {count}")

# Save for comparison
import json
with open("/tmp/synapse_counts.json", "w") as f:
    json.dump(synapse_counts, f)

Step 2 — Collect Fabric row counts and compare (run in a Fabric notebook):

# Run in Fabric notebook — compare against Synapse counts
import json

# Load Synapse counts (upload the JSON to Lakehouse Files/ or paste inline)
synapse_counts = {
    "sales.customers": 150000,
    "sales.orders": 2340000,
    "marketing.campaigns": 5200,
    # ... paste or load from file
}

# Collect Fabric counts
validation_results = []
for synapse_table, expected_count in synapse_counts.items():
    # Map Synapse database.table to Fabric schema.table
    fabric_table = synapse_table  # adjust if schema names differ
    try:
        actual_count = spark.sql(f"SELECT COUNT(*) AS cnt FROM {fabric_table}").first().cnt
        match = actual_count == expected_count
        validation_results.append({
            "table": synapse_table,
            "synapse_count": expected_count,
            "fabric_count": actual_count,
            "match": match,
            "diff": actual_count - expected_count,
        })
        status = "✅" if match else "❌"
        print(f"  {status} {fabric_table}: Synapse={expected_count}, Fabric={actual_count}, diff={actual_count - expected_count}")
    except Exception as e:
        validation_results.append({
            "table": synapse_table,
            "synapse_count": expected_count,
            "fabric_count": None,
            "match": False,
            "diff": None,
            "error": str(e),
        })
        print(f"  ❌ {fabric_table}: ERROR — {e}")

# Summary
passed = sum(1 for r in validation_results if r["match"])
failed = len(validation_results) - passed
print(f"\nRow count validation: {passed}/{len(validation_results)} passed, {failed} failed")

Schema Comparison

Verify column names, types, and order match between Synapse and Fabric:

def compare_schema(synapse_schema, fabric_table):
    """
    synapse_schema: list of (column_name, data_type) from Synapse
    fabric_table: fully qualified Fabric table name
    """
    fabric_cols = [(f.name, f.dataType.simpleString()) for f in spark.table(fabric_table).schema.fields]

    mismatches = []
    for i, (syn_col, syn_type) in enumerate(synapse_schema):
        if i >= len(fabric_cols):
            mismatches.append(f"Column '{syn_col}' missing in Fabric (position {i})")
            continue
        fab_col, fab_type = fabric_cols[i]
        if syn_col != fab_col:
            mismatches.append(f"Position {i}: name mismatch — Synapse '{syn_col}' vs Fabric '{fab_col}'")
        if syn_type != fab_type:
            mismatches.append(f"Column '{syn_col}': type mismatch — Synapse '{syn_type}' vs Fabric '{fab_type}'")

    if len(fabric_cols) > len(synapse_schema):
        extra = [f.name for f in spark.table(fabric_table).schema.fields[len(synapse_schema):]]
        mismatches.append(f"Extra columns in Fabric: {extra}")

    return mismatches

Partition Validation (Non-Delta Tables Retained as Original Format)

For tables migrated with Option B (retain original format + MSCK REPAIR TABLE):

# Compare partition counts
def validate_partitions(table_name, expected_partition_count):
    partitions = spark.sql(f"SHOW PARTITIONS {table_name}").collect()
    actual = len(partitions)
    match = actual == expected_partition_count
    status = "✅" if match else "❌"
    print(f"  {status} {table_name}: expected {expected_partition_count} partitions, got {actual}")
    return match

V3: Notebook Execution Testing

Run each migrated notebook to verify it executes without errors.

Execute Notebook via REST API

Endpoint: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

Key functions (generate full implementation on demand):

def run_notebook(notebook_id, notebook_name, timeout_minutes=30) -> tuple[str, float, str|None]:
    """Execute a notebook and wait for completion. Returns (status, duration_seconds, error).
    - Check GET .../jobs/instances for already-running jobs before submitting
    - POST to jobType=RunNotebook, extract job_id from Location header
    - Fallback: query job history if Location header missing
    - Delegate to _poll_job() for status polling
    """

def _poll_job(notebook_id, job_id, notebook_name, timeout_minutes) -> tuple[str, float, str|None]:
    """Poll GET .../jobs/instances/{job_id} every 15s until Completed, Failed, Cancelled, or timeout."""

Batch Test All Notebooks

List notebooks: GET .../items?type=Notebook
Loop and call run_notebook() for each; collect {name, id, status, duration_sec, error}
Print pass/fail summary

Common Failure Patterns

Error	Cause	Fix
`ImportError: No module named 'xxx'`	Missing library in Environment	Add to Environment → publish. See library-compatibility.md
`AnalysisException: Table or view not found`	Lakehouse not attached or table not migrated	Check lakehouse binding (Phase 2, Step 4) or re-run Phase 1
`AnalysisException: ... listDatabases`	Unsupported `spark.catalog` method	Refactor to Spark SQL. See code-patterns.md
`Py4JJavaError: ... LinkedServiceBasedTokenProvider`	Synapse token provider not replaced	Refactor to `ClientCredsTokenProvider`. See connector-refactoring.md
`getSecretWithLS ... not supported`	Linked service secret method not replaced	Replace with `getSecret(vaultUrl, name)`. See connector-refactoring.md
`spark.read.synapsesql ... not found`	Synapse SQL connector not available	Replace with Delta read or JDBC. See connector-refactoring.md
`FileNotFoundException` or `403 Forbidden` on `abfss://`	Old Synapse storage path not updated	Update to OneLake path or create shortcut. See code-patterns.md
`DefaultLakehouse: missing name`	Notebook lakehouse binding incomplete	Re-bind with both `id` and `name`

V4: SJD Execution Testing

Run each migrated Spark Job Definition to verify it completes successfully.

Execute SJD via REST API

Endpoint: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{sjdId}/jobs/instances?jobType=SparkJob

Key functions (generate full implementation on demand — same pattern as V3 run_notebook):

def run_sjd(sjd_id, sjd_name, timeout_minutes=60) -> tuple[str, float, str|None]:
    """Execute an SJD and wait for completion. Same submit+poll pattern as run_notebook but with jobType=SparkJob."""

Batch test: GET .../items?type=SparkJobDefinition, loop run_sjd() for each, print pass/fail

SJD-Specific Checks

Check	How
Main file accessible	Verify the `.py`/`.jar` reference file exists in the Lakehouse or ADLS path
Reference files accessible	Check all auxiliary files listed in the SJD definition
Lakehouse context set	SJD must have at least one lakehouse associated
Environment bound	If the Synapse SJD used a non-default pool, verify the Environment is attached

V5: Query Result Comparison

For critical tables, compare actual query results (not just row counts) between Synapse and Fabric.

Checksum Comparison

Compute a hash of key columns to detect data differences without transferring full datasets.

Key functions (generate full PySpark implementation on demand):

def table_checksum(table_name, key_columns, value_columns) -> dict:
    """Compute a deterministic checksum for a table. Returns {table, row_count, checksum}.
    - Read spark.table(), sort by key_columns
    - md5(concat_ws) each row on key+value columns
    - Aggregate: count(*) + md5(concat(sort_array(collect_list(row_hash))))
    Run in BOTH Synapse and Fabric, compare checksum values.
    """

def compare_samples(synapse_df, fabric_df, key_columns, sample_size=100):
    """For mismatched checksums: sample keys from source, join both sides, subtract to find diffs."""

V6: Generate Validation Report

Combine all validation results into a single report.

Generate the full report script on demand. It should accept these inputs and produce a markdown report:

def generate_validation_report(
    workspace_id: str,
    env_results: list,      # [{name, publish_status, lib_check, config_check}]
    data_results: list,      # [{table, synapse_count, fabric_count, match}]
    notebook_results: list,  # [{name, status, duration_sec, error}]
    sjd_results: list,       # [{name, status, duration_sec, error}]
) -> str:
    """Build a markdown validation report with sections for V1–V4 + summary table.
    - Per-category tables with pass/fail icons
    - Summary row: READY FOR CUTOVER if all passed, else ISSUES REMAIN
    - Write to validation_report.md and print
    """

Cutover Readiness Criteria

Do not decommission Synapse until all of the following are true:

Criterion	Check
All Environments published successfully	V1 — publish status = Success
All required libraries available	V1 — no ImportError in test notebooks
All table row counts match	V2 — 0 mismatches
All shortcuts accessible	V2 — no FileNotFoundException or 403 errors
All notebooks execute without errors	V3 — 100% Completed
All SJDs execute without errors	V4 — 100% Completed
Critical query results match (checksums)	V5 — checksums equal for key tables
Downstream consumers rerouted	Power BI, APIs, scheduled pipelines point to Fabric
Monitoring active	Fabric Monitoring Hub showing successful runs for 1–2 weeks

Parallel run recommended: Run migrated workloads in Fabric alongside Synapse for at least 1–2 weeks before cutover. Compare outputs daily to catch edge cases (time-dependent logic, incremental loads, schema evolution).

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-08

Also distributed in

microsoft/skills-for-fabric

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

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