dbt Core에서 dbt Projects on Snowflake로 마이그레이션하기

dbt Core에서 dbt Projects on Snowflake로 마이그레이션하기

이 가이드는 표준 dbt Core에서 dbt Projects on Snowflake로 전환하는 팀을 위한 단계별 안내예요. 목표는 오늘 실행 중인 dbt Core 프로젝트(로컬 IDE에서 실행하고, Airflow 같은 오케스트레이터가 시작하는 프로젝트)를 가능한 한 적은 변경으로 Snowflake 안에서 네이티브로 실행되게 하는 거예요. 프로젝트 파일의 대부분은 그대로 유지돼요.

설정 단계에는 관리자 역할이 필요해요. 각 단계는 복사해 붙여넣을 수 있는 SQL을 보여주고, 가능한 곳에는 Snowsight에서의 동일한 클릭도 보여줘요.

출처: Snowflake 문서

본문

무엇이 바뀌고 무엇이 바뀌지 않는가

먼저 좋은 소식: models/, seeds/, macros/, tests/, dbt_project.yml, packages.yml 파일은 바꿀 필요가 없어요. dbt는 여전히 dbt예요.

dbt가 Snowflake 안에서 실행될 때 달라지는 것의 짧은 목록이에요:

주제	오늘의 dbt Core	dbt Projects on Snowflake
편집·실행 위치	로컬 IDE + 터미널	Snowflake Workspaces (Snowsight의 웹 IDE) 또는 Cortex Code Desktop
실행 실행기	Airflow 같은 제3자 오케스트레이터	Snowflake 태스크 (스케줄된 SQL)
연결 / 인증	account, user, password가 있는 profiles.yml	프로젝트 루트의 dbt_projects_profiles.yml 또는 profiles.yml, account, user, password 불필요
dbt 엔진	설치한 것	Snowflake 관리 런타임 선택. 예: 1.11.11(dbt Core) 또는 2.0.0-preview.186(dbt Fusion). 설치 불필요.
패키지 가져오기 (dbt deps)	로컬에서 실행	외부 접근 통합을 사용해 Snowflake에서 실행
배포	n/a	Snowflake에 가변 live 버전 하나를 가진 dbt 프로젝트 객체

이 가이드가 안내하는 일곱 단계:

1. Workspaces 설정 (및 dbt 런타임 선택)
2. (선택) Git 서버에 PrivateLink 설정
3. OAuth2로 Git 저장소 연결
4. 프로필 파일을 프로젝트 루트로 이동
5. 외부 접근 통합 생성(일회성) 및 데이터 엔지니어에게 USAGE 부여
6. 환경 변수 마이그레이션
7. 프로젝트 배포 및 태스크로 스케줄링

Git 연결을 위해 2단계와 3단계가 두 가지 인증 선택을 다뤄요: 모든 공급자에 대한 대화형 개발용 OAuth2(권장), 또는 PrivateLink를 사용하거나 자동화된 접근을 설정할 때의 개인 접근 토큰.

관련 문서:

• dbt Projects on Snowflake 개요
• dbt Projects on Snowflake 시작하기 튜토리얼
• dbt Projects 접근 제어

1단계: Workspaces 설정

Workspaces는 Snowsight 안의 웹 기반 IDE예요. dbt Core 프로젝트를 Snowflake에서 실행하는 가장 쉬운 방법이에요. 파일을 편집하고, dbt compile / dbt run / dbt build를 실행하고, DAG를 보고, 배포하는 것을 모두 브라우저에서 할 수 있어요. 로컬 설치가 필요 없어요.

관련 문서:

• dbt Projects on Snowflake용 Workspaces
• Workspaces 개요

dbt 런타임 버전 선택

Snowflake는 관리형 dbt 런타임에서 프로젝트를 실행해요. 선택한 버전이 엔진을 결정해요: 1.x 버전은 dbt Core(Python)를, 2.x 버전은 dbt Fusion(Rust)을 실행해요. 팀이 이미 경험 있는 버전에 고정하세요.

계정 전체 기본값을 설정해 아무도 매번 지정할 필요가 없게 할 수 있어요. 이는 또한 Workspaces가 사용하는 초기 런타임 버전을 설정해요:

-- 계정 수준 기본값 (관리자 역할 필요). Workspaces는 이를 초기 런타임으로 사용합니다.

-- dbt Core 1.11.11로 기본 설정하려면:
ALTER ACCOUNT SET DEFAULT_DBT_VERSION = '1.11.11';

-- 또는 dbt Fusion으로 기본 설정하려면:
ALTER ACCOUNT SET DEFAULT_DBT_VERSION = '2.0.0-preview.186';

언제든 사용 가능한 버전을 보려면:

SELECT SYSTEM$SUPPORTED_DBT_VERSIONS();

이후 개별 프로젝트에서 버전을 항상 재정의할 수 있어요(6단계에서 설명).

