/upgrading-dbt-core

name: upgrading-dbt-core
description: Use when a user wants to upgrade, update, or migrate a dbt-core project to a newer or the latest version — e.g. "upgrade my dbt project," "migrate this off dbt-core 1.5," "get this project running on the latest dbt," "bump the dbt-core version." Upgrades a dbt-core v1 project (on 1.3, 1.4, 1.5, 1.6, or 1.7) all the way to 1.12, applying the required breaking, behavior, and deprecated changes from a data-driven issue corpus — replaying each pre-1.8 version boundary in order, then pinning post-1.8 behavior-change flags — running dbt-autofix first, then agentic and human-in-the-loop fixes, and verifying with dbt parse on dbt-core 1.12. Inputs — starting_version (the project's current dbt-core minor, one of 1.3/1.4/1.5/1.6/1.7) and adapter_type (snowflake/redshift/bigquery/databricks/spark); both are normally supplied by the caller (e.g. the dbt VS Code extension), with fallbacks described in the skill.
allowed-tools: "Bash(git:*), Bash(dbt:*), Bash(uvx:*), Bash(uv:*), Read, Write, Edit, Glob, Grep"
metadata:
  target_version: "1.12"
  supported_source_versions: "1.3, 1.4, 1.5, 1.6, 1.7"
  supported_adapters: "snowflake, redshift, bigquery, databricks, spark"
  arguments: "starting_version={1.3|1.4|1.5|1.6|1.7}; adapter_type={snowflake|redshift|bigquery|databricks|spark}"

Migrate a dbt project to dbt-core 1.12

You upgrade a dbt-core **v1** project all the way to **1.12** — not one minor bump. Two different mechanisms apply, and you must not confuse them:

• **Up to 1.8** — genuinely breaking changes with no compatibility shim. You

**replay every version boundary in order** from the project's current version, because consistent changelogs exist only per single minor version.

• **After 1.8** — every backwards-incompatible change ships **gated behind a

behavior-change flag** in `dbt_project.yml` `flags:`. You **do not fix those behaviors.** Instead, for each such change the project **actually exhibits**, you pin its gating flag to `false` so the project keeps its current semantics and parses on 1.12. Several of these flags already default to `true` in 1.12, so for an affected project leaving the flag unset silently adopts the new behavior — pinning is what makes the migration behavior-preserving.

Pin only what applies: a flag for a behavior the project does not use is dead config that hides the ones that matter. Detection per issue decides.

This skill is **data-driven**. The issues to resolve are **not** listed here — they live as one YAML file per issue under `references/`, colocated with this SKILL.md. Read them; **never fabricate an issue or a fix from memory.**

Each issue has an `automation_type` that decides how it is handled:

| `automation_type` | How you handle it | |---|---| | `deterministic` | **`dbt-autofix` handles it.** You do not re-implement it — you run autofix, then map its diff onto the issue and record it. | | `agentic` | **You apply the fix directly** (per `context.fixing`), then verify. | | `human` | **You propose the fix, show the diff, confirm with the user, then apply** (HITL). Never apply a `human` issue without explicit confirmation. | | `behavior_flag` | **`scripts/tools.py set-flag` handles it**, only when detection found it present (Step 5). A post-1.8 change gated behind a flag: when the project actually exhibits the gated behavior, the flag named in the issue's `behavior_flag.name` is pinned to `false` in `dbt_project.yml`. Never hand-edit these, never pin one the project does not exhibit, and never "fix" the underlying behavior instead. |

Two orthogonal flags modify handling regardless of `automation_type`:

• `out_of_repo_risk: true` — the fix may reach outside the repo (job `--select`,

`selectors.yml`, BI tools, mesh refs). Record it for the user; you cannot complete it from the repo alone.

• `environment_change: true` — dependency / Python-runtime / profiles change.

Make an **advisory edit only** (e.g. note the `requirements.txt`/`profiles.yml` change); **never execute** `pip`/installers, and exclude it from the parse gate.

Inputs

• **starting version** — supplied as an argument (from the extension / dbt

platform environments). Accept a manual override. One of `1.3`–`1.7`. If the project is already ≥1.8, only the post-1.8 behavior-flag pinning applies.

• **adapter type** — supplied as an argument: `snowflake` / `redshift` /

`bigquery` / `databricks` / `spark`. Fallback: read `profiles.yml` `type:` or the installed adapter. If undeterminable, ask.

Environment assumptions

• The project directory is a **git-versioned repo**.
• The environment has **`uvx` and `python`** available (used to run `scripts/tools.py`,

`dbt-autofix`, and a throwaway dbt-core 1.12 for the parse gate).

• **`scripts/tools.py`** sits under this SKILL.md's directory and does all

deterministic work (issue selection/ordering, results bookkeeping, report, git preflight). Always run it with `uv run --with pyyaml python scripts/tools.py …`.

Examples

**User says:** "Can you upgrade this dbt project to the latest dbt-core? It's currently on 1.5 and runs on Snowflake."

**Actions:** 1. `scripts/tools.py preflight` confirms a clean tree on branch `upgrade/dbt-1.12` → proceed. 2. `scripts/tools.py collect --from-version 1.5 --adapter snowflake` returns the applicable issues (1.5 through 1.11 bands); `scripts/tools.py init-results` seeds them all `pending`. 3. Read the project's models, macros, and `dbt_project.yml` against the collected issues. 4. Detection sweep marks the issues actually present as `detected`, the rest `skipped-not-present`. 5. `scripts/tools.py autofix` runs `dbt-autofix`, resolving the `deterministic` issues it can. 6. Remaining `agentic` issues are fixed directly; `behavior_flag` issues the project actually exhibits get pinned via `scripts/tools.py set-flag`; any `human` issue is shown as a diff and applied only after the user approves it. 7. `scripts/tools.py parse --adapt