Support for declaraing variables in a vars.yml file (#12488)

Author: sriramr98

.changes/unreleased/Features-20260212-232728.yaml

@@ -0,0 +1,6 @@
+kind: Features
+body: Added support for vars.yml to declare project variables
+time: 2026-02-12T23:27:28.294557+05:30
+custom:
+    Author: sriramr98
+    Issue: 11144 2955

core/dbt/config/project.py

@@ -21,6 +21,7 @@
     PACKAGE_LOCK_FILE_NAME,
     PACKAGE_LOCK_HASH_KEY,
     PACKAGES_FILE_NAME,
+    VARS_FILE_NAME,
 )
 from dbt.contracts.project import PackageConfig
 from dbt.contracts.project import Project as ProjectContract
@@ -108,6 +109,31 @@ def load_yml_dict(file_path):
     return ret
 
 
+def vars_data_from_root(project_root: str) -> Dict[str, Any]:
+    """Load vars from vars.yml file if it exists.
+
+    Returns the contents of the 'vars' key, or empty dict if file doesn't exist or has no vars key.
+    """
+    vars_yml_path = os.path.join(project_root, VARS_FILE_NAME)
+    vars_file_dict = load_yml_dict(vars_yml_path)
+    if not vars_file_dict:
+        return {}
+    return vars_file_dict.get("vars", {})
+
+
+def validate_vars_not_in_both(
+    project_dict: Dict[str, Any],
+    has_vars_file: bool,
+) -> None:
+    """Raise error if vars defined in both vars.yml and dbt_project.yml."""
+    has_project_vars = "vars" in project_dict and project_dict["vars"]
+
+    if has_vars_file and has_project_vars:
+        raise DbtProjectError(
+            f"Variables cannot be defined in both {VARS_FILE_NAME} and {DBT_PROJECT_FILE_NAME}. "
+        )
+
+
 def package_and_project_data_from_root(project_root):
     packages_yml_dict = load_yml_dict(f"{project_root}/{PACKAGES_FILE_NAME}")
     dependencies_yml_dict = load_yml_dict(f"{project_root}/{DEPENDENCIES_FILE_NAME}")
@@ -338,10 +364,14 @@ def get_rendered(
         )
 
     # Called by Project.from_project_root which first calls PartialProject.from_project_root
-    def render(self, renderer: DbtProjectYamlRenderer) -> "Project":
+    def render(
+        self,
+        renderer: DbtProjectYamlRenderer,
+        vars_from_file: Optional[Dict[str, Any]] = None,
+    ) -> "Project":
         try:
             rendered = self.get_rendered(renderer)
-            return self.create_project(rendered)
+            return self.create_project(rendered, vars_from_file=vars_from_file)
         except DbtProjectError as exc:
             if exc.path is None:
                 exc.path = os.path.join(self.project_root, DBT_PROJECT_FILE_NAME)
@@ -376,7 +406,11 @@ def check_config_path(
                     kwargs.update({"exp_path": expected_path})
                 deprecations.warn(f"project-config-{deprecated_path}", **kwargs)
 
-    def create_project(self, rendered: RenderComponents) -> "Project":
+    def create_project(
+        self,
+        rendered: RenderComponents,
+        vars_from_file: Optional[Dict[str, Any]] = None,
+    ) -> "Project":
         unrendered = RenderComponents(
             project_dict=self.project_dict,
             packages_dict=self.packages_dict,
@@ -485,10 +519,13 @@ def create_project(self, rendered: RenderComponents) -> "Project":
         saved_queries = cfg.saved_queries
         exposures = cfg.exposures
         functions = cfg.functions
-        if cfg.vars is None:
-            vars_dict: Dict[str, Any] = {}
+
+        # Use vars from vars.yml if provided, otherwise use vars from dbt_project.yml
+        # Mutual exclusivity ensures only one source is populated
+        if vars_from_file:
+            vars_dict = vars_from_file
         else:
-            vars_dict = cfg.vars
+            vars_dict = cfg.vars or {}
 
         vars_value = VarProvider(vars_dict)
         # There will never be any project_env_vars when it's first created
@@ -557,6 +594,7 @@ def create_project(self, rendered: RenderComponents) -> "Project":
             restrict_access=cfg.restrict_access,
             dbt_cloud=dbt_cloud,
             flags=flags,
+            vars_from_file=vars_from_file or {},
         )
         # sanity check - this means an internal issue
         project.validate()
@@ -676,6 +714,7 @@ class Project:
     restrict_access: bool
     dbt_cloud: Dict[str, Any]
     flags: Dict[str, Any]
+    vars_from_file: Dict[str, Any]
 
     @property
     def all_source_paths(self) -> List[str]:
@@ -786,11 +825,16 @@ def from_project_root(
         *,
         verify_version: bool = False,
         validate: bool = False,
+        vars_from_file: Optional[Dict[str, Any]] = None,
     ) -> "Project":
         partial = PartialProject.from_project_root(
             project_root, verify_version=verify_version, validate=validate
         )
-        return partial.render(renderer)
+
+        # Check mutual exclusivity before rendering
+        validate_vars_not_in_both(partial.project_dict, bool(vars_from_file))
+
+        return partial.render(renderer, vars_from_file=vars_from_file)
 
     def hashed_name(self):
         return md5(self.project_name)

core/dbt/config/runtime.py

@@ -24,7 +24,11 @@
 from dbt.adapters.contracts.relation import ComponentName
 from dbt.adapters.factory import get_include_paths, get_relation_class_by_name
 from dbt.artifacts.resources import Quoting
-from dbt.config.project import load_package_lock_config, load_raw_project
+from dbt.config.project import (
+    load_package_lock_config,
+    load_raw_project,
+    vars_data_from_root,
+)
 from dbt.contracts.graph.manifest import ManifestMetadata
 from dbt.contracts.project import Configuration
 from dbt.events.types import UnusedResourceConfigPath
@@ -54,10 +58,24 @@ def load_project(
     validate: bool = False,
     require_vars: bool = True,
 ) -> Project:
-    # get the project with all of the provided information
-    project_renderer = DbtProjectYamlRenderer(profile, cli_vars, require_vars=require_vars)
+
+    if cli_vars is None:
+        cli_vars = {}
+
+    # Load vars.yml first (before rendering dbt_project.yml)
+    vars_from_file = vars_data_from_root(project_root)
+
+    # Merge: CLI vars take precedence over file vars
+    merged_vars = {**vars_from_file, **cli_vars}
+
+    # Renderer receives merged vars for Jinja in dbt_project.yml
+    project_renderer = DbtProjectYamlRenderer(profile, merged_vars, require_vars=require_vars)
     project = Project.from_project_root(
-        project_root, project_renderer, verify_version=version_check, validate=validate
+        project_root,
+        project_renderer,
+        verify_version=version_check,
+        validate=validate,
+        vars_from_file=vars_from_file,
     )
 
     # Save env_vars encountered in rendering for partial parsing
@@ -199,6 +217,7 @@ def from_parts(
             dependencies=dependencies,
             dbt_cloud=project.dbt_cloud,
             flags=project.flags,
+            vars_from_file=project.vars_from_file,
         )
 
     # Called by 'load_projects' in this class

core/dbt/constants.py

@@ -12,6 +12,7 @@
 )
 
 DBT_PROJECT_FILE_NAME = "dbt_project.yml"