다른 dbt Core 프로젝트를 Fusion으로 옮겨야 한다면 dbt Fusion으로 마이그레이션 문서를 참조하세요.

관련 문서: 지원되는 dbt 버전

시작하기 전에 알아둘 점

Workspaces에서 사람들이 자주 걸려 넘어지는 몇 가지가 있어요:

• Workspaces는 기본적으로 개인임: 각 사용자의 워크스페이스는 자신의 개인 데이터베이스에 존재하며 공유되지 않아요. 여러 사람이 같은 워크스페이스에서 협업하려면 일반 데이터베이스와 스키마에 공유 워크스페이스를 만드세요. Workspaces 개요 문서를 참조하세요.
• dbt 프로젝트 객체를 배포할 때 100,000 파일 제한: 이 제한은 배포하는 개별 dbt 프로젝트 폴더에 적용되지, 워크스페이스 전체에는 적용되지 않아요. dbt가 생성하는 target/, dbt_packages/, logs/ 폴더를 포함한 그 폴더의 모든 것을 셉니다. 큰 패키지 트리가 있는 대형 프로젝트는 이 제한에 부딪힐 수 있어요. 팀의 프로젝트가 이 임계값보다 크다면 계정 담당자에게 문의하세요.
• 각 프로젝트 폴더에 dbt_projects_profiles.yml 또는 profiles.yml 파일이 필요함: (4단계에서 다룸.)
• 공개 저장소는 읽기 전용임: 공개 Git 저장소를 연결하면 pull은 할 수 있지만 워크스페이스에서 commit과 push는 할 수 없어요. 실제 프로젝트는 3단계에서 OAuth2로 비공개 저장소로 연결하세요.
• Fusion은 dbt deps를 자동으로 실행함: Fusion을 사용하고 packages.yml에 패키지가 나열되어 있는데 dbt_packages 폴더가 아직 없으면, Fusion은 dbt compile / dbt run 중에 조용히 dbt deps를 실행하며 인터넷 접근이 필요해요. Workspaces는 이를 간단하게 만들어요: 관리자가 외부 접근 통합을 한 번 만들고 역할에 USAGE를 부여해요(5단계). EAI를 선택하면 필요할 수 있는 모든 명령에 미리 선택된 상태로 유지되므로 다시 생각할 필요가 없어요.

2단계: (선택) Git 서버에 PrivateLink 설정

📌 Git 서버가 PrivateLink로만 접근 가능하지 않다면(공개 인터넷 접근 없음) 이 전체 단계를 건너뛰고 3단계로 가세요. 대부분의 팀은 공개 인터넷을 통해 Git 공급자에 연결하며 이 단계가 필요하지 않아요.

PrivateLink는 Snowflake와 Git 서버 사이의 전용 프라이빗 네트워크 연결이므로 Git 트래픽이 공개 인터넷을 거치지 않아요. 설정은 3단계에서 저장소를 연결하기 전에 완료해야 하는 일회성 관리 작업이며, Snowflake와 Git 서버가 같은 클라우드와 리전에 있을 때만 작동해요. PrivateLink에서는 OAuth2가 작동하지 않으므로 이 경로에서는 토큰으로 인증한다는 점에 유의하세요.

1. 클라우드 공급자에서 Snowflake의 요청을 받아들이는 private link 서비스(아래 링크된 워크스루 참조)를 만들어요.
2. Snowflake에서 private link 서비스 ID와 Git 서버의 도메인으로 아웃바운드 프라이빗 엔드포인트를 프로비저닝해요(AWS 예시; Azure와 Google Cloud는 자체 서비스 ID 형식을 사용): SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT('com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxx', -- your private link service ID 'git.example.com' -- your Git server domain);
3. 클라우드 공급자에서 엔드포인트를 수락한 다음 상태를 확인해요: SELECT SYSTEM$GET_PRIVATELINK_ENDPOINTS_INFO();
4. USE_PRIVATELINK_ENDPOINT = TRUE와 토큰 기반 인증(개인 접근 토큰을 담는 시크릿)으로 API 통합을 만들어요. 서버가 자체 서명 인증서를 사용한다면 TLS_TRUSTED_CERTIFICATES를 추가해요:

CREATE OR REPLACE SECRET git_pat_secret TYPE = password USERNAME = 'your-git-username' PASSWORD = 'your-personal-access-token';
CREATE OR REPLACE API INTEGRATION git_api_integration API_PROVIDER = git_https_api API_ALLOWED_PREFIXES = ('https://git.example.com/my-workspace') ALLOWED_AUTHENTICATION_SECRETS = (git_pat_secret) USE_PRIVATELINK_ENDPOINT = TRUE ENABLED = TRUE;

대부분의 공급자에서 USERNAME은 실제 Git 사용자 이름이에요. Bitbucket은 USERNAME을 문자열 x-token-auth(Bitbucket 관례)로 문자 그대로 설정하고 PASSWORD에 토큰을 넣어요:

