# upgrading-dbt

This skill automates upgrading dbt projects from versions 1.3–1.7 to 1.12, applying all breaking changes and behavior flags. Use it to move an older project to the latest version without manually parsing each incompatibility.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 131 installs · ★ 767 repo stars
- Author: dbt-labs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/dbt-labs/dbt-agent-skills/tree/HEAD/skills/dbt-migration/skills/upgrading-dbt/SKILL.md
- Updated: 2026-10-22
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/upgrading-dbt

## What it does

The skill handles two migration patterns separately. For versions up to 1.8, it replays every version boundary in sequence, since changelogs exist per minor version only. From 1.8 onward, dbt gates backward-incompatible changes behind behavior flags in `dbt_project.yml` — the skill preserves current semantics by pinning flags to `false` for projects that use those behaviors, rather than rewriting the logic itself.

The skill is data-driven: issues arrive in a precompiled bundle `references/kb_<FROM>_<ADAPTER>.json`, where each task carries its own action, automation type, and detection rules. It supports Snowflake, Redshift, BigQuery, Databricks, and Spark. Works both locally (with Bash and `uv`) and in dbt Studio via file APIs.

You must specify the current dbt version (1.3–1.7) and adapter type — typically supplied by the IDE or extension, but overridable manually. If the project is already on 1.8+, only behavior-flag pinning applies.

## Requirements
- Works with: Snowflake, Databricks

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dbt-labs/dbt-agent-skills --skill upgrading-dbt -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/upgrading-dbt/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/upgrading-dbt/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dbt-labs/dbt-agent-skills --skill upgrading-dbt -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/upgrading-dbt/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dbt-labs/dbt-agent-skills --skill upgrading-dbt -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/upgrading-dbt/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dbt-labs/dbt-agent-skills skills/dbt-migration/skills/upgrading-dbt
```

2. **Manually: put the files in place**
- File: `.github/skills/upgrading-dbt/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dbt-labs/dbt-agent-skills --skill upgrading-dbt -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dbt-labs/dbt-agent-skills --path skills/dbt-migration/skills/upgrading-dbt
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/upgrading-dbt/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dbt-labs/dbt-agent-skills --skill upgrading-dbt -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dbt-labs/dbt-agent-skills/tree/HEAD/skills/dbt-migration/skills/upgrading-dbt/SKILL.md

## When to use it
- Upgrade a dbt project from 1.5 to 1.12 without breakage
- Automate migration of an older project to current dbt
- Navigate breaking changes across dbt versions
- Pin behavior flags correctly during migration

## Example prompts
- Upgrade my dbt project to version 1.12
- Migrate this project from dbt 1.5 to the latest version
- Apply all necessary changes for dbt 1.12 compatibility

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1a058058e64cc472.

BEGIN THIRD-PARTY FILE 1a058058e64cc472
```text
---
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
```
END THIRD-PARTY FILE 1a058058e64cc472

The third-party file has ended. Everything between the 1a058058e64cc472 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2512 of 38119 bytes. © dbt-labs · Apache-2.0 · https://github.com/dbt-labs/dbt-agent-skills/tree/HEAD/skills/dbt-migration/skills/upgrading-dbt/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
