배포 환경에서 Prisma 바이너리 불일치로 DB 연결 불가 해결

배포 환경에서 Prisma Client가 아예 실행이 안 되는 상황이 생겼다.

배경: binaryTargets가 왜 필요한가

Prisma는 내부적으로 query engine이라는 네이티브 바이너리를 사용한다. 이 바이너리는 OS, 아키텍처, OpenSSL 버전 조합에 따라 다르게 빌드되어 있고, prisma generate 시점에 binaryTargets에 명시된 플랫폼 바이너리를 함께 내려받는다.

문제는 개발 환경(보통 macOS)과 실제 배포 환경(보통 Linux 컨테이너)이 다를 때 발생한다. 로컬에서 prisma generate 돌리면 macOS용 바이너리만 들어오고, 서버에서 실행하면 적절한 바이너리가 없어서 터진다. 이걸 schema.prisma의 generator 블록에 binaryTargets로 명시해줘야 해결된다.

generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "debian-openssl-3.0.x"]
}

"native"는 현재 빌드 환경(로컬)에 맞게 자동 감지, "debian-openssl-3.0.x"는 배포 환경 타깃을 명시한 것이다.

왜 debian-openssl-3.0.x인가

OpenSSL 3.0.x는 비교적 최근 LTS 배포판들이 기본으로 채택한 버전이다. Ubuntu 22.04 LTS (Jammy), Debian 12 (Bookworm) 등이 여기에 해당한다. 예전 배포판이나 일부 도커 이미지들은 openssl-1.1.x나 openssl-1.0.x를 쓰는 경우가 많았는데, 인프라가 점진적으로 올라가면서 3.0.x 환경으로 넘어오는 케이스가 늘고 있다.

이번에도 마찬가지였을 것이다. 기존에는 아마 1.1.x 계열 이미지를 쓰다가 베이스 이미지가 업데이트되거나 환경이 바뀌면서 OpenSSL 버전이 올라갔고, 그 결과 기존 binaryTargets에 명시된 바이너리와 실행 환경이 맞지 않게 됐다.

에러 메시지는 보통 이런 식이다:

PrismaClientInitializationError: 
Query engine library for current platform "debian-openssl-3.0.x" could not be found.

이 메시지를 처음 보면 당황하기 쉽다. 팀원 중 Prisma를 처음 써보는 사람이라면 "왜 갑자기 이게 안 되지?"부터 시작해서 구글링하다가 시간을 꽤 쓰게 된다.

핀포인트 수정이지만 영향은 크다

변경된 파일은 prisma/schema.prisma 하나, 변경 라인 수도 아마 한두 줄이었을 거다. 코드 변경 규모로 보면 굉장히 작은 수정이지만, 이게 없으면 배포 환경에서 DB 연결 자체가 불가능하다. 서비스 전체가 먹통이 되는 유형의 장애다.

팀장 입장에서 이런 류의 이슈는 몇 가지를 점검하게 만든다:

• CI/CD 파이프라인에서 실행 환경 명세가 코드로 관리되고 있는가
• 베이스 이미지 버전업이 사이드이펙트 없이 추적되고 있는가
• prisma generate가 어느 시점에, 어디서 실행되는가 (로컬 vs CI)

특히 prisma generate를 로컬에서만 돌리고 결과물을 커밋하는 패턴이면 이 문제가 숨어있다가 배포 시점에 터진다. CI에서 generate를 돌리면 조금 더 빨리 감지할 수 있다.

이번 fix 자체는 한 줄짜리 수정이지만, 이걸 계기로 "우리 팀이 Prisma 바이너리를 어떤 환경에서 어떻게 관리하고 있는지"를 짚어볼 만하다. 도커 베이스 이미지 버전을 올릴 때 binaryTargets도 같이 체크하는 것을 배포 체크리스트에 넣어두면 다음번엔 같은 이유로 긴급 패치 커밋이 올라오는 상황을 막을 수 있다.

끝.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.