데이터 계층 설계

문제 정의

이번 프로젝트의 데이터 계층은 단순 CRUD 편의보다 운영 안정성이 더 중요했다.
도메인이 커지고 쿼리 수가 늘어날수록, 실행 SQL을 바로 읽을 수 있는지와 타입 불일치를 얼마나 빨리 잡는지가 실제 개발 속도를 좌우했다.

특히 다음 요구가 컸다.

• 장애 시 실행 SQL을 빠르게 확인할 수 있어야 한다
• schema mismatch를 런타임까지 미루지 않아야 한다
• 복잡한 조회도 팀이 읽고 튜닝할 수 있는 형태로 남아야 한다

선택 기준

그래서 데이터 계층을 고를 때는 "얼마나 빨리 CRUD를 붙일 수 있는가"보다 아래 기준을 우선했다.

• SQL이 추상화 뒤에 숨지 않을 것
• 결과 타입과 파라미터 타입을 정적으로 검증할 수 있을 것
• 쿼리 파일이 운영 분석과 LLM 협업 맥락으로도 그대로 쓸 수 있을 것

이 기준에서 sqlc는 꽤 잘 맞았다.
더 자세한 기술 선택 배경은 독립 article인 Why SQLC에서 따로 정리했다.

설계 결과

최종적으로 데이터 계층은 "쿼리를 선명하게 남기되, 수동 매핑의 실수를 줄이는 구조"를 목표로 정리됐다.

• 쿼리는 SQL 파일에 남기고
• 생성된 타입으로 애플리케이션 계층과 맞물리게 하고
• 컨텍스트별 저장소 경계를 유지해 영향 범위를 줄였다

이 접근 덕분에 운영 중에는 SQL 가시성을 확보하고, 개발 중에는 타입 안정성을 높이는 쪽으로 균형을 맞출 수 있었다.