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:
1. `dbtf compile` finishes with 0 errors **and 0 warnings** on the target platform
2. All unit tests pass on the target platform (`dbt test --select test_type:unit`)
3. 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](#additional-resources) — Reference docs for installation, unit tests, profile targets
- [Migration Workflow](#migration-workflow) — 7-step migration process with progress checklist
- [Don't Do These Things](#dont-do-these-things) — Critical guardrails
- [Known Limitations & Gotchas](#known-limitations--gotchas) — Fusion-specific and cross-platform caveats

## Additional Resources

- [Installing dbt Fusion](references/installing-dbt-fusion.md) — How to install and verify dbt Fusion
- [Generating Unit Tests](references/generating-unit-tests.md) — How to generate unit tests on the source platform before migration
- [Switching Targets](references/switching-targets.md) — How to configure the dbt target for the destination platform and update sources

## Migration Workflow

### Progress Checklist

Copy this checklist to track migration progress:

```
Migration Progress:
- [ ] Step 1: Verify dbt Fusion is installed and working
- [ ] Step 2: Assess source project (dbtf compile — 0 errors on source)
- [ ] Step 3: Generate unit tests on source platform
- [ ] Step 4: Switch dbt target to destination platform
- [ ] Step 5: Run Fusion compilation and fix all errors (dbtf compile — 0 errors on target)
- [ ] Step 6: Run and validate unit tests on target platform
- [ ] Step 7: Final validation and document changes in migration_changes.md
```

### Instructions

When a user asks to migrate their dbt project to a different data platform, follow these steps. Create a `migration_changes.md` file documenting all code changes (see template below).

#### Step 1: Verify dbt Fusion is installed

Fusion is **required** — it provides the real-time compilation and rich error diagnostics that power this migration. Fusion may be available as `dbtf` or as `dbt`.