dbt 프로젝트 객체 배포

dbt Projects on Snowflake에서 dbt 프로젝트 객체를 배포한다는 것은 dbt 프로젝트 코드를 Snowflake로 복사해 단일 작업으로 객체를 생성하거나 그 live 버전을 교체한다는 뜻이에요. Snowflake CLI의 snow dbt deploy 명령, Snowsight, 또는 CREATE DBT PROJECT 및 ALTER DBT PROJECT ... DEPLOY SQL 명령으로 배포할 수 있어요.

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

출처: Snowflake 문서

본문

Snowflake CLI로 dbt 프로젝트 객체 배포

이것은 dbt 프로젝트 객체 배포에 권장되는 방식이에요. CI/CD 파이프라인에서 Snowflake CLI를 사용하세요. 설정부터 배포까지의 전체 워크스루는 dbt Projects on Snowflake에서 CI/CD 통합 설정 튜토리얼을 참조하세요.

snow dbt deploy 명령은 로컬 파일을 임시 스테이지에 업로드하고 단일 작업으로 새 dbt 프로젝트 객체를 생성하거나 기존 객체의 live 버전을 업데이트해요. 유효한 dbt 프로젝트에는 dbt_project.yml과 지원되는 프로필 파일 중 하나가 포함되어야 해요:

dbt_project.yml: 사용할 프로필을 지정하는 표준 dbt 구성 파일.
dbt_projects_profiles.yml 또는 profiles.yml: dbt_project.yml에서 참조하는 dbt 연결 프로필 정의. 선택된 프로필 파일은 database, role, schema, type을 정의해야 해요. 두 파일이 모두 있으면 Snowflake는 배포·컴파일·이후 명령 중에 dbt_projects_profiles.yml을 사용하고 profiles.yml을 무시해요. 기본적으로 dbt Projects on Snowflake는 dbt 환경이나 프로필에서 지정한 target 스키마(target.schema)를 사용해요. dbt 프로젝트 객체를 실행하면 dbt는 dbt_projects_profiles.yml 또는 profiles.yml에 지정된 target 스키마가 아직 없으면 만들려고 시도해요. 자세한 내용은 스키마 생성과 커스터마이징 이해 문서를 참조하세요.

<profile_name>:
  target: dev
  outputs:
    dev:
      database: <database_name>
      role: <role_name>
      schema: <schema_name>
      warehouse: <warehouse_name>
      type: snowflake

다음 예시는 snow dbt deploy 명령을 사용하는 방법을 보여줘요.

⚠️ 의도적으로 dbt 프로젝트 객체를 다시 만들려는 게 아니라면 --force를 사용하지 마세요. snow dbt deploy의 --force는 CREATE OR REPLACE DBT PROJECT를 실행하며, 이는 실행 기록을 제거할 수 있어요.

jaffle_shop이라는 dbt 프로젝트 객체 배포: snow dbt deploy jaffle_shop
지정된 디렉터리에서 jaffle_shop 프로젝트를 배포하되, 별도 디렉터리의 프로필 파일을 사용. CLI는 dbt_projects_profiles.yml을 먼저 찾고 없다면 profiles.yml만 사용해요. CLI는 이 파일을 배포된 프로젝트 객체의 루트에 같은 파일 이름으로 복사하며, 그 위치의 같은 이름 파일을 덮어써요: snow dbt deploy jaffle_shop --source /path/to/dbt/directory --profiles-dir ~/my_profiles/
지정된 디렉터리에서 jaffle_shop 프로젝트를 배포하되, 프로젝트 밖 폴더의 프로필 파일을 제공하고, 기본 target을 설정하고, dbt 버전을 고정(pin)하고, 외부 접근 통합을 활성화: snow dbt deploy jaffle_shop --source /path/to/dbt/directory --profiles-dir ~/my_profiles/ --default-target prod --dbt-version 1.11.11 --external-access-integration dbthub-integration --external-access-integration github-integration
jaffle_shop 프로젝트를 배포하고 특정 dbt 런타임 버전 설정: snow dbt deploy jaffle_shop --dbt-version '1.11.11'

Snowsight로 dbt 프로젝트 객체 배포

Snowsight에서 dbt 프로젝트 객체를 배포하면 워크스페이스의 dbt 코드를 가져와 새 dbt 프로젝트 객체를 생성하거나 기존 객체를 업데이트해요.

Snowsight에서 dbt 프로젝트 객체를 배포하려면 다음 단계를 따르세요:

