NextJS (App Router)에서 데이터베이스 연결

Source: Dev.to

소개

이 글에서는 Prisma ORM을 사용해 Next.js 애플리케이션(App Router)을 데이터베이스에 안정적으로 연결하는 방법을 살펴보겠습니다.

Prisma ORM이란?

Prisma(객체‑관계 매핑)는 데이터베이스와의 통신을 단순화합니다. MySQL, PostgreSQL, SQLite, MongoDB 등에 대해 직접 SQL을 작성하는 대신, 타입‑안전한 클라이언트를 사용해 내부 문법을 추상화합니다.

ORM 사용의 장점

• 데이터베이스마다 다른 쿼리 문법을 외울 필요가 없습니다.
• 사소한 실수로 인한 디버깅 시간을 줄여줍니다.
• 데이터베이스 교체가 쉬워집니다.

Next.js App Router에서 Prisma 연결하기

아래는 Next.js App Router와 잘 동작하는 Prisma 클라이언트의 최소하면서도 프로덕션에 적합한 설정 예시입니다.

// lib/prisma.ts
import { PrismaClient } from "@/generated/prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

const connectionString = `${process.env.DATABASE_URL}`;

const adapter = new PrismaPg({ connectionString });

export const prisma =
  globalForPrisma.prisma || new PrismaClient({ adapter });

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

작동 방식

1. 어댑터 생성 – PrismaPg는 process.env.DATABASE_URL에서 가져온 연결 문자열을 받습니다.
2. 싱글톤 패턴 – 클라이언트를 전역 변수(globalForPrisma.prisma)에 저장합니다.
   • 프로덕션에서는 동일 서버 인스턴스 내에서 요청마다 새로운 DB 연결을 만들지 않도록 같은 Prisma 인스턴스를 재사용합니다.
   • 개발 환경에서는 핫‑리로드 시마다 새 클라이언트가 생성되는 것을 방지하기 위해 전역에 저장해 하나의 연결만 열리게 합니다.

왜 이런 코드를 추가해야 할까?

Next.js 앱을 배포하면 여러 서버 인스턴스가 동시에 실행될 수 있습니다. 각 인스턴스는 많은 요청을 처리하지만, 요청마다 별도의 데이터베이스 연결을 만들고 싶지는 않습니다.

• 모듈 캐싱: Prisma 클라이언트 모듈을 import 하면 같은 서버 인스턴스 내에서 이미 생성된 인스턴스를 재사용합니다.
• 전역 저장소(개발): 개발 모드에서 핫‑모듈 교체가 발생하면 매번 새로운 클라이언트를 생성하게 되는데, 전역 캐시를 사용하면 불필요한 연결을 방지할 수 있습니다.

이 패턴을 따르면 활성 데이터베이스 연결 수를 최소화하면서도 Prisma의 타입‑안전 API를 그대로 활용할 수 있습니다.