Snowflake Migration Agent¶

The Snowflake Migration Agent is an AI assistant for Cortex Code that guides you through an end-to-end database migration to Snowflake. It provides a conversational, interactive workflow — from connecting to your source database through code conversion, deployment, data migration, and validation.

Migrations take time. A full migration — especially for large workloads with hundreds of objects — is not completed in a single session. The Snowflake Migration Agent automatically tracks your progress at every step. Each time you start a session, it reads your project state and picks up exactly where you left off. There is no need to start over.

Why use the Snowflake Migration Agent¶

Cortex Code on its own is a capable coding agent, but a database migration involves coordination across dozens of tools, stages, and hundreds of objects over days or weeks. The Snowflake Migration Agent adds the structure, automation, and domain expertise that a general-purpose agent doesn’t have.

What the Snowflake Migration Agent gives you¶

Snowflake Migration Agent vs. plain Cortex Code¶

How to use the Snowflake Migration Agent¶

Launch Cortex Code¶

Create a directory for your migration project. From the project directory, start Cortex Code CLI

cortex

Start a migration¶

From within Cortex Code CLI, there are a couple common ways to start a migration

1. Start a new migration (greenfield)
   You have a source database and want to migrate it to Snowflake from scratch. The Snowflake Migration Agent walks you through every stage: connect to the source, extract objects, convert code, assess the workload, deploy, migrate data, and validate.

start a database migration

2. Resume an in-progress migration
   You already started a migration in a previous session — maybe days or weeks ago. The Snowflake Migration Agent reads your project state and picks up at the exact point where you stopped. No re-extraction, no re-conversion.

continue my migration

Import an existing migration¶

Once you start or continue a migration, if you already have .sql files from a previous SnowConvert run or another source, they can be imported into a project to be picked up at the conversion or deployment stage.

import SQL files from ./my-exported-scripts/

What you can do¶

Snowflake Migration Agent guides you through the full migration lifecycle and lets you jump directly to any stage at any time. You can pause and resume across sessions, and multiple users can collaborate on the same project — it tracks which code units each person is working on so effort isn’t duplicated.

Supported source systems¶

Not all capabilities are available for all source systems. The following table shows what is supported today and what is coming soon.

Other dialects with deterministic conversion support: Azure Synapse, Sybase IQ, Google BigQuery, Greenplum, Netezza, PostgreSQL, Spark SQL, Databricks SQL, Vertica, Hive, IBM DB2

Available extraction scripts: Teradata, SQL Server, Synapse, Oracle, Redshift, Netezza, Vertica, DB2, Hive, BigQuery, Databricks, Sybase IQ

Prerequisites¶

Before starting a migration, ensure you have:

• Python installed
• Git installed
• Cortex Code CLI installed (the Snowflake Migration Agent is bundled).
• A Snowflake account with a connection configured in ~/.snowflake/connections.toml.
• A source database (SQL Server or Redshift) accessible from your machine.

All other dependencies (uv, scai, Python packages) are installed automatically when the Snowflake Migration Agent runs for the first time.

Migration workflow¶

The Snowflake Migration Agent guides you through six stages. Each session starts by detecting your current progress and resuming automatically.

Stage 6 is where the bulk of the work happens. AI-driven testing, conversion remediation, and iterative fix loops run here — often across multiple sessions and days. This is also the stage where collaboration pays off most: multiple users can work on the same project simultaneously, each picking up different code units while the Snowflake Migration Agent coordinates to prevent duplicated effort.

Every session shows a live progress checklist so you always know where you stand:

✅  1. Connect             — Connected to SQL Server
✅  2. Init                — Project initialized
✅  3. Register            — 342 objects registered
◐   4. Initial Conv        — 280/342 converted
⬚   5. Assess              — Not run
⬚   6. Migrate Objects     — 0/120 tables deployed

Snowflake Migration Agent Reference¶

The Snowflake Migration Agent is organized as a skill tree. The root skill detects your project state and delegates to the right sub-skill. You can also invoke any sub-skill directly by describing what you want.

Setup sub-skills (Stages 1–5)¶

connection¶

Walks you through connecting to your source database. Collects credentials, tests the connection, and saves it for reuse across sessions. Supports:

• SQL Server — configures ODBC driver, host, port, and authentication.
• Amazon Redshift — configures host, port, database, and IAM or password authentication.

register-code-units¶

Gets source code into the migration project. Two paths are available:

convert¶

Runs SnowConvert to translate your source SQL (T-SQL or Redshift SQL) into Snowflake-compatible SQL. After conversion, the agent presents:

• Total objects converted successfully.
• EWI (Early Warning Issue) summary broken down by severity (errors, warnings, informational).
• A list of objects that require manual review.

assessment¶

Generates an interactive multi-tab HTML report. The assessment includes four analyses that can be run individually or together:

The report is generated as a single self-contained HTML file. You can iterate on the wave plan interactively — for example, reprioritizing objects, adjusting wave sizes, or relocating specific objects — before locking it for deployment.

Migration sub-skills (Stage 6)¶

migrate-objects¶

The main deploy loop. Processes all objects in the current wave in dependency order:

After each wave completes, the agent automatically advances to the next wave.

baseline-capture¶

Captures the expected output of source stored procedures and functions for use as test baselines. Two approaches are supported:

Baselines are stored locally and uploaded to Snowflake so they can be used for two-sided validation (source output vs. Snowflake output) during the migrate-objects loop.

rule-engine¶

Manages reusable migration rules stored in Snowflake. Rules encode known source-to-Snowflake fix patterns and are shared across all objects in the project. Each rule can operate in two modes:

The rule engine has four sub-capabilities:

Rules accumulate over the lifetime of the project. Every time the agent fixes an object and extracts a rule, that rule becomes available to all subsequent objects — reducing manual effort as the migration progresses.

What You Can Ask¶

You do not need to follow the prescribed path. You can ask for any capability at any time.

Status and navigation¶

Setup¶

"Connect to my SQL Server database"
"Extract objects from the source"
"Import SQL files from ./my-scripts/"
"Convert my source code"

Assessment¶

"Run a full assessment"
"Generate deployment waves"
"I want a maximum of 30 objects per wave"
"Prioritize all Payroll objects in Wave 1"
"Identify temporary and staging objects"
"Analyze dynamic SQL patterns"
"Assess my SSIS packages"

Migration¶

"Deploy tables"
"Migrate data"
"Deploy and test the next function"
"Capture baselines for dbo.GetCustomerOrders"

Rule engine¶

"Search rules for this file"
"Apply all matched rules"
"Extract a rule from my last fix"
"Propagate this rule across the project"
"Show me all rules"

Example Workload¶

You can use AdventureWorksDW (https://learn.microsoft.com/en-us/sql/samples/adventureworks-install-configure) as an example source database to try the Snowflake Migration Agent end-to-end. Substitute any SQL Server or Redshift database you have access to — the Snowflake Migration Agent adapts to whatever source you connect.

Troubleshooting¶

Support¶

For help with the migration skill, contact: snowconvert-support@snowflake.com