Snowsight에 로그인해요.
탐색 메뉴에서 Projects » Workspaces를 선택해요.
Workspaces 메뉴에서 dbt 프로젝트가 포함된 워크스페이스를 선택해요.
선택적으로 dbt deps 명령을 실행해 프로젝트 의존성을 가져와요.
dbt 파일이 제자리에 있는지 확인해요. 작동을 확인하려면 다음과 같이 dbt compile, dbt run, 또는 dbt build 명령을 실행해요: 워크스페이스 편집기 아래에서 Output 탭을 열어 워크스페이스에서 dbt 명령을 실행한 후 stdout을 볼 수 있게 해요. 워크스페이스 편집기 위의 메뉴 바에서 올바른 Project와 Profile이 선택됐는지 확인해요. 명령 목록에서 dbt compile, dbt run, 또는 dbt build를 선택한 다음 실행 버튼을 선택해요. 이 단계는 프로젝트를 파싱해요.
워크스페이스 오른쪽 상단에서 Connect를 선택한 다음 다음 중 하나를 선택해요: Deploy dbt project로 새 dbt 프로젝트를 연결해요. 첫 배포에서 이는 스키마 수준 dbt 프로젝트 객체를 생성해요. Existing dbt deployment로 기존 dbt 프로젝트에 연결해요. 배포는 기존 dbt 프로젝트 객체의 live 버전을 단일 작업으로 업데이트해요(ALTER DBT PROJECT ... DEPLOY FROM 'snow://workspace/.../versions/live'와 동일).
Deploy dbt project 팝업 창에서 다음을 선택해요: Select location 아래에서 데이터베이스와 스키마를 선택해요. Select or Create dbt project 아래에서 Create dbt project를 선택해요. 이름과 설명을 입력해요. 선택적으로 컴파일과 이후 실행에 사용할 프로필을 고르는 기본 target을 입력해요(예: prod). dbt 프로젝트 객체 실행의 target은 여전히 ARGS의 --target으로 재정의할 수 있어요. 선택적으로 Run dbt deps를 선택한 다음 외부 접근 통합을 선택해 배포 중 dbt deps를 자동으로 실행하게 해요. 또는 배포 전에 워크스페이스 내에서 dbt deps를 실행해 추가 단계 없이 dbt_packages 폴더가 포함되도록 할 수 있어요.
Deploy를 선택해요. Output 탭에 Snowflake에서 실행되는 명령이 표시되는데, 다음 예시와 유사해요: CREATE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project FROM 'snow://workspace/USER$.PUBLIC."my_workspace"/versions/live' EXTERNAL_ACCESS_INTEGRATIONS = (); my_dbt_project successfully created. 이제 Connect 메뉴에 생성한 dbt 프로젝트 객체의 이름이 다음 옵션과 함께 표시돼요: Redeploy dbt project: ALTER DBT PROJECT ... DEPLOY를 사용해 dbt 프로젝트 객체의 live 버전을 현재 워크스페이스 내용으로 단일 작업으로 교체해요. 자세한 내용은 dbt 프로젝트 객체와 파일의 live 버전 문서를 참조하세요. Disconnect: 워크스페이스와 dbt 프로젝트 객체의 연결을 끊지만 dbt 프로젝트 객체는 삭제하지 않아요. Edit project: dbt 프로젝트 객체의 comment, default target, 외부 접근 통합을 업데이트해요. View project: 객체 탐색기에서 dbt 프로젝트 객체를 열어 dbt 프로젝트 객체의 CREATE DBT PROJECT 명령과 프로젝트의 실행 기록을 볼 수 있어요. Create schedule: dbt 프로젝트 객체를 스케줄에 따라 실행하는 태스크를 만드는 옵션을 제공해요. 자세한 내용은 Snowflake에서 dbt 프로젝트 객체 실행 스케줄링 문서를 참조하세요. View schedules: dbt 프로젝트 객체를 실행하는 스케줄(태스크) 목록을 열고, 객체 탐색기에서 태스크 세부 정보를 볼 수 있는 옵션을 제공해요.
선택적으로 워크시트에서 SHOW DBT PROJECTS 명령을 실행해 dbt 프로젝트 객체가 존재하는지 확인해요. 예: SHOW DBT PROJECTS IN DATABASE mydb;

SQL 명령으로 dbt 프로젝트 객체 배포

CREATE DBT PROJECT와 ALTER DBT PROJECT 명령은 문의 FROM 절에 지정된 파일을 복사해 각각 dbt 프로젝트 객체를 생성하거나 그 live 버전을 업데이트해요.

⚠️ SQL 명령으로 Git 저장소 스테이지에서 직접 배포하면 CI/CD 검증을 우회해요. 변경이 프로덕션에 도달하기 전에 풀 리퀘스트 검토나 테스트가 실행되지 않아요. 이 명령들은 개발과 테스트용으로만 사용할 것을 권장해요. 프로덕션 배포에 대한 종합 가이드는 dbt Projects on Snowflake에서 CI/CD 통합 설정 튜토리얼을 참조하세요.

CREATE DBT PROJECT 명령은 아래와 같이 live라는 가변 버전을 가진 새 객체를 생성해요.

CREATE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  FROM '@sales_db.integrations_schema.sales_dbt_git_stage/branches/main'
  DEFAULT_TARGET = 'prod'
  EXTERNAL_ACCESS_INTEGRATIONS = my_dbt_ext_access
  COMMENT = 'Generates sales data models.';

ALTER DBT PROJECT 명령은 live 버전의 전체 파일 집합을 단일 작업으로 교체해요.

ALTER DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  DEPLOY FROM '@sales_db.integrations_schema.sales_dbt_git_stage/branches/main/sales_dbt_project';

소스 파일 위치

dbt 프로젝트 객체의 소스 파일은 다음 위치 중 하나에 둘 수 있어요:

내부 명명 스테이지(internal named stage): 예: '@my_db.my_schema.my_internal_named_stage/path/to/dbt_projects_or_projects_parent'. 내부 사용자 스테이지와 테이블 스테이지는 지원되지 않아요.
dbt 워크스페이스: 예: 'snow://workspace/user$.public."my_workspace_name"/versions/live'. 워크스페이스 URI는 versions/live를 사용하며, 이는 워크스페이스의 활성 작업 상태를 가리켜요. 워크스페이스 이름은 대소문자를 구분하고 특수 문자를 포함할 수 있으므로 큰따옴표로 감싸는 것을 권장해요.
기존 dbt 프로젝트 스테이지: 예: 'snow://dbt/my_db.my_schema.my_existing_dbt_project_object/versions/live'. 버전 지정자는 필수이며 live예요.
Git 저장소 스테이지: 예: '@my_db.my_schema.my_git_repository_stage/branches/my_branch/path/to/dbt_project_or_projects_parent'. Git 저장소 객체와 스테이지를 만들고 관리하는 방법은 Snowflake에서 Git 저장소 사용 및 CREATE GIT REPOSITORY 문서를 참조하세요.

dbt 프로젝트 객체 배포