Module OPR-006
Version 1.0 · May 2026
cloud-ondemand.com
Operator Module · Tier 2
Snowflake CLI Migration From SnowSQL to the Modern CLI Without Breaking Production
A structured migration path from legacy SnowSQL to the modern Snowflake CLI — without breaking pipelines, CI workflows, or scheduled jobs. Parallel-running patterns, command mapping, and the validation discipline that keeps production stable through the transition.
Learning objectives
01
Understand why Snowflake invested in a new CLI and what the legacy SnowSQL gaps are.
02
Inventory the SnowSQL touch points across your environment — pipelines, scripts, CI workflows, scheduled jobs.
03
Apply the five-step migration pattern using parallel running rather than big-bang cutover.
04
Diagnose the six common migration failure patterns and their fixes.
05
Map command-by-command from SnowSQL syntax to the new Snowflake CLI equivalents.
06
Validate migration completeness and decommission SnowSQL safely.
Level
Operator Migration
Duration
75 minutes plus lab
Prerequisites
OPR-005 SnowSQL 101 or equivalent
Why this matters
Most Snowflake-using organizations still run pipelines on SnowSQL. Snowflake stopped active investment in SnowSQL in 2024 and now ships new capabilities through the modern Snowflake CLI. Customers who delay migration accumulate technical debt; customers who migrate without discipline break production. This module is for the second group avoiding the second outcome.
00
Module Contents
What this module covers
This module is the migration playbook from legacy SnowSQL to the modern Snowflake CLI. By the end you will have a complete migration plan for your environment — inventory of touch points, mapped commands, parallel-running validation strategy, and a safe SnowSQL decommission procedure.
01
Why migrate from SnowSQL
What Snowflake CLI does that SnowSQL doesn't, and where the technical debt accumulates if you delay.
p.03
02
Inventorying your SnowSQL footprint
Where SnowSQL hides — pipelines, scripts, CI workflows, scheduled jobs, ad-hoc tools, developer laptops.
p.04
03
The five-step migration pattern
Inventory, install, parallel-run, cutover, decommission. The repeatable workflow that keeps production safe.
p.05
04
Diagnosing migration failures
Six failure patterns specific to CLI migration — command mismatches, config drift, behavioral differences, and others.
p.06
05
Command-by-command mapping
Reference table mapping SnowSQL commands and flags to their Snowflake CLI equivalents.
p.07
06
Validation and decommission
How to prove the migration is complete and remove SnowSQL safely without leaving orphan dependencies.
p.08
07
Hands-on lab worksheet
Migrate three real SnowSQL workflows in your environment using the parallel-running pattern.
p.09
08
Knowledge check
Five questions covering migration patterns, command mapping, diagnostics, and validation.
p.10
09
Glossary and reference
Terminology, command cheat sheet, and a migration completion checklist.
p.11
10
Module completion and next steps
Module summary, certificate, and the next module in the series.
p.12
01
Chapter 01
Why migrate from SnowSQL
SnowSQL was Snowflake's first command-line client. It shipped early in Snowflake's history, served well for years, and is still in production at most customer organizations today. But Snowflake stopped active feature investment in SnowSQL after 2024 and now ships new capabilities through the modern Snowflake CLI. The legacy tool isn't deprecated — yet — but the gap between what each can do widens every release.
Three gaps that compound
Gap 01 — Cortex AI integration. The modern Snowflake CLI integrates natively with Cortex Code, Cortex Analyst deployment, and SnowWork agents. SnowSQL has no Cortex integration. Pipelines that need to invoke or manage AI features must use the new CLI; SnowSQL cannot do this work.
Gap 02 — Streamlit deployment. The modern CLI ships, updates, and manages Streamlit apps inside Snowflake. SnowSQL cannot deploy Streamlit apps. Teams that want to ship Streamlit-based internal tools must use the new CLI for deployment automation.
Gap 03 — Native object lifecycle management. The modern CLI has native commands for managing stages, file formats, pipes, tasks, and Snowflake-native applications. SnowSQL handles these through raw SQL execution. The new CLI's native commands produce better error messages, support dry-run validation, and integrate cleanly with version-controlled definitions.
The compounding cost of delay
Cost of staying on SnowSQL
Each new Snowflake feature you adopt requires the new CLI. Teams accumulate hybrid environments where some pipelines use SnowSQL and some use the new CLI — increasing complexity rather than reducing it. The eventual migration becomes harder, not easier, as new features get layered on the legacy tool.
Benefit of migrating now
One CLI across all pipelines. Native Cortex, Streamlit, and object management. Better error messages, dry-run validation, and improved CI/CD ergonomics. Forward compatibility with everything Snowflake ships next.
The strategic timing
Snowflake hasn't announced a SnowSQL end-of-life date yet, but the trajectory is clear. Migrate while it's elective and you control the timeline. Wait until it's forced and you migrate under pressure — usually with a deadline that doesn't accommodate proper parallel-running validation. Choose elective.
02
Chapter 02
Inventorying your SnowSQL footprint
SnowSQL hides everywhere. Before migration begins, you need a complete inventory of where it lives, what it does, and who owns each touch point. Skip this step and you'll discover production SnowSQL dependencies six months after you thought migration was complete.
The six places to check
Source 01 — CI/CD pipelines. Search your repositories for "snowsql" command invocations. Common locations: .github/workflows, .gitlab-ci.yml, Jenkinsfiles, Bamboo specs, CircleCI configs. Each match is a pipeline step that needs migration.
Source 02 — Scheduled jobs and cron. Check Airflow DAGs, Prefect flows, Dagster pipelines, and traditional cron tabs. SnowSQL invocations in scheduled work are the highest-risk migration targets — they fail at 3am, not during business hours.
Source 03 — Engineer workstations. Individual developers often have SnowSQL aliases, .snowsql/config files, and shell scripts on their laptops. These don't appear in your inventory unless you specifically poll the team.
Source 04 — Docker images. Search Dockerfiles in your repositories for "snowsql" installation commands. Container images embedded in build pipelines often have SnowSQL baked in.
Source 05 — Documentation and runbooks. Internal wikis, README files, and incident runbooks often reference SnowSQL commands. Migration leaves these stale unless you update them as part of the project.
Source 06 — Third-party tools. Some ETL tools, monitoring agents, and observability platforms embed SnowSQL for Snowflake connectivity. Check each tool's documentation for what client it uses internally.
Build a shared spreadsheet with one row per SnowSQL touch point. Columns: location, owner, criticality, migration status, validation date. The spreadsheet becomes your migration burndown. Without it you'll miss touch points and the migration will feel "complete" three times before it actually is.
03
Chapter 03
The five-step migration pattern
Step 01 — Inventory
Complete the touch-point inventory
Apply the six-source inventory pattern from Chapter 02. Produce a spreadsheet of every SnowSQL invocation. Categorize by criticality (production scheduled jobs are critical; ad-hoc developer scripts are not). The inventory drives migration priority.
Step 02 — Install
Install Snowflake CLI alongside SnowSQL
Install the modern CLI on the same systems where SnowSQL runs. The two tools coexist — installation doesn't break SnowSQL. Verify both work independently before any migration begins.
# Install Snowflake CLI without removing SnowSQL
pip install snowflake-cli-labs
# Both should respond
snowsql --version
snow --version
# Configure new CLI connection (separate from SnowSQL config)
snow connection add --connection-name dev_connection
Step 03 — Parallel-run
Run both clients side-by-side and compare
For each migration target, build the equivalent Snowflake CLI invocation alongside the existing SnowSQL one. Run both. Compare outputs. Production SnowSQL stays unchanged; the new CLI runs in shadow mode until validated.
# Existing SnowSQL invocation (untouched)
snowsql -c prod -q "SELECT COUNT(*) FROM ORDERS"
# Equivalent Snowflake CLI invocation (parallel)
snow sql -q "SELECT COUNT(*) FROM ORDERS" --connection prod
# Compare outputs - should be identical
# If different, investigate before cutover
Step 04 — Cutover
Replace SnowSQL invocations one workflow at a time
Cutover individual workflows after parallel-running validates equivalence. Never cutover multiple workflows in a single change — if something breaks you need to know which workflow caused it. Update the inventory spreadsheet to mark each touchpoint complete.
Step 05 — Decommission
Remove SnowSQL only after inventory is 100% complete
When every inventory row is marked complete, remove SnowSQL from systems. Don't rush this — keep SnowSQL installed for at least 30 days after the last cutover to handle the touchpoints inventory missed. Most migrations discover one or two surprises during this grace window.
Operator Tip
Parallel-run is the discipline that prevents migration disasters. Every customer who skipped it and went directly to cutover had at least one production incident. Every customer who parallel-ran for two weeks per critical workflow caught the differences before they became outages. The two weeks is cheap insurance.
04
Chapter 04
Diagnosing migration failures
Migration failures fall into six categories. Most produce subtle output differences rather than outright errors, which is exactly why parallel-running validation matters so much.
Symptom
Root cause and fix
Query output formatting is different between tools
Default output format differs. SnowSQL defaults to fancy table output; Snowflake CLI defaults to JSON. Specify --format explicitly to match expected downstream parsing.
Connection succeeds but uses unexpected role
Default role resolution differs. SnowSQL uses the role set in .snowsql/config; Snowflake CLI uses the connection definition's role parameter. Set role explicitly in the connection or per-command.
Variable substitution syntax differs
SnowSQL uses &variable and !set. Snowflake CLI uses ${variable} and environment variable conventions. Update variable references when migrating scripts.
Authentication works in SnowSQL but fails in new CLI
Output captures empty strings instead of expected data
Snowflake CLI buffers output differently for piped invocations. Use --output json and parse rather than relying on text formatting; or use --silent flag and explicit output file.
File upload to stage works in SnowSQL but fails in CLI
PUT command syntax differs slightly between tools. Snowflake CLI's snow stage copy is the preferred path for file operations; raw PUT statements still work but with different default behavior on auto-compression.
The validation reflex
Output format, variable syntax, and connection role resolution are the three differences that produce the most migration surprises. Build validation tests that check all three explicitly for every critical workflow. The tests pay back the first time a "completed" migration breaks because someone missed a variable substitution.
05
Chapter 05
Command-by-command mapping
The reference table below maps the SnowSQL commands you most commonly use to their Snowflake CLI equivalents. Most patterns map cleanly with syntax adjustments; a few require structural changes.
SnowSQL pattern
Snowflake CLI equivalent
Notes
snowsql -c prod -q "SELECT 1"
snow sql -q "SELECT 1" --connection prod
Direct map
snowsql -c prod -f script.sql
snow sql -f script.sql --connection prod
Direct map
snowsql -c prod -q "..." -o output_format=csv
snow sql -q "..." --format csv
Flag rename
snowsql variable: &myvar
Snowflake CLI: ${myvar}
Syntax change
snowsql !set variable_substitution=true
Default behavior; no equivalent needed
Implicit
PUT file://local.csv @MYSTAGE
snow stage copy local.csv @MYSTAGE
Native command preferred
GET @MYSTAGE/file.csv file://./
snow stage copy @MYSTAGE/file.csv ./
Symmetric pattern
snowsql .snowsql/config connection
snow connection add
Separate config namespace
Stream listening with !system
Use snow sql with --execute flag for inline
Architectural change
Variable from environment: &env_var
Snowflake CLI: $env_var (shell expansion)
Standard shell
snowsql -c prod ... --role X
snow sql -q "..." --connection prod --role X
Direct map
Deploy Streamlit (no SnowSQL support)
snow streamlit deploy
New capability
Manage Cortex resources (no SnowSQL support)
snow cortex commands
New capability
Operator Tip
Save this mapping table where your team can reference it during migration. Most engineers spend the first week of migration looking up command equivalents — having the table cached locally cuts that overhead in half. Print it. Pin it. Reference it.
06
Chapter 06
Validation and decommission
The migration isn't done when scripts are updated. It's done when you've proven the new pipelines produce identical results to the old ones, and when you've safely removed the legacy tool from production systems without breaking surprise dependencies.
Validation — three checks per workflow
Check 01 — Output identity. Run the old and new versions in parallel against the same inputs for at least one week. Outputs must match byte-for-byte. Any differences must be investigated and explained; do not paper over them.
Check 02 — Error behavior. Force the workflow to fail (bad input, missing permissions, network blip) and confirm that the new version surfaces the failure visibly. Silent failure during error conditions is the most dangerous migration regression.
Check 03 — Performance parity. The new CLI should not be meaningfully slower than SnowSQL for equivalent operations. If you observe greater than 20% performance regression, investigate before cutover. Usually the cause is connection pooling, output buffering, or unnecessary format conversion.
Decommission — the four-step removal
Inventory shows zero remaining SnowSQL touchpoints across all six sources
30-day grace period elapsed since the last touchpoint cutover (catches missed dependencies)
Notice sent to engineering organization with 14-day removal lead time
SnowSQL removed from systems, configuration files archived (not deleted) for audit
The audit artifact
# Migration completion audit query# Run after decommission to confirm no SnowSQL connections remainSELECT
client_application,
client_application_version,
COUNT(*) AS session_count,
MAX(created_on) AS last_session
FROM SNOWFLAKE.ACCOUNT_USAGE.SESSIONS
WHERE created_on >= DATEADD(day, -30, CURRENT_TIMESTAMP())
AND client_application ILIKE '%SnowSQL%'
GROUP BY 1, 2
ORDER BY last_session DESC;
# Zero rows = migration complete# Any rows = investigate; there's a touchpoint inventory missed
07
Chapter 07
Hands-on lab worksheet
Five tasks that walk you through inventory through decommission for a small subset of your environment. Estimated time: 60–75 minutes.
Task 01
Inventory three real SnowSQL touchpoints
15 min
Use the six-source pattern to identify three SnowSQL touchpoints in your environment — one CI pipeline, one scheduled job, one developer workstation. Document each: location, owner, criticality.
Task 02
Install Snowflake CLI alongside SnowSQL
10 min
Install Snowflake CLI on the same system where SnowSQL runs. Verify both tools work independently. Configure a connection for the new CLI.
Task 03
Build parallel CLI equivalent for one touchpoint
20 min
Pick the simplest touchpoint from Task 01. Build the Snowflake CLI equivalent using the command mapping table. Run both versions and compare outputs byte-for-byte.
Task 04
Trigger and resolve a migration failure
15 min
Force a difference between SnowSQL and Snowflake CLI output — change a variable syntax, swap format flags, or use relative key path. Identify the cause using Chapter 04 diagnostics.
Task 05
Run the migration audit query
10 min
Execute the audit query from Chapter 06 against your account. Count remaining SnowSQL sessions. Use the result to estimate how much migration work remains in your environment.
08
Chapter 08
Knowledge check
Question 01
Why is migrating from SnowSQL to Snowflake CLI strategically important?
A
SnowSQL has been deprecated and will stop working soon
B
Snowflake stopped active feature investment; new capabilities (Cortex, Streamlit deployment) ship only through the new CLI
C
The new CLI is significantly faster for simple queries
D
Snowflake charges extra credits for SnowSQL usage
Question 02
The recommended migration pattern is:
A
Big-bang cutover during a maintenance window
B
Inventory, install, parallel-run, cutover workflow-by-workflow, decommission with grace period
C
Replace SnowSQL with Snowflake CLI immediately on all systems
D
Wait until Snowflake announces SnowSQL end-of-life and then migrate
Question 03
SnowSQL variable syntax (&myvar) maps to which Snowflake CLI equivalent?
A
@myvar
B
${myvar} or shell variable expansion
C
%myvar%
D
No equivalent — variables are unsupported
Question 04
After cutover, the recommended grace period before decommissioning SnowSQL is:
A
Immediate removal
B
24 hours
C
30 days to catch missed dependencies
D
One full year
Question 05
How do you confirm migration is complete after decommission?
A
Ask the team if anyone still uses SnowSQL
B
Check the inventory spreadsheet shows zero rows
C
Query SNOWFLAKE.ACCOUNT_USAGE.SESSIONS for any sessions where client_application contains 'SnowSQL'
D
Check that SnowSQL is uninstalled from one developer's laptop
09
Chapter 09
Glossary and reference
Key terminology
SnowSQL
Snowflake's first command-line client. Mature, stable, but no longer receiving feature investment. Cannot deploy Streamlit apps or manage Cortex resources.
Snowflake CLI
The modern Snowflake command-line tool. Native commands for stages, Streamlit, Cortex, and Snowflake-native applications. Invoked as snow rather than snowsql.
Parallel-running
Migration discipline where the old and new tools are run side-by-side against the same inputs for a validation period before cutover. Catches subtle behavioral differences before they cause production incidents.
Cutover
The moment a specific workflow stops using the legacy tool and starts using the new one in production. Done workflow-by-workflow, never in bulk.
Touch-point inventory
The complete catalog of every place SnowSQL is invoked in your environment. The foundation of migration planning. Without it, migration completion is impossible to claim.
Decommission grace period
The 30-day window between completing all cutovers and removing SnowSQL from systems. Exists to catch touch points the inventory missed.
Migration completion checklist
Touch-point inventory complete across all six sources
Inventory spreadsheet maintained with criticality and owner per row
Snowflake CLI installed alongside SnowSQL on all systems
Parallel-running validation completed for every critical workflow
Output identity confirmed byte-for-byte for production pipelines
Error behavior validated for failure scenarios
Performance parity confirmed (no >20% regression)
Cutover completed workflow-by-workflow, never bulk
30-day grace period elapsed since last cutover
Audit query confirms zero recent SnowSQL sessions
SnowSQL removed from systems; configs archived
10
Chapter 10
Module completion
What you learned
The strategic case
Why migrate now, the three gaps SnowSQL has that compound over time, and the timing logic that makes elective migration smarter than forced migration.
Inventory discipline
The six sources where SnowSQL hides — CI/CD, scheduled jobs, workstations, Docker images, docs, third-party tools — and the spreadsheet pattern that turns inventory into a migration burndown.
Migration pattern
Inventory, install, parallel-run, cutover, decommission. The five-step workflow that keeps production stable through the transition.
Command mapping
The reference table mapping the most common SnowSQL patterns to Snowflake CLI equivalents, plus the six failure modes that produce migration surprises.
Cloud On Demand · Operator Module Completion
Snowflake CLI Migration
Awarded to the practitioner who completed module OPR-006