SQLAlchemy 엔진 구성

SQLAlchemy 엔진 구성 (Engine Configuration)

SQLAlchemy에서 엔진(Engine)은 데이터베이스와의 연결을 관리하는 시작점이에요. 애플리케이션은 보통 엔진을 하나만 만들어 전역적으로 사용해요. 엔진은 연결 풀을 갖고 있으며, SQLAlchemy의 create_engine() 호출이 실제 데이터베이스 연결을 수행하는 유일한 인터페이스예요.

출처: SQLAlchemy — Engine Configuration

엔진 만들기

create_engine()에 데이터베이스 URL을 넘겨 엔진을 만들어요. URL은 dialect+driver://user:password@host:port/dbname 형태로, 다이얼렉트(dialect)는 어떤 데이터베이스를 다루는지를, 드라이버는 어떤 DBAPI 드라이버를 쓸지를 가리켜요.

from sqlalchemy import create_engine

# SQLite (파일)
engine = create_engine("sqlite:///mydb.sqlite3")

# PostgreSQL
engine = create_engine("postgresql+psycopg://scott:tiger@localhost/mydb")

다이얼렉트 접두사를 생략하면 SQLite가 기본으로 선택돼요. PostgreSQL은 postgresql://로 표기하며 드라이버를 물리려면 +psycopg 같은 접미사를 붙여요.

연결 풀링

기본적으로 SQLAlchemy는 QueuePool을 사용해 연결을 재사용하는 풀을 관리해요. 연결이 필요할 때마다 새로 여는 대신 풀에서 꺼내 쓰고, 반납하면 다시 재사용되도록 해요. 이 덕분에 많은 요청을 처리하는 웹 애플리케이션에서도 연결 지연을 줄일 수 있어요.

연결 고갈이나 유휴 연결 처리 전략이 필요하면 pool_size, max_overflow, pool_pre_ping, pool_recycle 같은 옵션을 엔진에 줄 수 있어요.

engine = create_engine(
    "postgresql+psycopg://scott:tiger@localhost/mydb",
    pool_size=10,
    max_overflow=20,
    pool_pre_ping=True,
)

pool_pre_ping=True는 연결을 꺼내기 전에 핑을 보내 끊어진 연결을 미리 걸러 줘서, 오래된 연결 사용으로 인한 오류를 줄여요.

엔진은 연결 자체가 아니다

중요한 점은 엔진 자체가 커넥션이 아니라는 것이에요. 엔진은 연결을 만들고 관리하는 팩토리이며, 실제 작업은 엔진에서 얻는 커넥션이나 그 위에서 동작하는 세션(Session, ORM)을 통해 이뤄져요. ORM을 쓸 때는 엔진을 sessionmaker에 넘겨 세션 팩토리를 만들게 돼요.

SQLAlchemy 엔진 구성