-- Bitbucket 예시
CREATE OR REPLACE SECRET git_pat_secret TYPE = password USERNAME = 'x-token-auth' -- 리터럴 값, 사용자 이름이 아님 PASSWORD = 'your-bitbucket-access-token';

이 단계를 마친 후 3단계의 OAuth 옵션을 건너뛰고 바로 Git 연결 워크스페이스 생성으로 가세요. 각 개발자는 자신을 위해 이 워크스페이스 생성 단계를 반복해요: 인증 방법으로 Personal access token을 선택하고 시크릿을 가리켜요.

공유 토큰 또는 개발자별 토큰

위에서 만든 시크릿은 Git 사용자 이름 하나와 개인 접근 토큰 하나를 담으므로 단일 Git 신원을 나타내요. 팀이 Git 토큰을 어떻게 사용할지 결정하세요:

• 개발자별 시크릿 (개별 귀속): 개발자별 귀속과 개발자별 저장소 권한을 위해 각 개발자가 자신의 Git 사용자 이름과 개인 접근 토큰으로 자신의 시크릿을 만든 다음 워크스페이스를 그 시크릿에 연결해요. 워크스페이스 생성 대화 상자에서 Personal access token을 선택하고 시크릿을 고르거나 + Secret로 인라인 생성해요.
• 공유 시크릿 하나 (서비스 계정 모델): 시크릿에 READ가 있는 모든 사람이 그 하나의 신원으로, 그 신원의 저장소 권한으로 인증하고 push해요. Git 서버에서 push는 누가 Snowflake에서 실행했든 그 계정에 귀속돼요.

관리자는 여전히 API 통합을 한 번 만들어요. 개발자별인 것은 시크릿뿐이에요. 개발자별 시크릿을 사용한다면 각각을 ALLOWED_AUTHENTICATION_SECRETS에 나열하거나 ALL로 설정하세요.

📌 Workspaces에서 설정한 작성자(author) 이름과 이메일은 커밋 메타데이터만 바꿔요. 인증 신원은 바꾸지 않아요. 시크릿의 개인 접근 토큰이 여전히 push가 어떤 Git 계정으로 실행되는지 결정해요.

관련 문서:

• 프라이빗 네트워크를 통한 Git 저장소 연결

3단계: OAuth2로 Git 저장소 연결

Workspaces는 Git 저장소의 브랜치에 동기화하므로 평소의 Git 워크플로(브랜치, 커밋, 풀 리퀘스트)를 유지해요. 대화형 개발에 가장 깔끔한 로그인 경험은 OAuth2예요. 팀이 Git 공급자에 한 번 로그인하면 Snowflake가 나머지를 처리하고, 붙여넣거나 순환 교체할 토큰이 없어요.

OAuth2는 공개 인터넷을 통한 모든 지원 공급자에서 작동해요: GitHub, GitLab, Azure DevOps, Bitbucket Cloud, 그리고 다른 OAuth2 공급자. GitHub 전용 옵션이 아니에요. OAuth2 대신 개인 접근 토큰이 필요한 경우는 두 가지뿐이에요:

• Git 서버가 PrivateLink로만 접근 가능한 경우. 개인 링크로는 OAuth2가 작동하지 않으므로 토큰으로 인증해요(2단계 참조).
• 대화형 로그인을 완료할 사람이 없는 CI/CD 파이프라인 같은 비대화형 자동화 접근을 설정하는 경우.

📌 dbt Projects on Snowflake 온보딩 초기에 Workspaces를 사용할 의도가 없다면 이 섹션은 건너뛰어도 돼요. 팀은 여전히 Snowflake CLI(6단계에서 표시)를 사용해 dbt 프로젝트 객체를 배포하고 스케줄할 수 있어요.

설정은 두 부분으로 이뤄져요: 관리자가 Snowflake에 Git 공급자와 통신하는 방법을 알려주는 API 통합을 만들고, 각 사용자가 Git 연결 워크스페이스를 만들 때 OAuth로 로그인해요.

💡 2단계(PrivateLink)를 완료했다면 토큰 기반 API 통합을 이미 만들었어요. 아래 OAuth 옵션을 건너뛰고 바로 Git 연결 워크스페이스 생성으로 가세요.

리다이렉트 URI (GitHub를 제외한 모든 공급자에 필요)

대부분의 OAuth2 공급자는 OAuth 애플리케이션을 등록할 때 리다이렉트 URI(콜백 URL이라고도 함)를 요청해요. 이는 계정의 리전에 기반한 고정 Snowflake URL이에요. API 통합이 생성하는 것이 아니에요. 패턴은 다음과 같아요:

https://apps-api.c1.<region>.<cloud>.app.snowflake.com/oauth/complete-secret

