SQLAlchemy의 복잡성을 제거한 57라인의 asyncpg 기반 Type-safe 래퍼 구현

Context

SQLAlchemy와 같은 무거운 ORM 사용 시 발생하는 DSL 학습 비용과 불투명한 쿼리 생성으로 인한 N+1 문제 발생. 특히 Raw SQL 사용을 위해 text() 함수로 우회하는 비효율적 구조와 런타임 타입 불일치 해결 필요성 대두.

Technical Solution

• asyncpg 라이브러리를 기반으로 한 초경량 래퍼 설계로 57라인의 핵심 코드로 구동
• Pydantic 모델의 table 속성을 활용하여 DB 테이블과 Python 객체 간의 매핑 정의
• query_as 메서드를 통한 Generic Type 반환으로 SQL 결과값에 대한 정적 타입 안전성 확보
• Join 쿼리 시 별도의 DTO 모델을 정의하여 관계 매핑의 Magic을 제거하고 명시적 데이터 구조 설계
• CLI Validator를 도입하여 배포 전 모델 정의와 실제 DB Schema 간의 타입 일치 여부를 사전 검증