Airflow 폴더 구조 및 역할 분리 정리

(DAG, Task, SQL을 어떻게 나눌 것인가)

Airflow를 사용하다 보면 가장 먼저 헷갈리는 부분이 있다.

“어디에 무엇을 써야 하는가?”

 

DAG 파일에 로직을 다 넣어야 하는지,
Python 함수는 어디에 두는지,
SQL은 그냥 문자열로 써도 되는지.

이번 글에서는 실무에서 권장되는 Airflow 폴더 구조와 각 파일의 역할을 간단하게 정리해본다.

 

1. Airflow 설계의 핵심 원칙

Airflow에서 가장 중요한 개념은 다음 한 줄로 정리된다.

순수 기능은 Python 모듈로 만들고,
DAG는 그 기능들을 가져와 실행 흐름만 정의한다.

즉,

• DAG는 설계도
• Task는 단일 책임
• 로직은 DAG 밖에 둔다

 

2. 권장 폴더 구조 (실무 기준)

airflow/
├─ dags/                     # DAG 정의 (흐름, 스케줄)
│  ├─ etl_orders_dag.py
│  └─ _common.py
│
├─ pipeline/                 # ⭐ 순수 ETL 로직
│  ├─ __init__.py
│  ├─ extract.py
│  ├─ transform.py
│  └─ load.py
│
├─ sql/                      # SQL 분리 (선택이지만 권장)
│  └─ extract_orders.sql
│
└─ requirements.txt

 

3. 각 폴더의 역할 정리 

1️⃣ pipeline/ — 순수 기능 (단일 책임)

• Extract / Transform / Load 로직
• Airflow 없이도 실행 가능해야 함
• 테스트와 재사용이 쉬움

# pipeline/extract.py
def extract_orders():
    ...

 

Task = 하나의 기능

 

2️⃣ dags/ — 실행 흐름만 정의

• 스케줄
• Task 간 의존성
• 재시도 / 실패 정책

with DAG(...) as dag:
    extract >> transform >> load

 

DAG는 “무엇을 언제 어떻게 실행할지”만 책임짐

 

3️⃣ sql/ — SQL은 파일로 분리

-- sql/extract_orders.sql
SELECT * FROM raw."order";

 

PostgresOperator(
    sql="extract_orders.sql"
)

• DAG 가독성 향상
• SQL 수정 시 코드 변경 최소화
• 리뷰 및 관리 용이

 

4. 왜 이렇게 나누는가?

이 구조의 장점은 명확하다.

• DAG 파일이 커지지 않음
• 로직 변경이 DAG 파싱에 영향 없음
• SQL / Python / 흐름이 명확히 분리됨
• 운영과 실험을 동시에 하기 쉬움

결국 Airflow는 로직을 실행하는 도구가 아니라,
로직을 조율하는 도구라는 점이 구조에 그대로 드러난다.

 

 

5. 정리하면

DAG는 흐름,
Task는 단일 책임,
로직은 Python 모듈,
SQL은 파일로 분리한다.

 

이 구조를 기준으로 잡아두면,
Airflow 프로젝트가 커져도 흔들리지 않는다