dbt Projects on Snowflake 의존성 이해하기

dbt Projects on Snowflake에서 dbt 의존성은 packages.yml 파일에 선언하는 패키지예요(예: 시작하기 튜토리얼에서 배우는 dbt-labs/dbt_utils). dbt deps를 실행하면 dbt Core에서와 마찬가지로 이 패키지들이 dbt_packages 폴더에 설치돼요.

📌 이 페이지에서 설명하는 일부 기능은 가변 live 버전을 사용하는 dbt 프로젝트 객체가 필요해요. live 버전 객체를 얻으려면 2026_06 동작 변경 번들에 옵트인하거나, Snowflake 계정 담당자에게 별도의 단일 live 버전 기능을 활성화하도록 요청하세요. 그런 다음 객체를 생성하거나 교체하고, 기존 버전 객체는 SYSTEM$MIGRATE_DBT_PROJECT로 마이그레이션하세요. 자세한 내용은 dbt 프로젝트 객체의 단일 가변 live 버전으로의 마이그레이션 문서를 참조하세요.

출처: Snowflake 문서

본문

dbt deps는 Snowflake 워크스페이스, 배포 전 로컬 머신이나 Git 오케스트레이터, 또는 배포된 dbt 프로젝트 객체의 가변 live 버전을 대상으로 실행할 수 있어요. 배포된 객체에 대해 실행할 때는 WRITEBACK=TRUE를 사용해 설치되거나 업데이트된 패키지가 유지되도록 해요. 자세한 내용은 dbt deps 명령 실행에 대해 문서를 참조하세요.

dbt deps 명령 실행에 대해

dbt deps 명령은 다음 방식 중 하나로 실행할 수 있어요:

Snowflake 워크스페이스에서: (dev 환경에 권장.) dbt Project를 DBT PROJECT 객체로 배포하기 전에 Snowsight의 워크스페이스 안에서 dbt deps 명령을 실행해 dbt_packages를 채울 수 있어요. 이는 Snowflake가 의존성의 저장소에 접근할 수 있도록 외부 네트워크 접근이 필요해요. 자세한 내용은 dbt 의존성용 Snowflake 외부 접근 통합 생성 문서를 참조하세요.
Snowflake 밖에서: (예: 배포 파이프라인의 빌드 단계.) 로컬 머신이나 지속적 통합(CI)에서 dbt deps 명령을 실행해 dbt_packages에 패키지를 다운로드한 다음, 전체 프로젝트(그 폴더 포함)를 Snowflake로 배포할 수 있어요. 모든 의존성이 이미 dbt 프로젝트에 포함되어 있으므로 외부 네트워크 접근 통합이 필요하지 않아요.
배포된 dbt 프로젝트 객체에서: 가변 live 버전을 대상으로 deps 명령을 실행할 수 있어요. 생성된 dbt_packages 폴더와 package-lock.yml이 live 버전에 유지되도록 WRITEBACK = TRUE로 설정해요: EXECUTE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project ARGS = 'deps' WRITEBACK = TRUE;. 외부 패키지는 외부 접근 통합이 필요해요. 자세한 내용은 dbt 의존성용 Snowflake 외부 접근 통합 생성 및 EXECUTE DBT PROJECT 문서를 참조하세요.

dbt Fusion 엔진을 사용한다면, Fusion은 packages.yml에 의존성이 나열되어 있지만 dbt_packages 폴더가 없을 때 dbt deps를 자동으로 실행한다는 점에 유의하세요. 이는 dbt compile과 dbt run 같은 명령 중에 암시적으로 일어나요. 외부 접근 통합이 구성되지 않으면 이 암시적 실행은 네트워크 접근 오류로 실패해요. 이를 해결하려면: 워크스페이스에서 작업 중이라면 먼저 dbt deps를 수동으로 실행해 dbt_packages를 채우세요. 프로젝트를 배포한다면 프로젝트 객체에 외부 접근 통합을 설정해 컴파일 중 dbt deps가 자동으로 실행되게 하세요. 자세한 내용은 dbt 의존성용 Snowflake 외부 접근 통합 생성 문서를 참조하세요.

교차 dbt 프로젝트 의존성(Cross dbt project dependencies)

dbt 프로젝트 안에서 다른 dbt 프로젝트를 참조하려면 참조되는 dbt 프로젝트를 dbt 프로젝트의 루트로 복사해야 해요. Snowflake는 같은 폴더 안의 참조만 지원해요. 예를 들어 :local:../some_other_project는 지원되지 않아요.

