Updated defer in the dbt Cloud IDE docs

[nataliefiann]

What are you changing in this pull request and why?

I have created this PR following this thread: https://dbt-labs.slack.com/archives/C01Q230T0E8/p1738162535339299 (reported by Gouthami / CSE) where a user expected defer to point to production references. It was confirmed, once defer is set jobs will configure to the staging env if it exists, regardless of job existence or success.

Checklist

• I have reviewed the Content style guide so my content adheres to these guidelines.
• The topic I'm writing about is for specific dbt version(s) and I have versioned it according to the version a whole page and/or version a block of content guidelines.
• I have added checklist item(s) to this list for anything anything that needs to happen before this PR is merged, such as "needs technical review" or "change base branch."
• The content in this PR requires a dbt release note, so I added one to the release notes page.

---

🚀 Deployment available! Here are the direct links to the updated files:

• https://docs-getdbt-com-git-nfiann-ide-defer-dbt-labs.vercel.app/docs/cloud/about-cloud-develop-defer

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs-getdbt-com	✅ Ready (Inspect)	Visit Preview	Feb 4, 2025 1:54pm

[mirnawong1]

hey @nataliefiann , thanks for opening this up! i'm not sure if it's just me not understanding the thread but some of the info was confusing so left some comments to clarify.

it sounds like @benmosher said the ide behaves in the same way as cloud cli. which means the following is prob what needs to be added but i would def confirm with ben and the team:

By default, the dbt Cloud IDE will prefer metadata from the project's "Staging" environment (if defined), otherwise "Production."

[nataliefiann]

Querying here: https://dbt-labs.slack.com/archives/C01Q230T0E8/p1738324525317939?thread_ts=1738162535.339299&cid=C01Q230T0E8

[benmosher]

ide behaves in the same way as cloud cli

IDE deferral did initially defer directly to production, so it makes sense that the docs reflect this, but has since been amended to work the same as CLI (staging if exists, else production) 🎯

[mirnawong1]

hey @nataliefiann , thanks for the updates! not sure if i'm just confusing things so might be good to have this reviewed again by someone else. i noticed some areas where the explanation of defer in the cloud ide doesn’t seem to align with the actual behavior (from what i gathered in the thread). to make sure we accurately capture how defer interacts with staging vs. production, especially since the IDE now follows the same logic as the CLI, i added the below comments/questions:

• snce defer logic can be tricky, i recommend getting a technical review first to confirm the behavior before updating the docs. if you've done this already, then nevermind. but if not, before a docs review or finalizing, it would be helpful to get a technical review to confirm the details.
• separate x project ref from deferral behavior
  • x project ref -- if staging environment exists, child projects reference their parent’s staging environment. otherwise, they reference production. (is this the right interpretation?)
  • deferral -- when running in a dev environment, defer will use the manifest from the latest successful deploy job in staging (if one exists). if there’s no successful deploy job, deferral doesn't automatically fall back to production. (is this the right interpretation?)
• ide deferral doesn't default to prod
  • the correct behavior seems to be that the IDE defers to staging first (if a successful deploy job exists), then production. just like mentioned here in the cloud cli
  • Ben's comment here seems to summarize this well i think
  • the existence of staging impacts xproject ref and deferral
• staging can be used even if no successful deploy job exists
  • if staging exists but has no successful (non-CI) deploy job, both x project ref and deferral will still reference staging. this means prod will not be used, even if staging is outdated or incomplete.
  • it also seems like deferral succeeds it if looks at a successful deleted job run
    • seems like this is something that needs product confirmation? could be a bug? not sure?
• rewording the "defer to production" button
  • the toggle says "Defer to production," but functionally, it defers to staging first (if available), otherwise to production.
  • we should clarify that (e..g not 'toggle the Defer to production button' but 'toggle the Defer to staging/production button'
• again, not sure if me but i found the intro sentences confusing and diving into staging env/jobs, etc. first are tricky concepts to understand before going into the ‘to enable defer in the ide...’. sentence.
  • i also think you should keep the 'for example, if you were to start developing..' since the context is an example.

let me know if you have any questions!

[benmosher]

Looks technically accurate to me! I commented some suggestions just trying to reinforce the staging OR production deferral.

Might be good to have someone from @dbt-labs/dx review as well?