Gitsunmin

TIL

TIL
(=Today I Learned)

Prisma ORM

해당 문서는 Gemini 를 사용하여 대화한 내용을 요약한 것임을 밝힙니다.

목차

  1. Prisma 개요 및 최신 v7.x의 특징
  2. Prisma의 3대 핵심 구성 요소
  3. 데이터베이스 연결 및 Datasource 설정
  4. Prisma Schema Language(PSL) 상세 문법
  5. Prisma Client 주요 메서드와 활용법
  6. Prisma Migrate를 이용한 스키마 관리
  7. Prisma Studio를 통한 시각적 데이터 관리
  8. 환경 분리 및 위기 대처 전략

1. Prisma 개요 및 최신 v7.x의 특징

Prisma는 Node.js와 TypeScript 환경에서 사용할 수 있는 차세대 ORM입니다. 스키마 중심(Schema-First) 접근 방식을 통해 개발 생산성과 타입 안전성을 동시에 제공합니다.

최신 버전(v7.x)의 주요 변화

  • Rust-Free 엔진 전환: 기존의 무거운 Rust 바이너리 엔진 대신 순수 JavaScript/TypeScript 기반 런타임으로 전환되었습니다.
  • 초경량 번들: 바이너리가 제거되면서 번들 크기가 약 90% 감소하여 서버리스 및 에지 컴퓨팅(Vercel, Cloudflare 등) 환경에 최적화되었습니다.
  • 성능 극대화: 쿼리 실행 속도가 비약적으로 향상되었으며, 콜드 스타트 이슈가 크게 개선되었습니다.
  • 멀티 파일 스키마 정식 지원: prisma/schema/ 폴더 내에 여러 .prisma 파일을 나누어 관리할 수 있어 대규모 프로젝트의 유지보수성이 향상되었습니다.

2. Prisma의 3대 핵심 구성 요소

  1. Prisma Client: 애플리케이션에서 DB에 쿼리를 날리는 타입 안전한 쿼리 빌더입니다.
  2. Prisma Migrate: 스키마 정의를 실제 DB 구조로 변환하고 변경 이력을 관리하는 도구입니다.
  3. Prisma Studio: DB 데이터를 브라우저에서 시각적으로 관리할 수 있는 GUI 도구입니다.

3. 데이터베이스 연결 및 Datasource 설정

Prisma는 schema.prisma를 통해 데이터베이스와 연결됩니다.

Datasource 및 Connection URL

  • Datasource: 데이터 원천을 정의하며 provider(DB 종류)와 url(접속 주소)을 포함합니다.
  • URL 구조: postgresql://USER:PASSWORD@HOST:PORT/DATABASE 형태이며, 이는 리모컨(Client)이 원격지의 서버(DB)를 제어하기 위한 통로 역할을 합니다.
  • Connection Pooling: DB 연결 자원을 효율적으로 쓰기 위해 미리 연결을 만들어두는 기술입니다. 서버리스 환경에서는 연결 제한 방지를 위해 필수적으로 고려해야 합니다.

4. Prisma Schema Language(PSL) 상세 문법

모델 속성 및 함수

  • @id vs @unique: @id는 모델당 하나인 기본 키(PK)이며, @unique는 중복을 허용하지 않는 고유 키입니다.
  • 내장 함수: @default() 내에 autoincrement(), now(), uuid(), cuid() 등을 사용하여 기본값을 자동 생성합니다.
  • @db 속성: @db.Text나 @db.VarChar(255)와 같이 특정 DB의 네이티브 타입을 명시적으로 지정할 때 사용합니다.

매핑 및 인덱스

  • @map & @@map: DB의 컬럼명이나 테이블명이 코드상의 이름과 다를 때 매핑합니다. (예: createdAt -> created_at)
  • @@index: 여러 필드를 묶어 복합 인덱스를 생성하여 검색 성능을 최적화합니다.

5. Prisma Client 주요 메서드와 활용법

  • upsert: 데이터 존재 여부에 따라 Update 또는 Insert를 자동 선택합니다.
  • include vs select: include는 관계 모델 전체를, select는 특정 필드만 선택하여 가져옵니다. (동시 사용 불가)
  • Fluent API: prisma.user.findUnique({..}).posts() 처럼 체이닝을 통해 관계 데이터를 직관적으로 조회합니다.
  • $transaction: 여러 쿼리를 하나의 작업 단위로 묶어 무결성을 보장합니다.

6. Prisma Migrate를 이용한 스키마 관리

마이그레이션은 설계도와 실제 DB 상태를 동기화하는 ‘타임머신’ 역할을 합니다.

  • npx prisma migrate dev: 개발 단계에서 변경 사항을 기록(SQL 생성)하고 반영합니다.
  • npx prisma migrate deploy: 운영 단계에서 이미 검증된 마이그레이션 파일들을 순서대로 적용합니다.
  • _prisma_migrations: DB 내부에 자동 생성되는 테이블로, 어떤 마이그레이션이 실행되었는지 관리합니다.

7. Prisma Studio를 통한 시각적 데이터 관리

npx prisma studio 명령어로 실행하며, 복잡한 SQL 없이 데이터를 조작합니다.

  • 엑셀 방식 CRUD: 셀 더블 클릭으로 수정하고 상단의 ‘Save Changes’로 일괄 반영합니다.
  • 관계 데이터 제어: 관계된 레코드를 팝업이나 탭을 통해 즉시 확인하고 연결할 수 있습니다.
  • 필터 및 정렬: 대량의 데이터 중 필요한 조건만 빠르게 추출하여 검토할 수 있습니다.

8. 환경 분리 및 위기 대처 전략

환경 분리

  • .env 활용: 개발용과 운영용 DB URL을 분리합니다. CI/CD 환경에서는 보안을 위해 플랫폼의 환경 변수 관리 기능을 사용합니다.
  • dotenv-cli: npx dotenv -e .env.production -- npx prisma migrate deploy와 같이 실행 시점에 환경 파일을 명시적으로 지정할 수 있습니다.

위기 대처 명령어

  • status: 현재 마이그레이션 상태가 정상인지 진단합니다.
  • resolve: 마이그레이션이 실패하여 DB 상태가 고정되었을 때 수동으로 해결합니다.
  • reset: 로컬 환경에서 모든 데이터를 밀고 처음부터 다시 시작할 때 사용합니다. (운영 서버 사용 금지)
  • db pull: 이미 구축된 DB에서 역으로 스키마 파일을 추출할 때 사용합니다.