로컬 의존성은 외부 접근 통합이 필요 없지만, 로컬 패키지와 원격 패키지(예: dbt Packages hub 또는 Git에서)를 섞어 써야 한다면 실제 외부 접근 통합을 구성해야 해요.

예를 들어 다음 두 dbt 프로젝트를 생각해 보세요. core_project가 metrics_project를 로컬로 포함해 Snowflake에 배포할 때 모든 것이 자체 포함(self-contained)되길 원해요(외부 접근 불필요).

/Projects
├─ core_project/
│   ├─ dbt_project.yml
│   ├─ packages.yml
│   ├─ models/
│   └─ ...
└─ metrics_project/
    ├─ dbt_project.yml
    ├─ models/
    └─ ...

core_project: 배포할 메인 프로젝트예요.
metrics_project: 로컬 의존성으로 사용할 프로젝트예요.

core_project 안에서 metrics_project를 참조하려면 다음 단계를 완료하세요:

core_project 안에 local_packages라는 폴더를 만들어요. metrics_project를 이 폴더로 복사해요. metrics_project의 dbt_project.yml에 있는 이름이 core_project와 달라야 해요. 고유해야 해요.

cd /Projects/core_project
mkdir local_packages
cp -R ../metrics_project ./local_packages/metrics_project

이제 레이아웃은 이렇게 보여요:

core_project/
├─ dbt_project.yml
├─ packages.yml
├─ models/
├─ local_packages/
│   └─ metrics_project/
│       ├─ dbt_project.yml
│       ├─ models/
│       └─ ...

core_project/packages.yml에서 상대 경로로 로컬 의존성을 선언해요.

packages:
  - local: local_packages/metrics_project

core_project 안에서 dbt deps를 실행해요. 이제 dbt는 metrics_project를 패키지로 취급하며 metrics_project의 매크로를 core_project에서 사용할 수 있어요.

배포 중 자동으로 dbt deps 실행

dbt 프로젝트 객체를 배포하거나 업데이트할 때 외부 접근 통합을 지정하면 Snowflake가 배포 중(dbt compile 전에) dbt deps를 자동으로 실행해 그 단계의 일부로 의존성을 설치해요. 즉, 외부 의존성이 있는 프로젝트를 배포할 때 더 이상 /dbt_packages를 포함할 필요가 없어요.

워크스페이스에서 dbt 프로젝트 객체를 Snowflake 데이터베이스와 스키마로 배포할 때, 이전에 만든 객체를 생성하거나 업데이트할 수 있어요.

Snowsight에 로그인해요.
탐색 메뉴에서 Projects » Workspaces를 선택해요.
Workspaces 메뉴에서 dbt 프로젝트가 포함된 워크스페이스를 선택해요.
워크스페이스 편집기 오른쪽에서 Connect » Deploy dbt project를 선택해요.
Deploy dbt project 팝업 창에서 다음을 선택해요: Select location 아래에서 데이터베이스와 스키마를 선택해요. Select or Create dbt project 아래에서 Create dbt project를 선택해요. 이름과 설명을 입력해요. 선택적으로 컴파일과 이후 실행에 사용할 프로필을 고르는 기본 target을 입력해요(예: prod). dbt 프로젝트 객체 실행의 target은 여전히 ARGS의 --target으로 재정의할 수 있어요. 선택적으로 Run dbt deps를 선택한 다음 외부 접근 통합을 선택해 배포 중 dbt deps를 자동으로 실행해요.
Deploy를 선택해요.

Output 탭에 Snowflake에서 실행되는 명령이 표시되는데, 다음 예시와 유사해요:

CREATE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  FROM 'snow://workspace/user$.public."my_workspace_name"/versions/live'
  DEFAULT_TARGET = 'prod'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_dbt_ext_access);

my_dbt_project successfully created.

이제 Connect 메뉴에 생성한 dbt 프로젝트 객체의 이름이 다음 옵션과 함께 표시돼요:

