Skip to main content

Special cases

TL;DR

dbt special cases - multiple environments, token rotation, Core migration, managed buckets, shared IAM roles, Cloud and Core in parallel.

Connect

Multiple environments, more than one dbt connection, token rotation, the Core-to-new-experience migration, and other setups the standard guides don't cover.

Multiple dbt environments (dev / test / prod)​

If several dbt environments feed one Atlan tenant, decide up front how they map to connections:

  • Scope each connection deliberately. Use Include/Exclude Metadata (dbt Cloud) or separate bucket prefixes (dbt Core) so each connection sees exactly one environment. A token or credential scoped to the wrong environment silently crawls the wrong assets.
  • Expect duplicates if you don't. The same model crawled from two environments appears twice, and lineage stitches to whichever warehouse connection matches - a top source of "why are there upstream duplicates?" confusion.
  • Multiple dbt connections pointing at the same warehouse connection is supported - but only one dbt connection must enrich each warehouse connection, or enrichment becomes unpredictable. See Troubleshooting dbt connectivity.

Rotating dbt Cloud tokens​

Tokens expire, people leave, security rotates secrets. To swap the token without rebuilding the connection:

  1. Go to Workflows → Monitor → your dbt workflow → most recent run → Config tab.
  2. Under dbt Credential, click Edit Credentials.
  3. Re-enter both fields: the Host Name / access URL and the new token. The form treats every save as a full overwrite - pasting only the token while the host shows masked dots submits an incomplete payload and fails with "Host URL and API token are required".
  4. Run Test Authentication, then Update.
Who can do this

Editing workflow credentials needs workflow admin; editing the connection itself needs connection admin on that dbt connection. They're separate roles - having one doesn't grant the other. If the edit form shows no input fields at all, take a screenshot and raise a ticket; that's a product bug, not your setup.

Migrating from Core (legacy) to Cloud/object storage experience​

Atlan has been migrating dbt connections off the legacy Core extraction method - affected admins received an email with a deadline. What to know:

  • The migration reuses your existing bucket and access - it changes how Atlan reads, not where your files live.
  • Re-check every field on save, especially Region: a missing/unmapped region blocks the save with "Region not found." If that happens near your deadline, raise a ticket immediately and reference the migration email - don't retry silently.
  • After migrating, run one crawl and diff the asset count against the last legacy run before declaring victory.

Using Atlan-managed bucket​

  • Support provisions a dedicated prefix and upload credentials; your pipeline uploads artifacts there instead of your own bucket.
  • One prefix per Atlan environment - ask for a second prefix (for example, dbt-dev/) rather than mixing dev and prod files under one.
  • Treat the upload credentials like any production secret; if they rotate, your uploads fail silently and the catalog goes stale.

One IAM role for several Atlan crawlers (AWS)​

The dbt Core role pattern (your role + Atlan's identity in the trust policy) is the same pattern other Atlan AWS connectors use (S3, Athena, miner backfills). You can reuse one role for all of them - grant it read on each bucket involved - which keeps your security review to a single role. Just remember: any Atlan workflow using that role can read everything it can read.

Running dbt Cloud and dbt Core side by side​

Supported - create one connection per flavor. Common during a Core→Cloud migration:

  • Keep both connections scoped so the same project isn't crawled by both, or you'll double-catalog it.
  • When cut-over completes, archive the old connection's assets rather than deleting the connection first - you keep history and lineage.