require-dbt-version

require-dbt-version

프로젝트가 특정 범위의 dbt 버전에서만 동작하도록 제한하는 설정이에요. 버전 범위는 따옴표로 감싼 문자열로 지정하며, 하한·상한을 함께 정의하는 것을 권장해요.

출처: 문서

본문

dbt_project.yml:

require-dbt-version: version-range | [version-range]

정의 (Definition)

require-dbt-version을 사용하면 프로젝트가 특정 범위의 dbt 버전에서만 동작하도록 제한할 수 있어요.

이 설정을 지정하면:

• dbt Packages 허브에서 설치한 패키지 중 일치하지 않는 require_dbt_version을 명시한 패키지가 있으면, dbt 명령 실행 시 에러가 발생해요.
• 패키지 관리자(예: dbt-utils)가 사용자의 dbt 버전이 패키지와 호환되는지 보장하도록 도와줘요.
• dbt v2(2.0.0 이상) 호환성을 나타내요.
• 전체 팀이 로컬 개발에서 동일한 dbt 버전을 유지해 변경된 동작으로 인한 호환성 문제를 피하는 데도 도움이 돼요.

메이저 릴리스로 고정(pin)해야 해요. 범위 고정에 대한 자세한 내용은 해당 항목을 참고하세요. 이 설정을 지정하지 않으면 버전 검사가 일어나지 않아요.

dbt 릴리스 트랙 (release tracks) — 2024년부터 dbt에서 릴리스 트랙을 선택해 지속적인 dbt 버전 업그레이드를 받으면, dbt는 require-dbt-version 설정을 무시해요.

dbt Labs는 dbt 프로젝트의 코드에 대해 제로 브레이킹 체인지를 약속하고 지속적으로 릴리스를 제공해요. 또한 다음 모범 사례도 권장해요.

dbt 패키지 설치하기 — 프로젝트에 사용할 dbt 패키지를 설치한다면(동료가 유지하든 오픈소스 dbt 커뮤니티 구성원이 유지하든), 패키지를 특정 리비전이나 버전 경계로 고정하는 것을 권장해요. dbt는 개발 중 패키지의 버전/리비전을 잠가 프로덕션에서 예측 가능한 빌드를 보장함으로써 이를 기본적으로 관리해요. 자세한 내용은 Predictable package installs 문서를 참고하세요.

dbt 패키지 유지하기 — dbt 패키지를 유지한다면(동료나 오픈소스 커뮤니티를 위해), 다른 필수 패키지와 전역 매크로가 있는지 확인하는 방어적 코드를 작성하는 것을 권장해요. 예를 들어 패키지가 전역 dbt 네임스페이스의 date_spine 매크로 가용성에 의존한다면 다음과 같이 작성할 수 있어요:

models/some_days.sql:

{% macro a_few_days_in_september() %}
  {% if not dbt.get('date_spine') %}
    {{ exceptions.raise_compiler_error("Expected to find the dbt.date_spine macro, but it could not be found") }}
  {% endif %}
  {{ date_spine("day", "cast('2020-01-01' as date)", "cast('2030-12-31' as date)") }}
{% endmacro %}

YAML quoting

이 설정은 YAML 파서가 문자열로 보간해야 해요. 따라서 설정 값을 따옴표로 감싸되 공백이 없도록 주의해야 해요. 예를 들어:

# ✅ These will work
require-dbt-version: ">=1.0.0"
# Double quotes are OK
require-dbt-version: '>=1.0.0'
# So are single quotes
# ❌ These will not work
require-dbt-version: >=1.0.0
# No quotes? No good
require-dbt-version: ">= 1.0.0"
# Don't put whitespace after the equality signs

상한을 무한대로 두지 않기

릴리스 간 안정성을 보장하려면 ">=1.0.0,<3.0.0"처럼 하한과 상한을 모두 정의하는 것을 권장해요. 무한대의 require-dbt-version(예: ">=1.0.0")은 권장하지 않아요. 상한이 없으면 dbt가 새 메이저 버전을 릴리즈할 때 프로젝트가 깨질 수 있어요.

dbt v2 호환성

require-dbt-version은 프로젝트나 패키지가 dbt v2(2.0.0 이상)를 지원하는지도 나타내요.

• 2.0.0을 제외하면 dbt v2는 지금은 경고하고 향후 릴리스에서 에러를 발생시킬 거예요. 이는 dbt v1 동작과 동일해요.
• --no-version-check로 버전 검사를 우회할 수 있어요.

버전 범위 정의 방법은 pin to a range 항목을 참고하세요.

