SQL Server Warehouse → Databricks
A common starting point: a team has years of T-SQL stored procedures, views, and ETL scripts running a SQL Server data warehouse, and is moving the workload onto Databricks. The scripts were written and tuned for T-SQL semantics, so a line-by-line rewrite risks subtle behavioral drift: date arithmetic, NULL ordering, and cursor-based logic don't map 1:1 onto PySpark.
What the CLI handles automatically
Discovery classifies each file as T-SQL (tsql dialect) and fingerprints the source platform from syntax markers. Known dialect gotchas, like DATEDIFF argument order and NULL ordering differences between T-SQL and Spark, are flagged and addressed during conversion and validation, not left for the developer to notice later.
What still needs a human
Cursors, dynamic SQL, transactions, and MERGE/upsert logic have no safe automatic transform. These land in the auto-fix phase's requires_manual bucket with prescriptive guidance (e.g. rewrite a cursor as a window function) rather than being silently guessed at.
A typical first pass: analyze one representative procedure to see its complexity and detected dialect before committing to a full-folder conversion.
3xcode workspace init ./warehouse-migration --name "sqlserver-to-databricks" # Dry run: discovery + planning only, no conversion yet 3xcode pyspark analyze legacy/usp_calculate_revenue.sql # Once the plan looks right, convert the full procedure 3xcode pyspark convert legacy/usp_calculate_revenue.sql --verbose
Oracle Stored Procedures → Spark ETL
Oracle PL/SQL packages tend to lean heavily on cursors, package-level state, and dynamic SQL: patterns that don't exist in PySpark and can't be mechanically translated. The goal in this scenario isn't a literal port; it's turning a procedural PL/SQL package into an idiomatic Spark ETL pipeline with the same business logic.
Discovery + Planning
Each object is classified against the plsql dialect, and the planning phase topologically sorts dependencies: views and standalone functions convert first, so procedures and triggers that reference them see real, already-converted PySpark signatures instead of guessed ones.
Conversion output
Related objects are grouped into production-style modules: pure utility functions in one file, the main procedure plus its exclusive helpers in another, and independently schedulable jobs kept standalone, rather than one flat script per stored procedure.
Cursor-driven row-by-row loops are exactly the kind of construct the pipeline calls out explicitly. It's worth checking the audit report before assuming a package is fully converted.
3xcode pyspark convert billing_package.sql --model sonnet # Review what needs manual attention (cursors, dynamic SQL, MERGE logic) cat output/billing_package_audit.md
Bulk Conversion During a Platform Migration
When a broader cloud data platform migration is underway, the SQL estate to convert is rarely one file. It's a directory of hundreds of scripts accumulated across years, mixed dialects, and mixed complexity. Converting these one at a time isn't practical, and a long-running batch job needs to survive interruptions.
Parallel, scheduled conversion
A directory of .sql files converts with a configurable worker count and a scheduling strategy: simple-first surfaces quick wins early, complex-first tackles the hardest files while workers are freshest.
Resumable sessions
Bulk runs are tracked as named sessions. If a run is interrupted (network blip, machine restart, deliberate pause), it resumes from where it left off instead of reprocessing already-completed files.
# Convert every .sql file in the directory, 4 workers, named session 3xcode pyspark convert --dir ./sql/ --session "batch-1" -w 4 --schedule complex-first # List sessions to find the exact resumable session ID (not just the --session name) 3xcode session list # Check progress on a long-running batch from another terminal 3xcode session status <session-id> --watch # If the run was interrupted, pick up exactly where it stopped 3xcode pyspark convert --resume <session-id>
Hive-to-Spark Modernization
Teams already running Hive on Spark, or Spark SQL / Databricks SQL scripts, are in a different situation than a cross-dialect migration: the underlying engine is the same, so conversion is about idiom and maintainability, not correctness. The goal is usually to move SQL-string pipelines into native, testable PySpark code that's easier to unit-test, version, and integrate into a broader orchestration layer.
spark_sql dialect
Discovery recognizes Hive, HiveQL, and Databricks SQL syntax under a single spark_sql dialect. Because the target and source share an engine, the conversion agent focuses on readable, well-structured PySpark rather than translating semantics.
API modernization
Deprecated Spark APIs still turn up in older Hive-era scripts (.unionAll() and .registerTempTable() are common examples) and get flagged and updated to their current equivalents (.union(), .createOrReplaceTempView()) as part of validation.
3xcode pyspark convert --dir hive_reporting_jobs/ --session "hive-modernization"
Migration Teams & BYOK
Larger migrations are rarely a solo effort. A data engineering team working through a shared backlog of SQL files benefits from shared visibility into progress and licensing, and some teams, particularly those with existing enterprise agreements with a model provider, prefer to route conversion traffic through their own account rather than a platform-provided key.
Shared organization
An org groups teammates under a shareable join code and, where an admin has provisioned one, a shared license pool, so individual engineers don't each need to track their own conversion quota during a crunch.
Bring your own provider key
Teams on AWS Bedrock, Google Vertex AI, or Azure AI Foundry can store credentials locally and route conversion calls directly to their own account. Either way, source SQL is never sent to the 3XDE backend, only directly to the configured LLM provider.
3xcode org create --name "Data Platform Team" 3xcode org join TEAM-4F9X # Route conversions through the team's own Bedrock account 3xcode keys store --provider bedrock 3xcode keys test --provider bedrock
Choosing Your Approach
Most migrations combine a few of these patterns: start with a single-file 3xcode pyspark analyze to sanity-check a representative script, then move to a bulk, resumable 3xcode pyspark convert --dir run once the approach is validated.
| Scenario | Typical source dialect | Starting point |
|---|---|---|
| SQL Server warehouse modernization | tsql | 3xcode pyspark analyze <file>.sql |
| Oracle package modernization | plsql | 3xcode pyspark convert <file>.sql |
| Large mixed-dialect estate | varies per file | 3xcode pyspark convert --dir ./sql/ -w 4 |
| Hive / Databricks SQL cleanup | spark_sql | 3xcode pyspark convert --dir ./sql/ |
| PostgreSQL / MySQL scripts | plpgsql / mysql | 3xcode pyspark convert <file>.sql |