migrating-dbt-project-across-platforms

Name: migrating-dbt-project-across-platforms
Author: dbt-labs

637stars55forks

How to install migrating-dbt-project-across-platforms?

dbt-labs/dbt-agent-skills/migrating-dbt-project-across-platforms

$npx -y skills add dbt-labs/dbt-agent-skills --skill migrating-dbt-project-across-platforms

Installs into the current project.

Summary

Use when migrating a dbt project from one data platform or data warehouse to another (e.g., Snowflake to Databricks, Databricks to Snowflake) using dbt Fusion's real-time compilation to identify and fix SQL dialect differences.

Files · 1

View on GitHub

SKILL.md

1	# Migrating a dbt Project Across Data Platforms
2
3	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.
4
5	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.
6
7	Success criteria: Migration is complete when:
8	1. `dbtf compile` finishes with 0 errors and 0 warnings on the target platform
9	2. All unit tests pass on the target platform (`dbt test --select test_type:unit`)
10	3. All models run successfully on the target platform (`dbtf run`)
11
12	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.
13
14	## Contents
15
16	- [Additional Resources](#additional-resources) — Reference docs for installation, unit tests, profile targets
17	- [Migration Workflow](#migration-workflow) — 7-step migration process with progress checklist
18	- [Don't Do These Things](#dont-do-these-things) — Critical guardrails
19	- [Known Limitations & Gotchas](#known-limitations--gotchas) — Fusion-specific and cross-platform caveats
20
21	## Additional Resources
22
23	- [Installing dbt Fusion](references/installing-dbt-fusion.md) — How to install and verify dbt Fusion
24	- [Generating Unit Tests](references/generating-unit-tests.md) — How to generate unit tests on the source platform before migration
25	- [Switching Targets](references/switching-targets.md) — How to configure the dbt target for the destination platform and update sources
26
27	## Migration Workflow
28
29	### Progress Checklist
30
31	Copy this checklist to track migration progress:
32
33	```
34	Migration Progress:
35	- [ ] Step 1: Verify dbt Fusion is installed and working
36	- [ ] Step 2: Assess source project (dbtf compile — 0 errors on source)
37	- [ ] Step 3: Generate unit tests on source platform
38	- [ ] Step 4: Switch dbt target to destination platform
39	- [ ] Step 5: Run Fusion compilation and fix all errors (dbtf compile — 0 errors on target)
40	- [ ] Step 6: Run and validate unit tests on target platform
41	- [ ] Step 7: Final validation and document changes in migration_changes.md
42	```
43
44	### Instructions
45
46	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).
47
48	#### Step 1: Verify dbt Fusion is installed
49
50	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`.
51
52	To detect which command to use:
53	1. Check if `dbtf` is available — if it exists, it's Fusion
54	2. If `dbtf` is not found, run `dbt --version` — if the output starts with `dbt-fusion`, then `dbt` is Fusion
55
56	Use whichever command is Fusion everywhere this skill references `dbtf`. If neither provides Fusion, guide the user through installation. See [references/installing-dbt-fusion.md](references/installing-dbt-fusion.md) for details.
57
58	#### Step 2: Assess the source project
59
60	Run `dbtf compile` on the source platform target to confirm the project compiles cleanly with 0 errors. This establishes the baseline.
61
62	```bash
63	dbtf compile
64	```
65
66	If there are errors on the source platform, those must be resolved first before starting the migration. The `migrating-dbt-core-to-fusion` skill can help resolve Fusion compatibility issues.
67
68	#### Step 3: Generate unit tests on source platform
69
70	While still connected to the source platform, generate dbt unit tests for key models to capture expected data outputs as a "golden dataset." These tests will prove data consistency after migration.
71
72	Which models to test: You must test every leaf node — models at the very end of the DAG that no other model depends on via `ref()`. Do not guess leaf nodes from naming conventions — derive them programmatically using the methods in [references/generating-unit-tests.md](references/generating-unit-tests.md#identifying-leaf-nodes). List all leaf nodes explicitly and confirm the count before writing tests. Also test any mid-DAG model with significant transformation logic (joins, calculations, ca

People who liked this also viewed

6 picks

Type

migrating-dbt-project-across-platforms

637stars55forks

View on GitHub

How to install migrating-dbt-project-across-platforms?

dbt-labs/dbt-agent-skills/migrating-dbt-project-across-platforms

$npx -y skills add dbt-labs/dbt-agent-skills --skill migrating-dbt-project-across-platforms

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Migrating a dbt Project Across Data Platforms
2
3	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.
4
5	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.
6
7	Success criteria: Migration is complete when:
8	1. `dbtf compile` finishes with 0 errors and 0 warnings on the target platform
9	2. All unit tests pass on the target platform (`dbt test --select test_type:unit`)
10	3. All models run successfully on the target platform (`dbtf run`)
11
12	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.
13
14	## Contents
15
16	- [Additional Resources](#additional-resources) — Reference docs for installation, unit tests, profile targets
17	- [Migration Workflow](#migration-workflow) — 7-step migration process with progress checklist
18	- [Don't Do These Things](#dont-do-these-things) — Critical guardrails
19	- [Known Limitations & Gotchas](#known-limitations--gotchas) — Fusion-specific and cross-platform caveats
20
21	## Additional Resources
22
23	- [Installing dbt Fusion](references/installing-dbt-fusion.md) — How to install and verify dbt Fusion
24	- [Generating Unit Tests](references/generating-unit-tests.md) — How to generate unit tests on the source platform before migration
25	- [Switching Targets](references/switching-targets.md) — How to configure the dbt target for the destination platform and update sources
26
27	## Migration Workflow
28
29	### Progress Checklist
30
31	Copy this checklist to track migration progress:
32
33	```
34	Migration Progress:
35	- [ ] Step 1: Verify dbt Fusion is installed and working
36	- [ ] Step 2: Assess source project (dbtf compile — 0 errors on source)
37	- [ ] Step 3: Generate unit tests on source platform
38	- [ ] Step 4: Switch dbt target to destination platform
39	- [ ] Step 5: Run Fusion compilation and fix all errors (dbtf compile — 0 errors on target)
40	- [ ] Step 6: Run and validate unit tests on target platform
41	- [ ] Step 7: Final validation and document changes in migration_changes.md
42	```
43
44	### Instructions
45
46	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).
47
48	#### Step 1: Verify dbt Fusion is installed
49
50	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`.
51
52	To detect which command to use:
53	1. Check if `dbtf` is available — if it exists, it's Fusion
54	2. If `dbtf` is not found, run `dbt --version` — if the output starts with `dbt-fusion`, then `dbt` is Fusion
55
56	Use whichever command is Fusion everywhere this skill references `dbtf`. If neither provides Fusion, guide the user through installation. See [references/installing-dbt-fusion.md](references/installing-dbt-fusion.md) for details.
57
58	#### Step 2: Assess the source project
59
60	Run `dbtf compile` on the source platform target to confirm the project compiles cleanly with 0 errors. This establishes the baseline.
61
62	```bash
63	dbtf compile
64	```
65
66	If there are errors on the source platform, those must be resolved first before starting the migration. The `migrating-dbt-core-to-fusion` skill can help resolve Fusion compatibility issues.
67
68	#### Step 3: Generate unit tests on source platform
69
70	While still connected to the source platform, generate dbt unit tests for key models to capture expected data outputs as a "golden dataset." These tests will prove data consistency after migration.
71
72	Which models to test: You must test every leaf node — models at the very end of the DAG that no other model depends on via `ref()`. Do not guess leaf nodes from naming conventions — derive them programmatically using the methods in [references/generating-unit-tests.md](references/generating-unit-tests.md#identifying-leaf-nodes). List all leaf nodes explicitly and confirm the count before writing tests. Also test any mid-DAG model with significant transformation logic (joins, calculations, ca

People who liked this also viewed

6 picks

Type