[Next.js] Prisma ORM 사용 이유 & 기본 사용법

Lui.Slki·2026년 4월 6일
ORMnext.jsprisma

Next.js

목록 보기
2/2

Next.js 프로젝트를 진행하면서 데이터베이스를 코드로 다루기 위해 Prisma를 사용했다.
Prisma는 Node.js 와 TypeScript 환경에서 사용할 수 있는 ORM이며, 타입 안전한 데이터 접근, 스키마 기반 모델링, 마이그레이션 관리, GUI 기반 데이터 확인 도구까지 함께 제공한다.
Prisma 공식 문서에서도 Prisma ORM을 타입 안전한 데이터 접근, 마이그레이션, 시각적 데이터 편집 기능을 제공하는 ORM으로 설명한다.

*ORM(Object Relational Mapping) : RDBMS의 테이블을 코드 상의 객체처럼 다룰 수 있게 해주는 기술
*마이그레이션(Migration) : DB 스키마 변경 사항을 기록하고 적용하는 작업
*GUI(Graphical User Interface) : 아이콘, 버튼, 창 같은 시각적 요소를 통해 사용자가 기능을 쉽게 조작할 수 있도록 만든 인터페이스

Prisma ORM 공식 문서

Prisma란 무엇인가

Prisma는 공식적으로 Node.js와 TypeScript를 위한 차세대 ORM으로 소개된다.
PostgreSQL, MySQL, SQL Server, MongoDB, CockroachDB 등 여러 데이터베이스를 지원하며, 핵심 구성은 보통 세 가지로 나뉜다.
Prisma Client, Prisma Migrate, Prisma Studio가 대표적이다.

각 역할은 다음과 같다.

  • Prisma Client: Prisma schema를 기반으로 생성되는 타입 안전한 ORM 인터페이스. 코드에서 findMany, create, update 같은 방식으로 DB를 다룰 수 있다.
  • Prisma Migrate: 스키마 변경을 migration 파일로 관리하고, 개발 및 운영 환경에 반영하는 도구.
  • Prisma Studio: 브라우저 기반 GUI에서 데이터를 조회하고 수정할 수 있는 도구.

즉, Prisma는 단순한 "Query 헬퍼" 가 아니라, 데이터 모델 정의부터 쿼리 실행, 변경 이력 관리까지 한 흐름으로 가져가는 도구로 취급한다.

Next.js 에서 Prisma를 쓰는 이유

Next.js는 프론트엔드 프레임워크처럼 보이지만, 실제로는 서버 컴포넌트, 서버 액션, Route Handler, API Route 등 서버 로직도 함께 다루는 풀스택 구조에 가깝다. Prisma는 이런 환경에서 특히 잘 맞는다.
Prisma 공식 가이드도 Next.js에서 Prisma를 설정하고, 마이그레이션을 다루고, 배포하는 흐름을 별도로 제공한다.

해당 공식 문서

Prisma를 선택한 이유는 크게 네 가지다.

1. 타입 안정성이 좋다 💭

Prisma Client는 Prisma schema를 바탕으로 자동 생성된다.
그래서 모델 필드명이나 타입이 바뀌면 TypeScript에서 바로 감지할 수 있는 경우가 많다.
문자열 기반 쿼리를 직접 흩뿌리는 것보다 훨씬 안정적이다.
Prisma는 Prisma Client를 auto-generated, type-safe ORM Interface로 설명한다.

2. 모델 구조를 코드로 관리할 수 있다 💭

Prisma에서는 schema.prisma 파일에 데이터 모델을 정의한다.
이 말은 즉, 데이터베이스 구조가 코드 레벨에서 관리된다는 뜻이다. 모델 정의가 프로젝트 안에 명시적으로 남기 때문에, 구조를 파악하기도 쉽고 팀원과 공유하기도 좋다.
Prisma schema API는 datasource, generator, model 등을 Prisma schema 언어로 정의하도록 안내한다.

3. 마이그레이션 이력을 남길 수 있다 💭

스키마 변경이 생길 때마다 migration 파일을 생성해 이력을 남길 수 있다.
단순히 "테이블 바뀜"이 아닌 어떤 변경이 어떤 순서로 있었는지 Git에 함께 남길 수도 있다는 뜻이다.
Prisma Migrate는 SQL migration 파일 히스토리를 생성하고, Git 저장소에서 관리할 수 있게 해 준다.

4. Next.js와 공식 가이드가 잘 갖춰져 있다💭

Prisma는 Next.js용 공식 가이드를 제공하고, App Router 환경과 배포 흐름까지 다룬다.
즉, 레퍼런스가 잘 정리되어 있고 문제가 생겼으 때 공식 자료를 찾기도 쉽다.

Prisma 기본 구조

Prisma를 처음 붙이면 보통 프로젝트 안에 prisma/schema.prisma 파일이 생긴다.
여기서 datasource, generator, model을 정의한다. Prisma 공식 문서는 prisma init 실행 시 Prisma 프로젝트 자산을 초기화하고, prisma.config.ts 역시 Prisma CLI 설정 파일로 사용할 수 있다고 설명한다.

예시 코드
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

이렇게 정의한 뒤 Prisma Client를 생성하면 코드에서 다음처럼 사용할 수 있다.

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

const users = await prisma.user.findMany();

const createdUser = await prisma.user.create({
  data: {
    email: "test@example.com",
    name: "Lui",
  },
});

Prisma Client는 schema를 기준으로 생성되기 때문에, 모델 이름과 필드에 맞춰 타입이 따라온다. 그게 Prisma를 사용하는 가장 크게 체감한 장점 중 하나다.

Prisma를 사용할 때의 기본 흐름