Redeploy dbt project: ALTER DBT PROJECT ... DEPLOY를 사용해 프로젝트의 현재 워크스페이스 버전으로 dbt 프로젝트 객체를 업데이트해요. 이는 객체의 가변 live 버전을 단일 작업으로 교체해요. 자세한 내용은 dbt 프로젝트 객체가 업데이트되는 방식 문서를 참조하세요.
Disconnect: 워크스페이스와 dbt 프로젝트 객체의 연결을 끊지만 dbt 프로젝트 객체는 삭제하지 않아요.
Edit project: dbt 프로젝트 객체의 comment, default target, 외부 접근 통합을 업데이트해요.
View project: 객체 탐색기에서 dbt 프로젝트 객체를 열어 dbt 프로젝트 객체의 CREATE DBT PROJECT 명령과 프로젝트의 실행 기록을 볼 수 있어요.
Create schedule: dbt 프로젝트 객체를 스케줄에 따라 실행하는 태스크를 만드는 옵션을 제공해요. 자세한 내용은 Snowflake에서 dbt 프로젝트 객체 실행 스케줄링 문서를 참조하세요.
View schedules: dbt 프로젝트 객체를 실행하는 스케줄(태스크) 목록을 열고, 객체 탐색기에서 태스크 세부 정보를 볼 수 있는 옵션을 제공해요.

배포 중 dbt deps를 자동 실행하려면 다음 예시처럼 EXTERNAL_ACCESS_INTEGRATIONS 매개 변수와 함께 CREATE DBT PROJECT 또는 ALTER DBT PROJECT 명령을 실행해요.

AUTO_COMPILE=TRUE면 Snowflake가 배포 중 dbt compile을 실행해요. 외부 접근 통합이 구성되면 Snowflake가 먼저 dbt deps를 실행한 다음 dbt compile을 실행해요. AUTO_COMPILE=FALSE로 설정하면 두 명령을 모두 건너뛰어요.

사용 사례에 따라 EXTERNAL_ACCESS_INTEGRATIONS 매개 변수에 빈 배열을 전달하거나 하나 이상의 외부 접근 통합을 지정할 수 있어요. 로컬 의존성은 외부 접근 통합이 필요 없지만, 로컬 패키지와 원격 패키지(예: dbt Packages hub 또는 Git)를 섞어 써야 한다면 실제 외부 접근 통합을 구성해야 해요.

-- 원격 패키지용으로 배포 중 dbt deps를 실행하는 dbt 프로젝트 객체 생성
CREATE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  FROM 'snow://workspace/user$.public."my_workspace_name"/versions/live'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_dbt_ext_access);

-- 로컬 의존성만을 위해 배포 중 dbt deps를 실행하는 dbt 프로젝트 객체 생성
CREATE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  FROM 'snow://workspace/user$.public."my_workspace_name"/versions/live'
  EXTERNAL_ACCESS_INTEGRATIONS = ();

-- 최신 코드를 가져오도록 Git 저장소 객체 업데이트
ALTER GIT REPOSITORY mydb.dev_schema.my_dbt_git_stage FETCH;

-- 외부 접근 통합 설정
ALTER DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  SET EXTERNAL_ACCESS_INTEGRATIONS = (my_dbt_ext_access);

-- 업데이트된 Git 저장소 파일을 live 버전으로 배포
-- 외부 접근 통합 설정 후, 배포는 dbt deps를 실행한 다음 dbt compile을 실행합니다
ALTER DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  DEPLOY FROM '@mydb.dev_schema.my_dbt_git_stage/branches/main/sales_dbt_project';

배포 중 dbt deps를 자동 실행하려면 다음 예시처럼 --external-access-integration 또는 --install-local-deps 플래그와 함께 snow dbt deploy 명령을 실행해요.

기본적으로 Snowflake는 배포 중 dbt compile을 실행해요. 외부 접근 통합이 구성되면 Snowflake가 먼저 dbt deps를 실행한 다음 dbt compile을 실행해요. 두 명령을 건너뛰려면 --no-auto-compile을 전달하세요.

--install-local-deps 플래그는 빈 외부 접근 통합을 가진 객체를 생성해요. 배포 중에 dbt deps를 실행하고 dbt_packages 폴더의 이전 상태를 교체해요.

--external-access-integration 플래그는 외부 접근 통합을 추가하며, --install-local-deps 플래그보다 우선해요.

snow dbt deploy my_dbt_project --install-local-deps;

dbt 의존성용 Snowflake 외부 접근 통합 생성

워크스페이스에서 dbt 명령을 실행할 때 dbt가 원격 URL에 접근해 의존성을 다운로드해야 할 수 있어요. 예를 들어 dbt가 dbt Package hub나 GitHub에서 패키지를 다운로드해야 할 수 있어요.

