migrating-dbt-project-across-platforms
Migrating a dbt Project Across Data Platforms
This skill guides migration of a dbt project from one data platform (source) to another (target) — for example, Snowflake to Databricks, or Databricks to Snowflake.
The core approach: dbt Fusion compiles SQL in real-time and produces rich, detailed error logs that tell you exactly what's wrong and where. We trust Fusion entirely for dialect conversion — no need to pre-document every SQL pattern difference. The workflow is: read Fusion's errors, fix them, recompile, repeat until done. Combined with dbt unit tests (generated on the source platform before migration), we prove both compilation correctness and data correctness on the target platform.
Success criteria: Migration is complete when:
dbtf compilefinishes with 0 errors and 0 warnings on the target platform- All unit tests pass on the target platform (
dbt test --select test_type:unit) - All models run successfully on the target platform (
dbtf run)
Validation cost: Use dbtf compile as the primary iteration gate — it's free (no warehouse queries) and catches both errors and warnings from static analysis. Only dbtf run and dbt test incur warehouse cost; run those only after compile is clean.
Contents
- Additional Resources — Reference docs for installation, unit tests, profile targets
- Migration Workflow — 7-step migration process with progress checklist
- Don't Do These Things — Critical guardrails
- Known Limitations & Gotchas — Fusion-specific and cross-platform caveats
More from dbt-labs/dbt-agent-skills
using-dbt-for-analytics-engineering
Builds and modifies dbt models, writes SQL transformations using ref() and source(), creates tests, and validates results with dbt show. Use when doing any dbt work - building or modifying models, debugging errors, exploring unfamiliar data sources, writing tests, or evaluating impact of changes.
329adding-dbt-unit-test
Creates unit test YAML definitions that mock upstream model inputs and validate expected outputs. Use when adding unit tests for a dbt model or practicing test-driven development (TDD) in dbt.
308fetching-dbt-docs
Retrieves and searches dbt documentation pages in LLM-friendly markdown format. Use when fetching dbt documentation, looking up dbt features, or answering questions about dbt Cloud, dbt Core, or the dbt Semantic Layer.
301running-dbt-commands
Formats and executes dbt CLI commands, selects the correct dbt executable, and structures command parameters. Use when running models, tests, builds, compiles, or show queries via dbt CLI. Use when unsure which dbt executable to use or how to format command parameters.
290answering-natural-language-questions-with-dbt
Writes and executes SQL queries against the data warehouse using dbt's Semantic Layer or ad-hoc SQL to answer business questions. Use when a user asks about analytics, metrics, KPIs, or data (e.g., "What were total sales last quarter?", "Show me top customers by revenue"). NOT for validating, testing, or building dbt models during development.
288troubleshooting-dbt-job-errors
Diagnoses dbt Cloud/platform job failures by analyzing run logs, querying the Admin API, reviewing git history, and investigating data issues. Use when a dbt Cloud/platform job fails and you need to diagnose the root cause, especially when error messages are unclear or when intermittent failures occur. Do not use for local dbt development errors.
285