dbt-autofix로 dbt 프로젝트·패키지 업데이트하기 — dbt-autofix 도구는 dbt 프로젝트의 deprecated 설정을 자동으로 스캔해 최신 모범 사례에 맞게 업데이트하고 dbt v2 마이그레이션을 대비해요. 실행 시 dbt-autofix는: packages.yml을 확인해 자동 업그레이드할 수 있는 패키지 결정 → require-dbt-version: 2.0.0 이상(dbt v2 지원을 의미)을 명시한 패키지 찾기 → dbt v2를 지원하는 가장 낮은 버전으로 해당 패키지 업그레이드. 이렇게 해서 dbt-autofix는 dbt v2와 동작이 확인된 패키지만 업데이트하고, dbt v2와 호환되지 않는 것으로 알려진 패키지는 건드리지 않아요.

예시 (Examples)

다음 예시들은 require-dbt-version 사용법을 보여줘요:

• 최소 dbt 버전 지정 — 최소 경계에 >= 연산자 사용.
• 범위에 고정(pin) — 상한·하한을 지정하는 쉼표 구분 목록 사용.
• 특정 dbt 버전 요구 — 프로젝트가 정확히 특정 dbt 버전에서만 동작하도록 제한.

최소 dbt 버전 지정

상한·하한을 지정하려면 >= 연산자를 사용해요. 예를 들어:

dbt_project.yml:

require-dbt-version: ">=1.9.0"
# project will only work with versions 1.9 and higher.
require-dbt-version: ">=2.0.0"
# project will only work with dbt v2 (v2.0.0 and higher).

기억하세요: 상한을 무한대로 두는 것은 권장하지 않아요. 대신 pin to a range 예시를 확인해 하한·상한을 모두 정의해 릴리스 간 안정성을 보장하세요.

범위에 고정 (Pin to a range)

상한·하한에 쉼표 구분 목록을 사용해요. 버전 범위는 YAML 목록(대괄호 사용) 또는 쉼표 구분 문자열로 정의할 수 있어요 — 두 형식 모두 유효하고 동작해요.

dbt v2 호환성을 나타내려면 버전 범위에 2.0.0 이상을 포함하세요. 다음 두 형식 모두 유효해요:

dbt_project.yml:

require-dbt-version: [">=1.10.0", "<3.0.0"]
# or
require-dbt-version: ">=1.10.0,<3.0.0"

범위가 2.0.0을 제외한다면(예: >=1.6.0,<2.0.0) dbt v2는 지금 경고를 표시하고 향후 릴리스에서 에러를 발생시켜요. --no-version-check로 버전 검사를 우회할 수 있어요.

특정 dbt 버전 요구

권장하지 않음 — 특정 dbt 버전으로 고정하는 것은 프로젝트 유연성을 제한하고 dbt 패키지와의 호환성 문제를 일으킬 수 있어 더 폭넓은 호환성과 업데이트 혜택을 위해 메이저 릴리스로 고정하는 것(예: ">=1.0.0", "<2.0.0" 같은 버전 범위)이 권장돼요. 프로젝트가 정확한 특정 dbt 버전에서만 동작하도록 제한할 수는 있지만, dbt v1.0.0 이상에서는 권장하지 않아요.

다음 예시에서 프로젝트는 dbt v1.5에서만 동작해요:

dbt_project.yml:

require-dbt-version: "1.5.0"

잘못된 dbt 버전 (Invalid dbt versions)

프로젝트를 실행하는 데 사용된 dbt 버전이 프로젝트나 포함된 패키지 중 하나에 지정된 require-dbt-version과 일치하지 않으면 dbt는 즉시 실패하고 다음 에러를 발생시켜요:

$ dbt compile
Running with dbt=1.5.0
Encountered an error while reading the project:
Runtime Error
  This version of dbt is not supported with the 'my_project' package.
    Installed version of dbt: =1.5.0
    Required version of dbt for 'my_project': ['>=1.6.0', '<2.0.0']
  Check the requirements for the 'my_project' package, or run dbt again with --no-version-check

버전 검사 비활성화 (Disabling version checks)

호환되지 않는 dbt 버전에 대한 실패를 무시하려면 dbt run에 --no-version-check 플래그를 제공하세요.

$ dbt run --no-version-check
Running with dbt=1.5.0
Found 13 models, 2 tests, 1 archives, 0 analyses, 204 macros, 2 operations....

사용 방법에 대한 자세한 내용은 global configs 문서를 참고하세요.

더 알아보기 (Learn more)

• 프로젝트 설정(dbt_project.yml)의 전체 목록은 Project configurations 문서를 참고하세요.
• 버전 범위 정의에 대한 자세한 내용은 pin to a range 항목을 참고하세요.