+VARS_FILE_NAME = "vars.yml"
 PACKAGES_FILE_NAME = "packages.yml"
 DEPENDENCIES_FILE_NAME = "dependencies.yml"
 PACKAGE_LOCK_FILE_NAME = "package-lock.yml"

core/dbt/parser/manifest.py

@@ -1030,16 +1030,18 @@ def build_manifest_state_check(self):
             v for k, v in config.cli_vars.items() if k.startswith(SECRET_ENV_PREFIX) and v.strip()
         ]
         stringified_cli_vars = pprint.pformat(config.cli_vars)
-        vars_hash = FileHash.from_contents(
-            "\x00".join(
-                [
-                    stringified_cli_vars,
-                    config.profile_name,
-                    config.target_name,
-                    __version__,
-                ]
-            )
-        )
+        vars_hash_contents = [
+            stringified_cli_vars,
+            config.profile_name,
+            config.target_name,
+            __version__,
+        ]
+
+        # We only add vars from `vars.yml` if it's present to prevent affecting users not using vars.yml from getting fully parsed.
+        if config.vars_from_file:
+            vars_hash_contents.append(pprint.pformat(config.vars_from_file))
+
+        vars_hash = FileHash.from_contents("\x00".join(vars_hash_contents))
         fire_event(
             StateCheckVarsHash(
                 checksum=vars_hash.checksum,

core/dbt/tests/fixtures/project.py

@@ -191,7 +191,7 @@ def project_config_update():
 # Combines the project_config_update dictionary with project_config defaults to
 # produce a project_yml config and write it out as dbt_project.yml
 @pytest.fixture(scope="class")
-def dbt_project_yml(project_root, project_config_update):
+def dbt_project_yml(project_root, project_config_update, vars_yml):
     project_config = {
         "name": "test",
         "profile": "test",
@@ -259,6 +259,23 @@ def selectors_yml(project_root, selectors):
         write_file(data, project_root, "selectors.yml")
 
 
+# Fixture to provide vars as either yaml or dictionary
+@pytest.fixture(scope="class")
+def vars_yml_update():
+    return {}
+
+
+# Write out the vars.yml file
+@pytest.fixture(scope="class")
+def vars_yml(project_root, vars_yml_update):
+    if vars_yml_update:
+        if isinstance(vars_yml_update, str):
+            data = vars_yml_update
+        else:
+            data = yaml.safe_dump(vars_yml_update)
+        write_file(data, project_root, "vars.yml")
+
+
 # This fixture ensures that the logging infrastructure does not accidentally
 # reuse streams configured on previous test runs, which might now be closed.
 # It should be run before (and so included as a parameter by) any other fixture
@@ -407,6 +424,7 @@ def project_files(
     selectors_yml,
     dependencies_yml,
     packages_yml,
+    vars_yml,
     dbt_project_yml,
 ):
     write_project_files(project_root, "models", {**models, **properties})