예를 들어 AWS US West(Oregon)의 계정은 다음을 사용해요:

https://apps-api.c1.us-west-2.aws.app.snowflake.com/oauth/complete-secret

OAuth 앱을 만들 때 이 URL을 콜백으로 설정하고, 공급자가 주는 client ID와 client secret을 API 통합에 꽂아요. 아래 GitHub 옵션은 이를 건너뛰어요. Snowflake GitHub App이 리다이렉트 URI를 처리해요.

Snowflake가 전체 URL을 만들게 하려면 다음을 실행하고 결과를 복사해요:

SHOW REGIONS;

SELECT DISTINCT
  'https://apps-api.c1.' || "region" || '.' || "cloud" || '.app.snowflake.com/oauth/complete-secret'
  AS redirect_uri
FROM TABLE(RESULT_SCAN(LAST_QUERY_ID()))
WHERE "snowflake_region" = SPLIT_PART(CURRENT_REGION(), '.', -1);

Git 공급자용 API 통합 만들기

Git 공급자를 선택해 설정 단계를 보세요.

GitHub는 관리자 설정이 가장 적어요. 아래 탭의 모든 공급자는 같은 OAuth2 로그인 흐름을 사용하지만, GitHub는 OAuth 애플리케이션 등록과 리다이렉트 URI를 건너뛰어요. Snowflake가 사전 빌드된 OAuth 앱(Snowflake GitHub App)을 게시하므로 관리자는 그 앱을 가리키는 API 통합만 만들면 돼요:

-- 관리자 역할로 실행 (CREATE API INTEGRATION 필요).

CREATE OR REPLACE API INTEGRATION git_api_integration
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://github.com/my-org') -- your GitHub org or account URL
  API_USER_AUTHENTICATION = (TYPE = SNOWFLAKE_GITHUB_APP)
  ENABLED = TRUE;

첫 로그인 시 GitHub는 조직 관리자에게 snowflakedb 앱을 인가하도록 요청해요. 그 후 계정의 모든 사람이 사용할 수 있어요.

Snowflake GitHub App은 github.com/apps/snowflakedb에 있어요.

GitLab의 경우 GitLab 쪽에서 OAuth 애플리케이션을 등록한 다음 위에서 설명한 OAuth2 세부 정보로 Snowflake에 API 통합을 만들어요. (GitHub 외 공급자의 OAuth는 현재 프리뷰지만 완전히 사용 가능해요.) GitLab에 OAuth 애플리케이션을 등록하고 콜백 URL을 위에서 설명한 Snowflake 리다이렉트 URI로 설정해요. read_api, read_repository, write_repository 스코프를 요청해요. GitLab이 다음에 사용할 client ID와 client secret을 줘요. 그런 다음 API 통합을 만들어요(관리자 역할로 실행). 아래 엔드포인트는 GitLab.com용이고, 자체 관리 GitLab은 자체 호스트를 대체해요:

CREATE OR REPLACE API INTEGRATION git_api_integration
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://gitlab.com/my-group') -- your GitLab group or account URL
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH2
    OAUTH_AUTHORIZATION_ENDPOINT = 'https://gitlab.com/oauth/authorize'
    OAUTH_TOKEN_ENDPOINT = 'https://gitlab.com/oauth/token'
    OAUTH_CLIENT_ID = '<your_gitlab_client_id>'
    OAUTH_CLIENT_SECRET = '<your_gitlab_client_secret>'
    OAUTH_ACCESS_TOKEN_VALIDITY = 3600
    OAUTH_REFRESH_TOKEN_VALIDITY = 2592000
    OAUTH_ALLOWED_SCOPES = ('read_api', 'read_repository', 'write_repository')
  )
  ENABLED = TRUE;

Azure DevOps는 GitLab과 같은 일반 OAuth2 흐름을 사용해요. Azure DevOps에 OAuth 애플리케이션을 등록하고 콜백 URL을 위에서 설명한 Snowflake 리다이렉트 URI로 설정한 다음 Azure DevOps의 엔드포인트와 스코프로 API 통합을 만들어요. 그 값들이 공급자별이고(Microsoft가 Microsoft Entra ID로 전환 중), 정확한 현재 값은 Azure DevOps OAuth용 Snowflake quickstart에서 얻으세요.

CREATE OR REPLACE API INTEGRATION git_api_integration
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://dev.azure.com/my-organization') -- your Azure DevOps org URL
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH2
    OAUTH_AUTHORIZATION_ENDPOINT = '<azure_devops_authorization_endpoint>'
    OAUTH_TOKEN_ENDPOINT = '<azure_devops_token_endpoint>'
    OAUTH_CLIENT_ID = '<your_client_id>'
    OAUTH_CLIENT_SECRET = '<your_client_secret>'
    OAUTH_ACCESS_TOKEN_VALIDITY = 3600
    OAUTH_REFRESH_TOKEN_VALIDITY = 2592000
    OAUTH_ALLOWED_SCOPES = ('<azure_devops_scopes>')
  )
  ENABLED = TRUE;

