> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# dbt

> dbt Cloud 또는 dbt Core 프로젝트를 연결하여 에이전트가 실패한 실행을 설명하고, 리니지를 추적하며, 모델을 미리 볼 수 있게 합니다

**dbt**를 연결하면 CloudThinker 에이전트가 아무것도 실행하지 않고 실패한 job 실행을 설명하고, 모델 리니지를 추적하며, 모델 상태를 점검하고, 컴파일된 SQL을 읽을 수 있습니다. **Cloud** 탭은 액세스 토큰으로 dbt Cloud 계정을 연결하고, **Self-host** 탭은 Git 저장소와 읽기 전용 웨어하우스 사용자로 dbt Core 프로젝트를 연결합니다.

> [!NOTE]
>
> dbt는 아직 정식 출시되지 않았습니다. 사용하려면 [CloudThinker에 문의](https://cloudthinker.io/contact)하세요. **Self-host**는 CloudThinker의 자체 호스팅 배포가 아니라 dbt Core를 의미합니다.

## 사전 요구사항

* **Cloud**: Starter, Enterprise 또는 Enterprise+ 플랜의 dbt 계정과 프로덕션 환경. 지표 관련 질문에는 [dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) 설정도 필요합니다.
* **Self-host**: GitLab 또는 GitHub 저장소에 있고 HTTPS로 제공되며 **PostgreSQL**에 빌드되는 dbt Core 프로젝트. Self-host 탭이 지원하는 웨어하우스는 PostgreSQL뿐입니다.
* **Self-host 네트워크 접근**: CloudThinker가 인터넷에서 Git 호스트와 PostgreSQL 포트에 도달할 수 있어야 합니다. [비공개 서비스에 연결하기](https://docs.cloudthinker.io/ko/guide/connections/overview.md#비공개-서비스에-연결하기)를 참고하세요.

## 설정

> [tab] Cloud
>
> **1. Access URL 복사**
>
> dbt에서 **Account settings**를 열고 **Access URLs**를 찾으세요. 계정 URL의 호스트를 `https://` 없이 복사하세요. 예: `cloud.getdbt.com` 또는 `ab123.us1.dbt.com`.
>
> CloudThinker는 `getdbt.com` 및 `dbt.com` 호스트로만 토큰을 전송합니다. 계정이 다른 도메인을 사용한다면 [CloudThinker에 문의](https://cloudthinker.io/contact)하세요.
>
> **2. 액세스 토큰 생성**
>
> 생성할 수 있는 토큰은 dbt 플랜에 따라 다릅니다:
>
> * **Enterprise 또는 Enterprise+**: **Account settings → Service Tokens**를 열고 **+ Create service token**을 클릭하세요. **Job Viewer**와 **Metadata Only** 권한 세트를 추가하고, 에이전트가 지표 질문에 답해야 한다면 **Semantic Layer Only**도 추가하세요. **Save**를 클릭하고 토큰을 복사하세요. dbt는 토큰을 한 번만 보여줍니다.
> * **Starter**: **Account settings → API tokens → Personal tokens**를 열고 **Create personal access token**을 클릭하세요. 개인 토큰은 생성한 사용자의 권한을 그대로 가지므로, 가능하면 읽기 전용 접근 권한을 가진 사용자로 생성하세요.
>
> dbt의 [서비스 토큰](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) 및 [개인 액세스 토큰](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) 가이드를 참고하세요.
>
> **3. 프로덕션 환경 ID 복사**
>
> **Orchestration → Environments**로 이동해 프로덕션 환경을 클릭하세요. 페이지 URL에서 `/environments/` 뒤의 숫자만 복사하세요.
>
> **4. CloudThinker에 연결 추가**
>
> **More → Workspace settings → Connections**를 열고 **dbt**를 선택한 뒤 **Connect**를 클릭하세요. **Cloud**를 선택하고 [연결 세부 정보](#연결-세부-정보)의 필드를 입력한 뒤 **Connect**를 클릭하세요.
>
> **성공 상태:** 연결이 **Connected** 상태로 표시됩니다.

> [tab] Self-host
>
> **1. 저장소 읽기 토큰 생성**
>
> > [tab] GitLab
> >
> > 프로젝트에서 **Settings → Repository**를 열고 **Deploy tokens**를 펼친 뒤 **Add token**을 클릭하세요. `read_repository` 스코프만 선택하고 **Create deploy token**을 클릭하세요. 생성된 사용자 이름(예: `gitlab+deploy-token-1`)과 토큰을 복사하세요. [GitLab deploy tokens](https://docs.gitlab.com/user/project/deploy_tokens/)를 참고하세요.
>
> > [tab] GitHub
> >
> > **Settings → Developer settings → Personal access tokens → Fine-grained tokens**를 열고 **Generate new token**을 클릭하세요. **Repository access**에서 **Only select repositories**를 선택해 dbt 저장소를 고르고, 토큰에 해당 저장소에 대한 읽기 전용 접근 권한을 부여하세요. 이 토큰에는 본인의 GitHub 사용자 이름을 사용합니다. [GitHub fine-grained tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)를 참고하세요.
>
> **2. 읽기 전용 PostgreSQL 사용자 생성**
>
> 관리자로 연결한 뒤, 모델과 소스가 있는 스키마에 대한 읽기 권한을 사용자에게 부여하세요. 이 예시는 `analytics`를 사용합니다:
>
> ```sql theme={null}
> CREATE ROLE cloudthinker_dbt WITH LOGIN PASSWORD '<secure-password>';
> GRANT CONNECT ON DATABASE your_database TO cloudthinker_dbt;
> GRANT USAGE ON SCHEMA analytics TO cloudthinker_dbt;
> GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO cloudthinker_dbt;
> ```
>
> 그 외에는 아무 권한도 부여하지 마세요. dbt는 컴파일할 때 프로젝트의 훅을 실행하므로, 읽기 전용 사용자를 쓰면 훅이 데이터를 변경하지 못합니다.
>
> **3. 네트워크 접근 개방**
>
> CloudThinker가 HTTPS로 Git 호스트에, 그리고 PostgreSQL 포트(기본값 `5432`)에 도달할 수 있도록 허용하세요. 이 문서에는 CloudThinker의 이그레스 IP 목록이 게시되어 있지 않습니다. CloudThinker 담당자에게 요청하거나 [문의](https://cloudthinker.io/contact)하세요.
>
> **4. CloudThinker에 연결 추가**
>
> **More → Workspace settings → Connections**를 열고 **dbt**를 선택한 뒤 **Connect**를 클릭하세요. **Self-host**를 선택하고 [연결 세부 정보](#연결-세부-정보)의 필드를 입력한 뒤 **Connect**를 클릭하세요.
>
> **성공 상태:** 연결이 **Connected** 상태로 표시됩니다. 첫 연결은 CloudThinker가 저장소를 클론하고 프로젝트 패키지를 설치하는 동안 2분 정도 걸릴 수 있습니다.

저장된 연결을 편집해도 원래 유형은 유지됩니다. 다른 탭을 사용하려면 두 번째 연결을 추가하세요.

## 연결 세부 정보

| Cloud 필드 | 필수 | 입력 값 |
| - | - | - |
| **Access URL** | 예 | **Account settings → Access URLs**의 호스트, 예: `cloud.getdbt.com` |
| **Access token** | 예 | 생성한 서비스 토큰 또는 개인 액세스 토큰 |
| **Production environment ID** | 예 | 프로덕션 환경 URL에서 `/environments/` 뒤의 숫자. 모델, 소스, 리니지, 지표 조회에 사용됩니다 |

| Self-host 필드 | 필수 | 입력 값 |
| - | - | - |
| **Git repository URL** | 예 | 사용자 이름이나 토큰이 포함되지 않은 HTTPS 클론 URL, 예: `https://gitlab.com/acme/analytics.git` |
| **Repository username** | 예 | GitLab deploy token의 사용자 이름 또는 본인의 GitHub 사용자 이름. 기본값은 `oauth2` |
| **Repository read token** | 예 | deploy token 또는 fine-grained token |
| **Branch or tag** | 아니요 | 비워 두면 기본 브랜치를 읽습니다 |
| **Project folder** | 아니요 | 저장소 루트 기준으로 `dbt_project.yml`이 있는 폴더. 루트에 있다면 비워 두세요 |
| **Warehouse** | 예 | **PostgreSQL** |
| **Warehouse host** | 예 | 포트를 제외한 호스트명 또는 IP 주소 |
| **Warehouse port** | 예 | 기본값은 `5432` |
| **Database** | 예 | 프로젝트가 빌드되는 데이터베이스 |
| **Schema** | 예 | 프로덕션 모델이 빌드되는 스키마. 컴파일된 SQL과 미리보기는 이 스키마를 기준으로 `ref()`를 해석합니다 |
| **Warehouse user** | 예 | 읽기 전용 사용자 |
| **Warehouse password** | 예 | 해당 사용자의 비밀번호 |

## 필요 권한

| 탭 | 에이전트가 할 작업 | 접근 권한 |
| - | - | - |
| **Cloud** | job, 실행, 로그, 실행 아티팩트 읽기 | 서비스 토큰의 **Job Viewer** |
| **Cloud** | 모델, 소스, exposure, 리니지 읽기 | 서비스 토큰의 **Metadata Only** |
| **Cloud** | 지표 질문에 답변 | 서비스 토큰의 **Semantic Layer Only** |
| **Self-host** | 프로젝트 읽기 | GitLab deploy token의 `read_repository`, 또는 GitHub fine-grained token의 단일 저장소 읽기 권한 |
| **Self-host** | 모델 컴파일 및 행 미리보기 | 스키마에 대한 `USAGE`와 테이블에 대한 `SELECT` |

개인 액세스 토큰은 이 권한 세트 대신 해당 사용자의 권한을 가집니다.

> [!TIP]
>
> 서비스 토큰에는 위의 권한 세트만, 웨어하우스 사용자에게는 `USAGE`와 `SELECT`만 부여하세요. 둘 다 쓰기 권한이나 관리자 권한이 필요 없습니다.

## 에이전트 기능

| 탭 | 에이전트가 할 수 있는 작업 | 범위 |
| - | - | - |
| **Cloud** | 프로젝트, job, 실행 목록 조회 및 실행의 상태, 오류, 로그, 아티팩트 읽기 | 읽기 전용 |
| **Cloud** | 모델, 소스, exposure, 매크로 읽기, 리니지 추적, 모델 상태와 실행 시간 점검 | 프로덕션 환경 사용 |
| **Cloud** | 지표, 디멘션, 저장된 쿼리 목록 조회, 지표의 SQL 표시, 지표 쿼리 | Semantic Layer 필요. 지표 쿼리는 웨어하우스에서 실행되며 비용도 그곳에서 청구됩니다 |
| **Self-host** | 프로젝트 파싱 및 목록 조회, 리니지 추적, 노드 세부 정보 읽기 | 설정한 브랜치를 읽음. 실행 이력 없음 |
| **Self-host** | 모델을 SQL로 컴파일하고 행 미리보기 | 미리보기당 최대 100행 |

### 연결 확인

```text theme={null}
Show the upstream and downstream lineage of the orders model
```

`orders`에 데이터를 공급하는 모델과 소스, 그리고 `orders`로부터 빌드되는 모델이 표시되어야 합니다. 알 수 없는 모델이라는 오류가 나오면 이름이 틀렸거나, 해당 모델이 프로덕션 환경 또는 설정한 브랜치에 없는 것입니다.

### 예시 프롬프트

```text theme={null}
Why did the last run of the nightly job fail?
Is the customers model healthy, and how long do its runs take?
Show the compiled SQL for the orders model and preview 5 rows
```

## 쓰기 접근

dbt 연결은 읽기 전용입니다. 에이전트는 dbt Cloud job을 실행, 재시도, 취소할 수 없으며, dbt Core 프로젝트에서 run, build, test, seed, snapshot을 실행할 수 없습니다. CloudThinker는 저장소에 절대 푸시하지 않습니다.

## 문제 해결

> [accordion] The provider rejected these credentials
>
> dbt가 토큰을 거부했습니다. **Access URL**이 계정의 호스트인지, 토큰이 만료되거나 취소되지 않았는지, 서비스 토큰이 **Job Viewer**와 **Metadata Only**를 보유하고 있는지 확인하세요. 새 토큰을 생성한 뒤 다시 연결하세요.

> [accordion] 모델, 리니지, 지표 질문이 실패함
>
> **Production environment ID**가 틀렸거나 숫자가 아닙니다. 프로덕션 환경 URL에서 `/environments/` 뒤의 숫자만 복사하세요.

> [accordion] 지표 질문에 유용한 답이 나오지 않음
>
> 계정에 Semantic Layer가 설정되어 있지 않거나, 토큰에 **Semantic Layer Only**가 없습니다. job, 모델, 리니지 질문은 이것 없이도 동작합니다.

> [accordion] could not clone the repository; check the URL, branch, username, and token
>
> CloudThinker가 저장소를 읽지 못했습니다. URL이 `https://`로 시작하는지, 브랜치 또는 태그가 존재하는지, 사용자 이름이 토큰과 일치하는지(GitLab deploy token 자체의 사용자 이름 또는 본인의 GitHub 사용자 이름), 토큰이 해당 저장소를 읽을 수 있는지 확인하세요. URL에 사용자 이름이나 토큰이 포함되어 있다면 제거하고 **Repository username**과 **Repository read token** 필드를 사용하세요.

> [accordion] dbt\_project.yml not found in the project folder
>
> **Project folder**를 저장소 루트 기준으로 `dbt_project.yml`이 있는 폴더(예: `analytics`)로 설정하세요. 파일이 루트에 있다면 비워 두세요.

> [accordion] The tools for this connection took too long to start
>
> 첫 Self-host 연결은 저장소를 클론하고 패키지를 설치하므로 몇 분이 걸릴 수 있습니다. 1분 정도 기다린 뒤 다시 연결하세요.

> [accordion] 컴파일 또는 미리보기가 데이터베이스 오류로 실패함
>
> CloudThinker가 PostgreSQL에 도달하지 못하거나, 사용자에게 접근 권한이 없습니다. 호스트, 포트, 데이터베이스, 비밀번호를 확인하고, 방화벽이 CloudThinker를 허용하는지, 그리고 사용자가 모델이 읽는 스키마에 `USAGE`와 `SELECT` 권한을 가지고 있는지 확인하세요.

## 보안

* **최소 권한** — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
* **기본 읽기 전용** — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
* **자격증명 교체** — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
* **오프보딩 시 취소** — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.

- **읽기 전용 웨어하우스 사용자 사용**: 미리보기는 이 사용자로 `SELECT` 쿼리를 실행하며, dbt는 컴파일할 때 프로젝트 훅을 실행합니다. `USAGE`와 `SELECT`만 부여하세요.
- **저장소 토큰 범위 제한**: 하나의 dbt 저장소만 읽을 수 있는 GitLab deploy token 또는 GitHub fine-grained token을 사용하세요.

## 관련 항목

> [card] [PostgreSQL](https://docs.cloudthinker.io/ko/guide/connections/postgresql.md)
>
> 읽기 전용 사용자로 웨어하우스를 직접 연결합니다.

> [card] [연결 개요](https://docs.cloudthinker.io/ko/guide/connections/overview.md)
>
> 모든 연결과 CloudThinker가 비공개 서비스에 도달하는 방식을 확인합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.