대부분의 dbt 프로젝트는 packages.yml 파일에 의존성을 지정해요. 배포 전에 워크스페이스, 로컬, 또는 CI에서 그 의존성을 설치할 수 있어요.

원격 URL에서 dbt 패키지를 가져오려면 Snowflake에 다음 예시처럼 네트워크 규칙에 의존하는 외부 접근 통합이 필요해요. 네트워크 규칙과 외부 접근 통합을 만드는 것은 일회성 관리 작업(admin operation)이에요. 그 후 dbt를 실행하는 역할에 통합에 대한 USAGE를 부여해요. 엔지니어는 필요할 때마다 선택할 수 있어요.

-- 외부 접근 통합용 NETWORK RULE 생성
CREATE OR REPLACE NETWORK RULE my_dbt_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  -- dbt deps에 필요한 최소 URL 허용 목록
  VALUE_LIST = (
    'hub.getdbt.com',
    'codeload.github.com'
  );

-- 외부 dbt 패키지 위치에 대한 dbt 접근용 EXTERNAL ACCESS INTEGRATION 생성
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_dbt_ext_access
  ALLOWED_NETWORK_RULES = (my_dbt_network_rule)
  ENABLED = TRUE;

-- 데이터 엔지니어가 통합을 선택하고 사용할 수 있도록 USAGE 부여
GRANT USAGE ON INTEGRATION my_dbt_ext_access TO ROLE data_engineer;

Snowflake의 외부 접근 통합에 대한 자세한 내용은 외부 접근 통합 생성 및 사용 문서를 참조하세요.

dbt 의존성의 제한 사항, 요구 사항, 고려 사항

다음 요구 사항, 고려 사항, 제한 사항은 dbt Projects on Snowflake에서 dbt 프로젝트의 dbt 의존성에 적용돼요:

packages.yml 파일에 공개 Git 패키지를 지정할 수 있어요. 모범 사례로 Snowflake는 비공개 Git 패키지는 안전하게 저장된 경우에만 사용할 것을 권장해요. 암호화되지 않은 Git 토큰을 임베드하는 것은 권장하지 않아요. 비공개 Git 패키지를 안전하게 인증하려면 토큰을 Snowflake 시크릿(secret)에 저장하고 env.yml 파일에서 DBT_ENV_SECRET_ 변수로 참조하세요. 자세한 내용은 dbt Projects on Snowflake용 SQL 환경 변수와 비공개 Git 패키지 사용 문서를 참조하세요.
Snowflake가 의존성의 저장소에 접근할 수 있도록 네트워크 규칙과 외부 접근 통합이 필요해요. 자세한 내용은 dbt 의존성용 Snowflake 외부 접근 통합 생성 문서를 참조하세요.
AUTO_COMPILE = TRUE면 Snowflake가 배포 중 dbt compile을 실행해요. 외부 접근 통합이 구성되면 Snowflake가 먼저 dbt deps를 실행한 다음 dbt compile을 실행해요. 자동 컴파일 중에는 생성된 dbt_packages 폴더, package-lock.yml, 컴파일된 아티팩트가 WRITEBACK 설정과 관계없이 live 버전에 유지돼요. 이후 deps 실행에서는 WRITEBACK이 업데이트된 의존성 파일이 live 버전에 유지될지 제어해요.
Snowflake는 같은 폴더 안의 다른 dbt 프로젝트 참조만 지원해요. 예를 들어 :local:../some_other_project는 지원되지 않아요. 해결 방법은 교차 dbt 프로젝트 의존성 문서를 참조하세요.
dbt Fusion과 암시적 dbt deps: dbt Fusion 엔진을 사용할 때 packages.yml에 의존성이 나열되어 있지만 dbt_packages 폴더가 없으면 Fusion이 dbt compile이나 dbt run 같은 명령 중에 dbt deps를 자동으로 실행해요. 이것이 Snowflake가 모든 dbt 명령에 외부 접근 통합 옵션을 표시하는 이유예요. 예상치 못한 네트워크 접근 오류가 발생하면: 워크스페이스에서 먼저 dbt deps를 수동으로 실행해 dbt_packages를 미리 채우세요. 배포할 때는 컴파일 중 dbt deps가 자동 실행되도록 프로젝트 객체에 외부 접근 통합을 설정하세요.

dbt Projects on Snowflake 의존성 이해하기