Next.js 프로젝트에서 Prisma를 사용할 때 보통 흐름은 아래와 같다.

  1. Prisma 설치 및 초기화
  2. schema.prisma 에 모델 정의
  3. Prisma Client 생성
  4. 스키마를 DB에 반영
  5. 코드에서 Prisma Client 사용
  6. 데이터 확인이 필요하면 Prisma Studio 실행

이 흐름은 Prisma CLI와 Next.js 공식 가이드에서 안내하는 전형적인 패턴과 맞닿아 있다.

db push 와 migrate dev 차이

npx prisma db push
db push는 현재 Prisma schema 상태를 migration 없이 db에 반영한다.
이는 프로토타이핑이나 로컬 개발에 적합하다.

npx prisma migrate dev
migrate dev는 스키마 변경을 기반으로 migration 파일 히스토리를 생성하고 개발 DB 스키마를 Prisma schema와 동기화 시켜준다.

즉, 협업이나 운영 배포까지 생각한다면 보통 migrate dev 가 더 적절하다.
빠른 실험은 db push , 이력 관리가 필요한 개발은 migrate dev 라고 구분하면 이해하기 쉽다.

*shadow database는 왜 생기나

Prisma를 쓰다 보면 migrate dev 실행 중 shadow database 관련 메시지를 볼 수 있다.
이건 Prisma가 문제를 일으키는 게 아니라, 스키마 드리프트나 잠재적인 데이터 손실 가능성을 감지하기 위해 임시 데이터베이스를 사용하는 동작이다.
Prisma 문서에 따르면 shadow database는 prisma migrate dev 실행 시 자동 생성 및 삭제되며, migration 문제 감지에 사용된다.

사고를 미리 막기위해 검사하는 안전장치 정도로 이해하면 된다.

자주 쓰는 Prisma 명령어 정리 💭

  1. Prisma 초기화
npx prisma init
  • Prisma 프로젝트 자산 초기화
  • 보통 prisma/ 디렉터리와 기본 설정 파일들이 생성됨
  • 프로젝트 셋업 명령
  1. Prisma Client 생성
npx prisma generate
  • Prisma schema를 바탕으로 Prisma Client를 생성
  • 모델 수정 후 Client를 다시 생성해야할 때 자주 사용
  • artifacts 생성 명령
  1. 스키마를 DB에 바로 반영
npx prisma db push
  • 마이그레이션 없이 스키마 상태를 DB에 반영
  • 프로토타이핑이나 로컬 초기 개발에 유용
  1. 개발용 migration 생성 및 적용
npx prisma migrate dev
  • 스키마 변경을 기준으로 마이그레이션 파일을 만들고 개발 DB에 적용한다.
  • 개발 환경에서 가장 자주 쓰는 명령어 중 하나다.
  1. 운영 환경에 migration 적용
npx prisma migrate deploy
  • 이미 생성된 migration 파일들을 운영 데이터베이스에 적용한다.(supabase 같은)
  • Prisma Migrate는 개발과 운영에서 migration history를 다루는 역할을 한다.
  1. 데이터 GUI 확인
npx prisma studio
  • 브라우저 GUI에서 데이터를 조회/수정 가능
  • 테이블 상태를 빨리 확인할 때 편하다
  1. 현재 DB 기준으로 schema 가져오기
npx prisma db pull
  • 이미 존재하는 데이터베이스 구조를 기준으로 Prisma schema를 업데이트할 때 사용
  1. schema 포맷 정리
npx prisma format
  • schema.prisma 파일을 포맷팅한다.
  1. migration 차이 비교
npx prisma migrate diff
  • migration 간 차이나 schema 차이를 비교할 때 사용한다.
  • 스키마 상태 점검에 유용

실제 자주 쓰게 되었던 흐름

실제 개발에 사용해보니 이러한 흐름으로 가게 되었다.

  • 모델을 수정한다.
  • 빠르게 반영 -> npx prisma db push 사용
  • 구조가 확정되었음 -> npx prisma migrate dev --name... 로 migration 파일을 남긴다
  • 필요하면 npx prisma generate로 Client를 다시 생성하고, npx prisma studio 로 데이터를 눈으로 확인한다.
npx prisma init
npx prisma generate
npx prisma db push
npx prisma migrate dev --name init
npx prisma studio

마무리

Prisma를 사용하면서 가장 좋았던 점은, 코드와 함께 관리하는 구조로 바꿔준다는 점이었다.

모델을 schema로 정의하고, Client를 통해 타입 안전하게 접근하고, migration 파일로 이력을 남기고, Studio로 바로 데이터를 확인할 수 있다는 점이 Next.Js 프로젝트와 잘 맞았다.

특히 Next.js처럼 프론트와 서버 로직이 가까이 붙어있는 환경에서는 Prisma가 더 편하게 느껴졌다.
DB 구조와 애플리케이션 코드가 따로 노는 게 아니라, 하나의 흐름으로 연결되었기 때문이다.

개인적으로는 DB를 처음부터 서버 환경에서만 직접 관리하는 방식보다, 로컬에서 먼저 검증하고 migration 파일로 변경 이력을 남기는 방식이 더 안정적이라고 느꼈다.
배포된 DB에 바로 둩어 수정하는 방식은 빠를 수는 있지만, 구조 변경이 누적될수록 추적과 관리가 어려워질 수 있다.
Prisma를 사용한 이유도 바로 이런 점 때문이었고, 단순한 쿼리 편의성보다 스키마를 더 일관되게 관리할 수 있다는 점이 특히 크게 느껴졌다.

profile
Lui.Slki
이전 포스트

[Next.js] 첫 시작(feat. newProject)

0개의 댓글