Skip to main content
Connect dbt so CloudThinker agents can explain failed job runs, trace model lineage, check model health, and read compiled SQL, without running anything. The Cloud tab connects a dbt Cloud account with an access token, and the Self-host tab connects a dbt Core project from its Git repository and a read-only warehouse user.
dbt isn’t generally available yet. To use it, contact CloudThinker. Self-host means dbt Core, not a self-hosted deployment of CloudThinker.

Prerequisites

  • Cloud: a dbt account on a Starter, Enterprise, or Enterprise+ plan, and a production environment. Metric questions also need the dbt Semantic Layer set up.
  • Self-host: a dbt Core project in a GitLab or GitHub repository, served over HTTPS, that builds into PostgreSQL. PostgreSQL is the only warehouse the Self-host tab supports.
  • Self-host network access: CloudThinker must reach your Git host and your PostgreSQL port from the internet. See Reaching private services.

Setup

1

Copy your Access URL

In dbt, open Account settings and find Access URLs. Copy the host of your account’s URL, such as cloud.getdbt.com or ab123.us1.dbt.com, without https://.CloudThinker sends the token only to getdbt.com and dbt.com hosts. If your account uses a different domain, contact CloudThinker.
2

Create an access token

Which token you can create depends on your dbt plan:
  • Enterprise or Enterprise+: open Account settings → Service Tokens and click + Create service token. Add the Job Viewer and Metadata Only permission sets, plus Semantic Layer Only if agents should answer metric questions. Click Save and copy the token, which dbt shows only once.
  • Starter: open Account settings → API tokens → Personal tokens and click Create personal access token. A personal token carries the permissions of the user who creates it, so create it as a user with read-only access where you can.
See dbt’s guides to service tokens and personal access tokens.
3

Copy the production environment ID

Go to Orchestration → Environments and click your production environment. Copy only the number after /environments/ in the page URL.
4

Add the connection in CloudThinker

Open More → Workspace settings → Connections, select dbt, and click Connect. Choose Cloud, fill in the fields in Connection details, and click Connect.Success state: the connection shows a Connected status.
Editing a saved connection keeps its original type. To use the other tab, add a second connection.

Connection details

Required permissions

A personal access token carries its user’s permissions instead of these sets.
Give the service token only the permission sets above, and give the warehouse user only USAGE and SELECT. Neither needs write or admin access.

Agent capabilities

Verify the connection

Expect the models and sources that feed orders and the models built from it. An unknown-model error means the name is wrong or the model isn’t in the production environment or the branch you set.

Example prompts

Write access

The dbt connection is read-only. Agents can’t run, retry, or cancel dbt Cloud jobs, and they can’t run, build, test, seed, or snapshot a dbt Core project. CloudThinker never pushes to your repository.

Troubleshooting

dbt refused the token. Check that the Access URL is your account’s host, that the token hasn’t expired or been revoked, and that a service token holds Job Viewer and Metadata Only. Create a new token and connect again.
The Production environment ID is wrong or isn’t a number. Copy only the number after /environments/ from your production environment’s URL.
The account has no Semantic Layer set up, or the token lacks Semantic Layer Only. Job, model, and lineage questions still work without it.
CloudThinker couldn’t read the repository. Check that the URL starts with https://, the branch or tag exists, the username matches the token (a GitLab deploy token’s own username, or your GitHub username), and the token can read that repository. If the URL contains a username or token, remove it and use the Repository username and Repository read token fields.
Set Project folder to the folder that holds dbt_project.yml, relative to the repository root, such as analytics. Leave it empty when the file is at the root.
The first Self-host connection clones the repository and installs packages, which can take a few minutes. Wait a minute, then connect again.
CloudThinker can’t reach PostgreSQL, or the user lacks access. Check the host, port, database, and password, that your firewall allows CloudThinker, and that the user has USAGE and SELECT on the schemas your models read.

Security

  • Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
  • Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
  • Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
  • Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
  • Use a read-only warehouse user: previews run SELECT queries as this user, and dbt runs project hooks when it compiles. Grant only USAGE and SELECT.
  • Scope the repository token: use a GitLab deploy token or a GitHub fine-grained token that can only read the one dbt repository.

PostgreSQL

Connect the warehouse directly with a read-only user.

Connections overview

See every connection and how CloudThinker reaches private services.