All jobs

Ship a Breaking Change to a dbt Model With Model Versions

Yes. An agent turns a breaking change into a versioned dbt model: v1 kept and deprecated, v2 as latest, tests split per version, and a PR with parse proof.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the model and everything that refers to it before versioning anything. In a project like dbt-labs/jaffle-shop, dbt_project.yml names jaffle_shop at version 3.0.0 with require-dbt-version: ">=2.0.0", staging models as views and marts as tables. models/marts/customers.sql joins stg_customers to the orders mart and derives count_lifetime_orders, first_ordered_at, last_ordered_at, lifetime_spend_pretax, lifetime_tax_paid, lifetime_spend and a customer_type column that is 'returning' or 'new' from an is_repeat_buyer flag the CTE computes and then drops. customers.yml is more than a column list: it enables a semantic model with first_ordered_at as the aggregation time, declares customer_id as the primary entity, customer_type as a categorical dimension with an accepted_values test, four simple metrics, a derived average_order_value, and a saved query with an export. A dbt_utils.expression_is_true test checks that pretax plus tax equals spend. No model in the project has versions or latest_version, and the only CI is three dbt Cloud jobs, one each for Snowflake, BigQuery and Postgres, started by .github/workflows/scripts/dbt_cloud_run_job.py on pull requests to main and staging.

The change the prompt asks for replaces the text customer_type with a boolean is_repeat_buyer, which is a breaking change for every downstream query that filters on 'returning'. The agent makes it as two versions of one model. customers.sql becomes customers_v1.sql, unchanged, and customers_v2.sql exposes is_repeat_buyer straight from the CTE and drops the case expression. In customers.yml the model gains latest_version: 2 and a versions list: version 1 with columns: {include: all} and a deprecation_date a quarter out, version 2 with include: all, exclude: [customer_type] and the new is_repeat_buyer column with a not_null test. The accepted_values test stays on customer_type and therefore applies to v1 only, since v2 excludes the column. The semantic model follows the columns: is_repeat_buyer becomes a categorical dimension, and because ref('customers') resolves to the latest version, the metrics and saved query move to v2 without a rename.

The agent then finds every ref('customers') in the project with dbt ls --select +customers+ and reads each: in this project nothing downstream selects customer_type, so no consumer needs ref('customers', v=1), and the pull request says that explicitly. The version in dbt_project.yml is bumped to 4.0.0, since the project's own convention treats it as semantic.

Verification runs in the sandbox with dbt installed from the project's requirements.txt plus an adapter for parsing: dbt deps pulls dbt_utils 1.4.1 and audit_helper from packages.yml, dbt parse succeeds with the versioned model, dbt ls --select customers --resource-type model lists customers.v1 and customers.v2, and dbt compile renders both SQL files and shows v2's relation is customers while v1 compiles to customers_v1, which is how existing consumers see no change until the deprecation date. sqlfluff lint runs on the new SQL with the project's .sqlfluff rules. The agent runs no warehouse query, because the project's data lives in dbt Cloud, and says so; the three dbt Cloud CI jobs on the pull request are the build.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Make a breaking change to the customers mart in this dbt project using model versions. Read dbt_project.yml, packages.yml, the customers model and its YAML, every model that refs it, the CI workflows and the sqlfluff config first. The change: replace the text customer_type column with a boolean is_repeat_buyer taken from the flag the model already computes. Keep version 1 as the current SQL with a deprecation date one quarter out, add version 2 as the latest with the old column excluded and the new one included with a not_null test, keep the accepted_values test applying only to v1, and move the semantic model's dimension to the new column so metrics and the saved query follow the latest version. Find every ref to the model and pin any consumer that selects the removed column to version 1, or say that none does. Bump the project version. Run dbt deps, dbt parse, dbt ls to show both versions, dbt compile to show their relation names, and sqlfluff on the new SQL; do not run against a warehouse. Open a pull request that explains the version split and what each consumer sees.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that renames models/marts/customers.sql to customers_v1.sql, adds customers_v2.sql, edits customers.yml and dbt_project.yml, and touches no staging model. The description explains in three short paragraphs what v1 and v2 are, that ref('customers') now means v2 while the warehouse relation customers_v1 keeps serving old queries, and the date after which v1 warns at parse time.

The run's record keeps the dbt parse output, the dbt ls listing with both versions, the compiled SQL paths and relation names for each, and the sqlfluff result, so a reviewer sees the project parses and both versions compile before dbt Cloud spends a run. The description names the downstream models it read and states that none selects the removed column.

Before merging, a reviewer waits for the three dbt Cloud CI jobs on the pull request, which build both versions in a PR schema, then checks that a dashboard query against customers sees is_repeat_buyer and one against customers_v1 still sees customer_type. The deprecation date in the YAML is the reminder to drop v1.

Run it on every Linear issue labelled breaking-change

A team that plans analytics work in Linear adds an automation with a linear trigger on linear.issue.labeled for the label breaking-change, the Project that has this repository, and this prompt. Labelling the issue that describes the column change starts one run with the issue's text after the prompt, and the pull request links back to the issue.

The trigger fills in no placeholder, so the issue has to say which model and which column, and the same automation handles the next breaking change, such as renaming a key in the orders mart, with the agent reading the project fresh each time.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

A model version touches the SQL file names, the YAML's versions block, the tests that must apply to one version only, the semantic model that must follow the latest, and every consumer that might need pinning, and a mistake in any of them is a dashboard that breaks on Monday. The agent reads the real project in its own sandbox, makes the edits together, and runs parse, list, compile and lint with the output kept.

The pull request says what each consumer sees after the merge and what the sandbox could and could not prove, so the reviewer's job is to read the dbt Cloud build and one query per version, not to reconstruct the change.

Frequently asked questions

What does ref('customers') resolve to after this?

Version 2, because latest_version: 2. A model that needs the old column writes ref('customers', v=1). In this project the agent finds no downstream model selecting customer_type, so nothing is pinned, and the pull request says so.

What are the relation names in the warehouse?

The latest version keeps the model's name, customers, and the older version gets a _v1 suffix, customers_v1, which is the dbt default and what dbt compile shows in the sandbox. Queries written against the old table keep working until v1 is removed.

Does the semantic layer break?

No. The semantic model is embedded in the model's YAML and follows the latest version, and the agent moves the categorical dimension from customer_type to is_repeat_buyer. The four metrics, the derived metric and the saved query parse unchanged, which dbt parse confirms.

What happens at the deprecation date?

dbt warns at parse time that the version is deprecated, and nothing stops working. A follow-up pull request deletes customers_v1.sql and its entry in versions, after checking the warehouse's query history for the old relation.

Why is nothing run against the warehouse?

The project's data lives in dbt Cloud and the sandbox has no credentials for it. The agent runs deps, parse, ls, compile and sqlfluff, and the three dbt Cloud CI jobs on the pull request build both versions in a PR schema.

More dbt jobs

More jobs like this: Turn a Linear label into a PR

Keep reading