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
- Cloud
- Self-host
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.
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.
Connection details
Required permissions
A personal access token carries its user’s permissions instead of these sets.
Agent capabilities
Verify the connection
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
The provider rejected these credentials
The provider rejected these credentials
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.
Model, lineage, or metric questions fail
Model, lineage, or metric questions fail
The Production environment ID is wrong or isn’t a number. Copy only the number after
/environments/ from your production environment’s URL.Metric questions return nothing useful
Metric questions return nothing useful
The account has no Semantic Layer set up, or the token lacks Semantic Layer Only. Job, model, and lineage questions still work without it.
could not clone the repository; check the URL, branch, username, and token
could not clone the repository; check the URL, branch, username, and token
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.dbt_project.yml not found in the project folder
dbt_project.yml not found in the project folder
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 tools for this connection took too long to start
The tools for this connection took too long to start
The first Self-host connection clones the repository and installs packages, which can take a few minutes. Wait a minute, then connect again.
Compiling or previewing fails with a database error
Compiling or previewing fails with a database error
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
SELECTqueries as this user, and dbt runs project hooks when it compiles. Grant onlyUSAGEandSELECT. - Scope the repository token: use a GitLab deploy token or a GitHub fine-grained token that can only read the one dbt repository.
Related
PostgreSQL
Connect the warehouse directly with a read-only user.
Connections overview
See every connection and how CloudThinker reaches private services.