Bitbucket의 Workspacesettings > OAuth consumers에서 Write repository 권한으로 OAuth consumer를 등록하고 콜백 URL을 위에서 설명한 Snowflake 리다이렉트 URI로 설정해요. Consumer의 Key와 Secret이 OAUTH_CLIENT_ID와 OAUTH_CLIENT_SECRET이에요. 스크린샷과 함께 완전한 단계별 안내는 OAuth2로 Snowflake를 Bitbucket에 연결 quickstart를 참조하세요.

CREATE OR REPLACE API INTEGRATION git_api_integration
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://bitbucket.org/my-workspace') -- your Bitbucket workspace URL
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH2
    OAUTH_AUTHORIZATION_ENDPOINT = 'https://bitbucket.org/site/oauth2/authorize'
    OAUTH_TOKEN_ENDPOINT = 'https://bitbucket.org/site/oauth2/access_token'
    OAUTH_CLIENT_ID = '<your-consumer-key>'
    OAUTH_CLIENT_SECRET = '<your-consumer-secret>'
    OAUTH_ACCESS_TOKEN_VALIDITY = 7200
    OAUTH_REFRESH_TOKEN_VALIDITY = 31536000
    OAUTH_ALLOWED_SCOPES = ('repository:write')
    OAUTH_USERNAME = 'x-token-auth' -- Bitbucket에 필요; 로그인 후 이게 없으면 Git 작업이 실패함
  )
  ENABLED = TRUE;

📌 Bitbucket이 아웃바운드 PrivateLink 뒤에 있나요? OAuth2는 Git 공급자로의 아웃바운드 프라이빗 링크에서는 지원되지 않아요. 이 옵션은 건너뛰고 토큰 기반 PrivateLink 단계(2단계)를 사용하세요. 이 옵션은 공개 인터넷으로 접근하는 Bitbucket Cloud용이에요.

OAuth2를 지원하는 다른 공급자(자체 관리 Git 서버 등)는 일반 템플릿을 사용해요. 공급자에 OAuth 애플리케이션을 등록하고 콜백 URL을 위에서 설명한 Snowflake 리다이렉트 URI로 설정한 다음 공급자의 엔드포인트, 클라이언트 자격 증명, 스코프를 채워요:

CREATE OR REPLACE API INTEGRATION git_api_integration
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://git.example.com/my-account') -- your provider/repo base URL
  API_USER_AUTHENTICATION = (
    TYPE = OAUTH2
    OAUTH_AUTHORIZATION_ENDPOINT = '<your_oauth_authorization_endpoint>'
    OAUTH_TOKEN_ENDPOINT = '<your_oauth_token_endpoint>'
    OAUTH_CLIENT_ID = '<your_client_id>'
    OAUTH_CLIENT_SECRET = '<your_client_secret>'
    OAUTH_ACCESS_TOKEN_VALIDITY = 3600
    OAUTH_REFRESH_TOKEN_VALIDITY = 2592000
    OAUTH_ALLOWED_SCOPES = ('<your_scopes>')
  )
  ENABLED = TRUE;

공급자별 값은 공급자별 Git 통합용 OAuth 설정 문서를 참조하세요.

Git 연결 워크스페이스 만들기

📌 관리자가 계정 전체에 대해 API 통합을 한 번 만들어요. 그 후 각 개발자가 아래 단계를 반복해 자신의 워크스페이스를 만들고 OAuth2로 로그인해요. GitHub의 경우 첫 로그인에서 조직 관리자가 snowflakedb 앱을 한 번 인가하도록 요청한 후 계정의 모든 사람이 로그인할 수 있어요.

API 통합이 생기면 그에 대한 USAGE가 있는 사람은 누구나 저장소에서 워크스페이스를 만들 수 있어요:

