SQLAlchemy에서 text()와 fetchone()의 역할 정리

SQLAlchemy로 순수 SQL을 실행할 때 text()와 fetchone()은 자주 함께 등장한다.
이 둘은 SQL 실행 자체와 결과를 어떻게 가져올지를 담당한다.

 

예시 코드

def is_batch_ingested(batch_id: str, conn_uri: str) -> bool:
    """
    주어진 batch_id가 이미 성공적으로 적재되었는지 여부를 반환한다.
    """
    engine = create_engine(conn_uri)

    query = """
        SELECT 1
        FROM ingest_log
        WHERE batch_id = :batch_id
            AND status = 'SUCCESS'
        LIMIT 1
    """

    with engine.connect() as conn:
        result = conn.execute(text(query), {'batch_id': batch_id}).fetchone()

    return result is not None

 

먼저 text()는 문자열 형태의 SQL 문을 SQLAlchemy가 실행할 수 있도록 감싸는 역할을 한다.
즉, 사람이 작성한 SQL을 SQLAlchemy 엔진이 이해할 수 있는 객체로 변환한다.
이 과정이 있어야 :param 형태의 바인딩 파라미터도 안전하게 사용할 수 있다.

 

다음으로 fetchone()은 SQL 실행 결과 중 첫 번째 행 하나만 반환한다.
결과가 여러 행이어도 하나만 가져오며, 결과가 없다면 None을 반환한다.
그래서 데이터 존재 여부를 확인할 때 가장 적합하다.

 

비유하면,
text()는 사람 말 → 기계가 이해하는 언어로 번역하는 과정이고,
fetchone()은 결과 더미 중 하나만 집어 드는 동작이다.