동작 변경(Behavior changes) 소개

동작 변경(Behavior changes) 소개

동작 변경(behavior change)은 같은 프로젝트 코드와 명령이 이전과 다른 결과를 내도록 dbt에 의도적으로 업데이트하는 것이에요 — 예를 들어 새 검증 오류, 변경된 매크로 시그니처, 또는 아티팩트·구조화된 로그의 브레이킹 체인지가 있어요. 버그 수정, 새 경고, 또는 브레이킹이 아닌 추가는 동작 변경이 아니에요.

출처: 문서

본문

동작 변경은 같은 프로젝트 코드와 명령이 이전과 다른 결과를 내도록 dbt를 의도적으로 업데이트하는 것이에요 — 예를 들어 새 검증 오류, 변경된 매크로 시그니처, 또는 아티팩트나 구조화된 로그의 브레이킹 체인지가 있어요. 버그 수정, 새 경고, 또는 브레이킹이 아닌 추가는 동작 변경이 아니에요.

dbt는 이러한 변경을 동작 변경 플래그 뒤에 가둬서(게이트), 언제 새 동작을 채택할지 사용자가 통제할 수 있게 해요.

다음은 동작 변경의 예시예요:

• dbt가 이전에는 발생하지 않던 검증 오류를 발생시키기 시작함.
• dbt가 내장 매크로의 시그니처를 변경함. 프로젝트에 그 매크로의 커스텀 재구현이 있는 경우, 커스텀 재구현이 받아들일 수 없는 인자를 전달받아 오류가 발생할 수 있음.
• dbt 어댑터가 dbt-Jinja 컨텍스트의 {{ adapter }} 객체에서 이전에 사용 가능했던 메서드의 이름을 바꾸거나 제거함.

다음은 동작 변경이 아닌 예시예요:

• 이전 동작이 결함적이거나, 바람직하지 않거나, 문서화되지 않았던 버그를 수정하는 경우.
• dbt가 이전에는 발생하지 않던 경고를 발생시키기 시작함.
• dbt가 로그 이벤트의 사람 친화적 메시지 언어를 업데이트함.

이 플래그들은 dbt_project.yml의 flags 사전에서 반드시 설정해야 해요. 이들은 프로젝트 코드와 밀접하게 연결된 동작을 구성하므로 버전 관리에 정의하고 pull/merge 요청으로 수정해야 해요 — 동일한 테스트와 동료 검토를 거쳐야 해요.

동작 변경 플래그는 개발의 세 단계를 거쳐요:

1. 도입 (기본값으로 비활성화): dbt가 '이전'과 '새' 동작을 모두 지원하는 로직을 추가해요. '새' 동작을 플래그 뒤에 가두고 기본값으로 비활성화해 이전 동작을 보존해요.
2. 성숙 (기본값으로 활성화): 플래그의 기본값이 기본적으로 새 동작으로 전환돼요. 여전히 이전 동작을 보존할 수 있지만, 더 이상 쓰지 말라는(deprecation) 경고가 보일 수 있어요.
3. 제거 (일반적으로 활성화): 이전 동작이 dbt 코드베이스(들)에서 제거돼요. 대부분의 플래그는 무기한 지원되지만, 영원히 지원한다는 보장은 없어요. 플래그가 제거되면 상당한 사전 경고가 있을 거예요.

이 표는 dbt v1 Latest 릴리즈 트랙의 어느 달에, 그리고 dbt v1의 어느 버전에 동작 변경의 도입(기본값으로 비활성화) 또는 성숙(기본값으로 활성화)이 포함됐는지 보여줘요.

dbt platform v1 Latest 릴리즈 트랙의 여러 동작 변경 플래그가 2026년 9월 1일에 성숙할 예정이며, 기본값이 false에서 true로 전환돼요. 9월 1일 날짜는 dbt platform 릴리즈 트랙에만 적용돼요. 이 플래그들은 dbt v1.12에서 성숙에 도달했어요. 도입 날짜는 dbt v1 동작 변경 표를 참고하세요.

다음 플래그는 dbt v2 전용이며 dbt v1에는 해당하는 것이 없어요. dbt_project.yml의 flags: 블록에서 같은 방식으로 구성돼요.

이 표는 dbt 어댑터의 어느 버전에 동작 변경의 도입(기본값으로 비활성화) 또는 성숙(기본값으로 활성화)이 포함됐는지 보여줘요.

프로젝트에서 동작 변경 플래그를 어떻게 구현하나요? 다음 예시는 최신 dbt와 dbt v1의 현재 플래그와 기본값을 보여줘요. 특정 동작 변경을 옵트아웃하려면 dbt_project.yml에서 플래그 값을 false로 설정해요. 옵트아웃한 레거시 동작에 대한 경고가 계속 보이는데, 다음 중 하나를 할 때까지 그렇지 않아요:

• 문제를 해결(플래그를 true로 전환)
• warn_error_options.silence 플래그로 경고 무음화

dbt_project.yml

flags:
  require_explicit_package_overrides_for_builtin_materializations: true
  require_resource_names_without_spaces: true
  source_freshness_run_project_hooks: true
  skip_nodes_if_on_run_start_fails: true
  state_modified_compare_more_unrendered_values: true
  require_yaml_configuration_for_mf_time_spines: true
  require_batched_execution_for_custom_microbatch_strategy: true
  require_nested_cumulative_type_params: true
  validate_macro_args: true
  require_all_warnings_handled_by_warn_error: true
  require_generic_test_arguments_property: true
  require_unique_project_resource_names: false
  require_ref_searches_node_package_before_root: false
  require_valid_schema_from_generate_schema_name: false
  enable_truthy_nulls_equals_macro: false
  require_sql_header_in_test_configs: false
  require_corrected_analysis_fqns: false
  require_source_and_semantic_model_names_without_spaces: false
  allow_jinja_file_extensions: false
  latest_version_pointer_enabled_by_default: false

성숙 날짜가 없으면 무슨 의미인가요? 성숙 날짜가 아직 설정되지 않았으면(-로 표시), 플래그 기본값이 정확히 언제 바뀔지 아직 정하지 않은 거예요. 영향을 받는 사용자는 그동안 deprecation 경고를 보게 되고, 성숙 날짜 전에 사전 경고 이메일을 받게 돼요. 그동안 deprecation 경고가 보이면 다음 중 하나를 할 수 있어요:

• 프로젝트를 새 동작을 지원하도록 마이그레이션한 뒤 플래그를 true로 설정해 경고가 안 보이게 하기.
• 플래그를 명시적으로 false로 설정하기. 경고는 계속 보이고, 성숙 날짜 이후(기본값이 바뀔 때)에도 레거시 동작을 유지해요.

더 알아보기 (Learn more)

• 동작 변경 플래그의 개별 플래그 문서 모음 (referenc/global-configs/behavior-flags/*)
• 환경 변수 구성
• 프로젝트 플래그