1. Snowsight에 로그인해요.
2. 탐색 메뉴에서 Projects > Workspaces를 선택해요.
3. Workspaces 메뉴에서 From Git repository를 선택해요.
4. 저장소 URL을 붙여넣어요(예: https://github.com/my-org/analytics 또는 https://gitlab.com/my-group/analytics).
5. 워크스페이스에 이름을 지정해요.
6. API Integration 아래에서 git_api_integration을 선택해요.
7. 인증 방법으로 OAuth2를 선택한 다음 Sign in하고 Snowflake가 저장소에 접근하도록 인가해요. pull과 push를 할 수 있도록 메타데이터에 대한 읽기 접근과 코드에 대한 읽기/쓰기 접근을 허용해요.
8. Create를 선택해요.

Snowflake가 저장소를 클론하고 편집할 준비가 된 dbt 프로젝트 파일로 워크스페이스를 열어요.

관련 문서:

• Git 설정 방법 선택
• OAuth 설정 세부 정보
• 워크스페이스를 Git에 연결
• CREATE API INTEGRATION

4단계: 프로필 파일을 프로젝트 루트로 이동

dbt Core에서 profiles.yml은 보통 프로젝트 밖(~/.dbt/)에 있고 account, user, password를 담아요. Snowflake에서는 그 파일을 dbt 프로젝트 폴더의 루트로 가져오고 민감한 부분을 뺀다.

더 단순한 이유: 프로젝트는 이미 Snowflake 안에서 로그인한 사용자와 계정으로 실행돼요. 그래서 dbt에 account, user, password가 필요 없어요. account와 user 키는 빈 문자열이나 자리표시자 문자열로 남겨둘 수 있고(dbt는 여전히 키가 존재할 것을 기대해요), password 필드는 아예 없어요.

하이브리드 팀(일부 구성원은 계속 로컬 dbt CLI를 쓰고 다른 구성원은 Workspaces를 쓰기 시작하려는 팀)에서는 dbt_projects_profiles.yml 파일을 사용할 것을 권장해요. 이 파일은 기존 개발 워크플로를 바꾸지 않고 dbt Projects on Snowflake를 채택하게 해줘요. 로컬 dbt CLI 실행은 이전처럼 프로젝트 밖의 ~/.dbt/profiles.yml을 계속 읽는 반면, 프로젝트 루트 안의 dbt_projects_profiles.yml은 Snowflake 관리 실행(Workspaces, Cortex Code Desktop Snowflake 관리 모드, dbt 프로젝트 객체)을 처리해요. 이렇게 하면 연결 설정을 바꾸지 않고 로컬 dbt와 Snowflake 관리 실행 사이를 오갈 수 있어요.

📌 프로젝트 루트에 두 파일이 모두 있으면 Snowflake는 Workspaces, Cortex Code Desktop(Snowflake 관리 모드), dbt 프로젝트 객체에서 dbt_projects_profiles.yml을 사용해요. dbt_projects_profiles.yml이 없으면 Snowflake는 이전처럼 profiles.yml을 사용해요.

여기에 넣을 수 있는 dbt_projects_profiles.yml 또는 profiles.yml이에요. dev와 prod target을 정의해요:

my_project:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: 'not needed' # Snowflake에서는 무시됨; 현재 계정으로 실행
      user: 'not needed'    # Snowflake에서는 무시됨; 현재 사용자로 실행
      role: transformer
      database: dev_db
      schema: analytics
      warehouse: dbt_wh
      threads: 8
    prod:
      type: snowflake
      account: 'not needed'
      user: 'not needed'
      role: transformer
      database: prod_db
      schema: analytics
      warehouse: dbt_wh
      threads: 8

password도, authenticator도, 키-페어 경로도 없어요. 그게 요점이에요. 파일에 민감한 것이 아무것도 없어요.

dbt_projects_profiles.yml 또는 profiles.yml이 프로젝트 루트에 유효한 target이 하나 이상 있는 상태로 있으면 각 target이 워크스페이스 툴바의 Profile 선택기에 나타나요. 프로필을 고르고 명령(compile, run, build)을 골라 실행해요.

관련 문서:

• 통합 개발-프로덕션 경험을 위한 dbt_projects_profiles.yml 사용
• dbt Projects on Snowflake용 Workspaces
• Cortex Code Desktop의 dbt 통합

5단계: dbt 패키지용 외부 접근 통합 만들기

프로젝트가 packages.yml의 패키지를 사용한다면(예: dbt-labs/dbt_utils), dbt는 dbt deps를 실행할 때 패키지를 다운로드하기 위해 인터넷에 접근해야 해요. Snowflake는 기본적으로 아웃바운드 네트워크 접근을 차단하므로 외부 접근 통합으로 좁고 허용 목록화된 경로를 dbt에 부여해요.

네트워크 규칙과 외부 접근 통합을 만드는 것은 계정의 일회성 관리 작업이에요. 그 후 관리자가 데이터 엔지니어링 역할에 통합에 대한 USAGE를 부여해요. 엔지니어는 그 후 dbt deps를 실행하거나 원격 패키지가 필요한 dbt 프로젝트 객체를 배포할 때마다 그 통합을 선택해요. 이 통합은 다시 만들 필요가 없어요.

이것은 Fusion에서 특히 중요해요: 앞서 언급한 함정에서처럼, Fusion은 패키지가 선언됐지만 아직 다운로드되지 않았을 때 컴파일/실행 중 dbt deps를 자동 실행해요. 외부 접근이 없으면 그 단계가 네트워크 오류로 실패해요. 한 번 설정하면 그 문제를 피할 수 있어요.

관리자 역할로 다음을 실행해요:

-- 1. dbt가 패키지를 다운로드하는 데 필요한 호스트를 허용 목록에 추가.
CREATE OR REPLACE NETWORK RULE dbt_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = (
    'hub.getdbt.com',    -- dbt Package hub
    'codeload.github.com' -- GitHub에 호스팅된 패키지
  );

-- 2. 규칙을 dbt가 사용할 수 있는 외부 접근 통합으로 감싸기.
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION dbt_ext_access
  ALLOWED_NETWORK_RULES = (dbt_network_rule)
  ENABLED = TRUE;

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

data_engineer를 팀이 Workspaces에서 dbt를 실행하거나 dbt 프로젝트 객체를 배포할 때 사용하는 역할로 바꾸세요. dbt deps를 실행하거나 배포 시 통합을 연결해야 하는 각 역할에 USAGE를 부여하세요. 통합은 한 번 만들고, 이후 새 역할 온보딩은 또 다른 GRANT일 뿐이에요.

워크스페이스에서 패키지를 채우려면 명령 목록에서 Deps를 선택하고 외부 접근 통합을 고른 다음 실행해요. 이렇게 하면 dbt_packages 폴더와 package-lock.yml이 생성돼요.

팀이 다른 호스트에서 패키지를 가져온다면(예: 비공개 Git 패키지 서버) 그 호스트 이름을 VALUE_LIST에 추가하세요.

관련 문서:

• dbt 의존성과 외부 접근
• 외부 네트워크 접근 개요

6단계: 환경 변수 마이그레이션

dbt Core 프로젝트가 모델, 매크로, 또는 profiles.yml에서 env_var()를 호출한다면 그 변수들을 프로젝트 루트의 env.yml 파일로 마이그레이션해요. Snowflake는 각 실행 전에 env.yml을 해결하고 값을 dbt에 주입해요. 모든 키는 대문자이고 DBT_ 접두사가 붙어야 해요.

1. 프로젝트에서 모든 env_var() 호출 스캔: CoCo에게 모델, 매크로, profiles.yml 전반에서 참조되는 모든 고유 환경 변수를 나열하라고 요청하세요.
2. env.yml 파일에 변수 추가: env.yml 파일 작성 문서의 env.yml 구문을 사용하세요. 어느 것을 하드코딩할지 정하는 동안 값은 "" 자리표시자로 설정하세요.
3. 각 변수를 DBT_ 접두사의 UPPERCASE로 이름 변경: 예를 들어 my_schema는 DBT_MY_SCHEMA가 돼요. 값은 그대로예요.
4. 프로젝트 파일에서 참조 업데이트: CoCo에게 모델, 매크로, profiles.yml 전반의 모든 env_var('OLD_NAME') 호출을 한 번에 env_var('DBT_OLD_NAME')으로 바꾸라고 요청하세요.

env.yml 작성, 환경 선택, 비공개 Git 패키지, 전체 참조에 대해서는 dbt Projects on Snowflake용 SQL 환경 변수와 비공개 Git 패키지 사용 문서를 참조하세요.

7단계: 프로젝트 배포 및 태스크로 스케줄링

프로젝트가 워크스페이스에서 깨끗하게 실행되면 dbt 프로젝트 객체를 만들어 '배송(shipping)'해요. 객체는 Snowflake 데이터베이스와 스키마에 프로젝트 파일의 가변 live 버전 하나를 가져요. 그런 다음 태스크로 스케줄해요(Airflow 작업을 대체).

dbt 프로젝트 객체로 배포

SQL 사용: CREATE DBT PROJECT가 코드를 복사하고 객체의 live 버전을 만들어요. FROM을 워크스페이스의 프로젝트 live 버전으로 지정해요. 배포 중 Fusion이 dbt deps를 실행할 수 있도록 5단계의 외부 접근 통합을 연결하고 Fusion 런타임을 고정해요:

CREATE OR REPLACE DBT PROJECT prod_db.analytics.my_dbt_project
  FROM 'snow://workspace/USER$.PUBLIC."my_dbt_workspace"/versions/live/my_dbt_project'
  DEFAULT_TARGET = 'prod'
  DBT_VERSION = '2.0.0-preview.186'
  EXTERNAL_ACCESS_INTEGRATIONS = (dbt_ext_access)
  COMMENT = 'Analytics dbt project';

📌 FROM URL은 워크스페이스의 live 버전을 가리켜요. 예시는 개인 워크스페이스(기본값)를 사용하며, 그 경로는 USER$.PUBLIC."<workspace_name>"이에요. 공유 워크스페이스를 사용한다면 USER$.PUBLIC을 객체가 있는 데이터베이스와 스키마(예: prod_db.analytics."<workspace_name>")로 바꾸세요. 마지막 세그먼트(my_dbt_project)는 워크스페이스 안의 dbt 프로젝트 폴더예요. 정확히 맞히는 가장 쉬운 방법은 UI에서 한 번 배포하고 출력되는 CREATE DBT PROJECT SQL을 복사하는 거예요.

존재를 확인해요:

SHOW DBT PROJECTS IN DATABASE prod_db;

객체를 교체하지 않고 live 버전을 업데이트하려면 ALTER DBT PROJECT ... DEPLOY를 실행해요:

ALTER DBT PROJECT prod_db.analytics.my_dbt_project
  DEPLOY FROM 'snow://workspace/USER$.PUBLIC."my_dbt_workspace"/versions/live/my_dbt_project';

UI 사용: 워크스페이스에서 Connect > Deploy dbt project를 선택하고 target 데이터베이스와 스키마를 고르고, Create dbt project를 선택하고 이름을 지정한 뒤, 선택적으로 기본 target과 외부 접근 통합을 설정하고 Deploy를 선택해요. Output 탭이 실행한 정확한 CREATE DBT PROJECT SQL을 보여주므로 UI와 SQL 경로가 같은 결과를 만들어요.

CI/CD: 손으로 배포하는 것은 시작하기에 올바른 방법이에요. 장기적으로는 GitHub Action이나 GitLab 파이프라인으로 구동되는 Snowflake CLI의 snow dbt 명령을 사용해 CI/CD 파이프라인을 통해 dbt 프로젝트 객체에 대한 업데이트를 관리할 것을 권장해요. 그 형태는 짧고 깔끔해요: 풀 리퀘스트 시 테스터 객체를 배포해 코드를 테스트하고, 머지 시 live 프로덕션 프로젝트를 업데이트해요.

# CI (각 풀 리퀘스트 시): dev에 복사본을 배포한 다음 실행 + 테스트
snow dbt deploy my_dbt_project --source ./my_dbt_project --database dev_db --schema analytics --external-access-integration dbt_ext_access
snow dbt execute my_dbt_project --database dev_db --schema analytics build --target dev

# CD (main에 머지 시): live 프로덕션 프로젝트 객체 업데이트
snow dbt deploy my_dbt_project --source ./my_dbt_project --database prod_db --schema analytics --external-access-integration dbt_ext_access

전체 설정(인증, 시크릿, 워크플로 파일)은 dbt Projects on Snowflake의 CI/CD 통합 및 CI/CD 튜토리얼을 참조하세요.

관련 문서:

• dbt 프로젝트 객체 배포
• CREATE DBT PROJECT
• ALTER DBT PROJECT

태스크로 스케줄링

태스크는 스케줄에 따라 EXECUTE DBT PROJECT 명령을 실행해요. Airflow를 대체하는 부분이에요. 기억할 두 규칙:

• 태스크는 dbt 프로젝트 객체와 같은 데이터베이스와 스키마에 있어야 해요.
• dbt를 실행하는 태스크는 사용자 관리 웨어하우스(user-managed warehouse)를 사용해야 해요(서버리스 태스크는 지원되지 않아요).

prod target에 대한 매일 실행:

CREATE OR ALTER TASK prod_db.analytics.run_dbt_project
  WAREHOUSE = dbt_wh
  SCHEDULE = 'USING CRON 0 6 * * * UTC' -- 매일 06:00 UTC
AS
  EXECUTE DBT PROJECT prod_db.analytics.my_dbt_project
    ARGS = 'run --target prod';

run이 끝난 직후 테스트 실행을 이어서 연결할 수 있어요:

CREATE OR ALTER TASK prod_db.analytics.test_dbt_project
  WAREHOUSE = dbt_wh
  AFTER prod_db.analytics.run_dbt_project
AS
  EXECUTE DBT PROJECT prod_db.analytics.my_dbt_project
    ARGS = 'test --target prod';

태스크는 일시 중단(suspended) 상태로 생성돼요. 스케줄을 시작하려면 다시 시작해요(자식 먼저, 그다음 루트):

ALTER TASK prod_db.analytics.test_dbt_project RESUME;
ALTER TASK prod_db.analytics.run_dbt_project RESUME;

언제든 단일 실행을 직접 할 수도 있어요:

EXECUTE DBT PROJECT prod_db.analytics.my_dbt_project
  ARGS = 'run --select my_model --target prod';

UI 사용: dbt 프로젝트 메뉴에서 Create schedule을 선택하고 주파수, 작업(run), 프로필, 그리고 어떤 플래그(예: --select customer_metrics)를 설정해요. Snowflake가 같은 CREATE TASK를 만들어줘요.

관련 문서:

• dbt 프로젝트 실행 스케줄링
• EXECUTE DBT PROJECT
• CREATE TASK
• 태스크 개요

다음으로 어디로 갈까

• 지원되는 dbt 명령과 플래그
• dbt Projects on Snowflake 모니터링
• dbt Projects on Snowflake 시작하기 튜토리얼

더 알아보기 (Learn more)

• dbt 프로젝트 객체 배포
• dbt 의존성 이해하기
• dbt Projects on Snowflake 개요