/upgrading-dbt

name: upgrading-dbt
description: Use when a user wants to upgrade, update, or migrate a dbt project to the latest version — e.g. "upgrade my dbt project," "migrate this off dbt 1.5," "get this project running on the latest dbt," "bump the dbt version." Upgrades a dbt 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. Inputs — starting_version (the project's current dbt 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 1.12

You upgrade a dbt **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 arrive as a **precompiled bundle**, `references/kb_<FROM>_<ADAPTER>.json`, colocated with this SKILL.md. One bundle per starting version × adapter, each self-contained: every issue carries its own `action`, `automation_type`, and `context.detection` / `context.fixing`. Read the bundle; **never fabricate an issue or a fix from memory.**

> The `kb/` YAML corpus is the *source* those bundles are compiled from, at > build time, by CI. It is not read during a migration and does not ship in the > package. Never try to read it at runtime — work from the bundle.

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

| `automation_type` | How you handle it | |---|---| | `deterministic` | **Handled by a tool where your profile has one.** Locally, run the `autofix` operation (`dbt-migrate-1x`) and map its diff onto the issue. In Studio there is no such tool for this — apply the fix yourself per `context.fixing`, exactly like an `agentic` issue, then record it the same way; see your profile's `autofix` operation. | | `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` | **The `set-flag` operation 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 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.

Execution profile — read one before Step 0

This skill runs in two environments with **the same rules and the same phases** but completely different mechanics. The rules live here; the mechanics live in a profile you load first.

| Environment | How you can tell | Profile | |---|---|---| | **Local / VS Code extension** | You have a shell (`Bash`) and can run `uv` / `python` | [references/exec-local.md](references/exec-local.md) | | **dbt platform (Studio)** | No shell at all; you have `edit_file`, `dbt_command`, `git`, and the `load_skill_resource_file` tools | [references/exec-platform.md](references/exec-platform.md) |

Load **exactly one**, as the first action of Step 0. Locally, read it from disk; in Studio, read it with `load_skill_resource_file`. If you cannot tell which environment you are in, check whether a shell tool exists: **no shell means Studio.** Never mix the two — a shell command in Studio cannot run, and Studio tools do not exist locally.

Everything below refers to work by **operation name**. The profile you loaded maps each operation to a concrete invocation, and it is the onl