본문 바로가기
Q&A해결2026년 4월 20일1분 읽기

FastAPI + SQLAlchemy 2.0 async에서 deadlock이 가끔 발생합니다

백
백엔드3년차
조회 401댓글 1

FastAPI + SQLAlchemy 2.0 async + PostgreSQL 환경입니다. 로컬·스테이징은 멀쩡한데 운영에서 트래픽이 살짝만 올라가면 asyncpg.exceptions.DeadlockDetectedError가 가끔 떨어집니다.

같은 트랜잭션 안에서 여러 테이블을 업데이트하는 부분이 있는데, 항상 동일 순서로 락을 잡도록 해도 사라지지 않습니다.

혹시 async session·connection pool 차원에서 deadlock이 생기는 패턴이 있을까요?

댓글 1

김김영삼7개월 전

asyncpg deadlock은 두 가지 다른 원인이 종종 섞입니다 — 진단 방향을 명확히 잡아야 합니다.

1) PostgreSQL 측 deadlock (실제 락 충돌)

로그에 Process 1234 waits for ShareLock... Process 5678 waits for ... 형태가 찍힙니다. 이건 정직하게 두 트랜잭션이 서로의 락을 기다리는 상황이고, 락 획득 순서를 통일하거나 SELECT ... FOR UPDATE OF로 좁혀야 합니다.

2) Async session 재사용으로 인한 가짜 deadlock

실무에서 더 자주 보는 케이스입니다. AsyncSession 하나를 여러 코루틴이 동시에 사용하면 SQLAlchemy 내부 상태가 꼬이면서 deadlock처럼 보이는 에러가 납니다.

잘못된 패턴:

session = async_session()  # 모듈 레벨에 두는 실수

async def handler():
await asyncio.gather(
session.execute(q1), # 같은 세션을 동시에!
session.execute(q2),
)

권장 패턴 (FastAPI Depends):

async def get_session() -> AsyncIterator[AsyncSession]:
async with async_session_factory() as s:
yield s

@app.post("/transfer")
async def transfer(s: AsyncSession = Depends(get_session)):
async with s.begin():
await s.execute(...)
await s.execute(...)
# 한 요청 = 한 세션, 동시 사용 금지

실무 체크리스트:

  • echo=True로 실제 SQL 순서·트랜잭션 경계 확인
  • pool_pre_ping=True·pool_recycle=300으로 stale connection 정리
  • 모든 update는 WHERE 절에 PK 포함 + 동일한 정렬 순서로
  • 긴 락이 필요한 작업은 SET LOCAL lock_timeout='5s' 로 빠르게 실패시키기
  • PostgreSQL 측 log_lock_waits=on 활성화 → 어느 쿼리가 누구를 기다리는지 즉시 보임

asyncpg connection pool 별도 주의:

SQLAlchemy의 pool과 asyncpg의 내부 statement cache가 충돌하는 케이스가 있습니다. connect_args={"statement_cache_size": 0}를 주면 PgBouncer transaction 모드와도 호환됩니다.

마지막 한 줄: "운영에서만 발생"은 거의 항상 session 공유 + 동시 호출입니다. 코드에서 await asyncio.gather(...) 주변을 다시 한 번 점검해보세요.

Ctrl+Enter로 등록