Airflow无法找到DAG目录下SQL文件的问题求助

问题背景 #

使用PostgresOperator指定DAG目录下相对路径的SQL文件时，出现jinja2.exceptions.TemplateNotFound: sql/evergreen_stage.sql错误：

stage_evergreen = PostgresOperator(
    task_id="RefreshStageEvergreen",
    postgres_conn_id="evergreen",
    autocommit=True,
    sql="sql/evergreen_stage.sql")

尝试在DAG装饰器中配置template_searchpath后问题仍未解决：

@dag(
dag_id = "Evergreen",
schedule_interval = '0 10 * * *',
start_date=pendulum.datetime(2023, 3, 9, tz="UTC"),
catchup=False,
dagrun_timeout=timedelta(minutes=20),
template_searchpath = ['/opt/airflow/dags/sql/']
)

仅当SQL文件直接放在DAG目录下时可正常运行。

解决方案 #

1. 匹配template_searchpath调整sql参数 #

当template_searchpath指向SQL文件所在目录（如/opt/airflow/dags/sql/），Jinja会直接在该目录下查找模板，此时sql参数只需填写文件名，无需带路径前缀：

stage_evergreen = PostgresOperator(
    task_id="RefreshStageEvergreen",
    postgres_conn_id="evergreen",
    autocommit=True,
    sql="evergreen_stage.sql")

2. 修改template_searchpath为DAG根目录 #

若希望保留sql="sql/evergreen_stage.sql"的写法，需将template_searchpath设置为DAG文件的根目录（/opt/airflow/dags/），让Jinja从根目录开始解析相对路径：

@dag(
dag_id = "Evergreen",
schedule_interval = '0 10 * * *',
start_date=pendulum.datetime(2023, 3, 9, tz="UTC"),
catchup=False,
dagrun_timeout=timedelta(minutes=20),
template_searchpath = ['/opt/airflow/dags/']
)

3. 验证路径与权限 #

• 确认SQL文件实际路径与配置一致：检查/opt/airflow/dags/sql/evergreen_stage.sql是否存在，注意Linux系统路径区分大小写。
• 确保Airflow进程对文件及目录有读取权限，可执行以下命令调整：

  chown -R airflow:airflow /opt/airflow/dags/sql/
  

4. 动态配置template_searchpath（推荐） #

使用Python的__file__变量动态获取DAG所在目录，避免硬编码绝对路径，适配不同部署环境：

import os
from pathlib import Path

# 获取当前DAG文件所在目录
DAG_DIR = Path(__file__).parent
# 拼接SQL目录路径
SQL_DIR = str(DAG_DIR / "sql")

@dag(
dag_id = "Evergreen",
schedule_interval = '0 10 * * *',
start_date=pendulum.datetime(2023, 3, 9, tz="UTC"),
catchup=False,
dagrun_timeout=timedelta(minutes=20),
template_searchpath = [SQL_DIR]
)

此时sql参数填写evergreen_stage.sql即可正常加载文件。

内容的提问来源于stack exchange，提问作者moth