같은 SQLAlchemy인데 왜 다르게 보일까? to_sql()과 engine.execute()의 역할 차이

같은 SQLAlchemy를 사용했는데,
어떤 코드는 df.to_sql()을 쓰고
어떤 코드는 engine.begin() + execute()를 쓰는 경우를 보면 헷갈리기 쉽습니다.

 

겉으로 보면 둘 다 DB에 데이터를 넣는 코드지만,
실제로는 역할과 추상화 수준이 완전히 다릅니다.

 

먼저 아래 코드는 pandas + SQLAlchemy 조합입니다.

df.to_sql(
    name=table,
    schema=schema,
    con=engine,
    if_exists="append",
    index=False
)

이 방식은 데이터프레임을 통째로 테이블에 적재하는 용도입니다.
SQL을 직접 작성하지 않아도 되고,
“이 DataFrame을 저 테이블에 넣어줘”라는 의도 중심 API입니다.

 

비유하면, 엑셀 파일을 통째로 DB에 업로드하는 버튼에 가깝습니다.

 

반면 아래 코드는 SQLAlchemy의 Core 레벨 사용입니다.

with engine.begin() as conn:
    conn.execute(
        insert_sql,
        {
            "table_name": table_name,
            "batch_id": batch_id,
            "ingest_start_time": ingest_start_time,
            "expected_record_count": expected_record_count,
            "ingest_status": ingest_status,
            "error_message": error_message,
        },
    )

이 방식은

• SQL을 직접 작성하고
• 파라미터를 명시적으로 바인딩하며
• 트랜잭션 단위까지 제어합니다.

즉,  **“이 SQL을 이 값으로 정확히 실행해라”**에 가깝습니다.

 

로그 테이블, 메타데이터, 상태 기록처럼
한 건 한 건 의미가 중요한 데이터에 적합합니다.

 

차이를 한 번에 정리하면

• df.to_sql()
  • 데이터프레임 중심
  • 대량 적재에 적합
  • SQL을 거의 의식하지 않음
• engine.execute()
  • SQL 중심
  • 정밀 제어 가능
  • 로그, 상태, 이력 기록에 적합

같은 SQLAlchemy를 쓰지만,
하나는 고수준 래퍼, 하나는 저수준 엔진 접근이라고 이해하면 정확합니다.

 

to_sql()은 데이터프레임 적재용 고수준 API이고, engine.execute()는 SQL을 직접 제어하는 저수준 API로, 목적에 따라 역할이 명확히 다르다.