Pydantic-asyncpg 결합을 통한 초경량 Typed CRUD 레이어 etchdb 구현

I keep writing the same Pydantic-asyncpg wrapper. So I published it.

Hannu Varjoranta2026년 5월 12일9분intermediate

AI 요약

Context

SQLAlchemy 등 기존 ORM의 무거운 추상화와 복잡한 Session 라이프사이클 관리에 따른 오버헤드 발생. 특히 pgvector, PostGIS 등 Postgres 확장 기능 사용 시 ORM의 제약으로 인해 결국 Raw SQL로 회귀하는 설계 모순 존재.

Pydantic 모델을 데이터베이스 Row와 직접 매핑하는 최소 단위의 추상화 계층 설계
RETURNING * 구문을 활용하여 서버 사이드 Default 값과 시퀀스 ID를 즉시 반영하는 insert 로직 구현
설정된 필드만 쿼리에 포함하는 Partial Update 메커니즘을 통한 데이터 덮어쓰기(Clobbering) 방지
DB-side 연산을 위해 Inc, Now와 같은 Sentinel 객체를 도입하여 원자적 업데이트(Atomic Increment) 보장
드라이버별로 상이한 execute 반환값을 정규화하여 통합 인터페이스 제공 및 Typed Exception 체계 구축
WHERE 조건절에 필터링 로직을 통합하여 TOCTOU(Time-of-check to time-of-use) 취약점을 방지하는 Atomic Scoping 적용

실천 포인트

1. ORM의 추상화 수준이 도메인의 복잡도보다 높을 때 Raw SQL 기반의 얇은 Wrapper 도입 검토

2. Partial Update 구현 시 Pydantic의 unset 필드를 식별하여 SQL 생성 로직에 반영하는지 확인

3. DB-side 원자적 연산을 위해 Application 레벨의 계산 대신 SQL Sentinel(Inc, Now) 활용 권장

4. 다중 드라이버 지원 시 Exception 래핑을 통해 일관된 에러 핸들링 인터페이스 확보

태그