프리즈마 ORM + PostgreSQL 궁극 가이드 (2025년판)

Source: Dev.to

프로젝트 초기화

Node.js 환경을 TypeScript와 함께 설정하는 것부터 시작합니다. 우리는 최신이고 빠른 실행을 위해 tsx를 사용합니다.

mkdir prisma-postgres-2025
cd prisma-postgres-2025
npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

Prisma 및 PostgreSQL 드라이버 설치

2025년에는 서버리스 및 엣지 환경에서 더 나은 성능을 위해 공식 PostgreSQL 어댑터를 설치하는 것이 강력히 권장됩니다.

npm install prisma --save-dev
npm install @prisma/client @prisma/adapter-pg pg

Prisma 초기화

다음 명령을 실행하여 보일러플레이트를 생성합니다. 이 명령은 prisma/schema.prisma 파일과 .env 파일을 만듭니다.

npx prisma init --datasource-provider postgresql

연결 설정

.env 파일을 엽니다. PostgreSQL 연결 문자열은 다음 형식을 따릅니다:

# Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public
DATABASE_URL="postgresql://postgres:mypassword@localhost:5432/mydb?schema=public"

최신 스키마 정의

prisma/schema.prisma 파일에서 모델을 정의합니다. 이 모델들은 데이터베이스에 대한 “프록시” 역할을 합니다.

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User    @relation(fields: [authorId], references: [id])
  authorId  Int
}

마이그레이션 적용

Prisma Migrate를 사용해 스키마를 PostgreSQL에 적용합니다. 실제 테이블이 생성되고 타입‑안전 클라이언트가 생성됩니다.

npx prisma migrate dev --name init

클라이언트 인스턴스화 (싱글톤 패턴)

PostgreSQL에서 “Too many connections”(연결 과다) 오류를 방지하려면(특히 핫‑리로드 개발 중) 다음 싱글톤 패턴을 사용합니다:

// db.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = global as unknown as { prisma: PrismaClient }

export const prisma = globalForPrisma.prisma || new PrismaClient()

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

CRUD 작업 수행

이제 완전한 타입‑안전 쿼리를 작성할 수 있습니다. Prisma가 PostgreSQL JOIN 및 관계를 자동으로 처리합니다.

import { prisma } from './db'

async function run() {
  // Create a user and a post in one transaction
  const user = await prisma.user.create({
    data: {
      email: 'hello@dev.to',
      name: 'Dev Reader',
      posts: {
        create: { title: 'Learning Prisma in 2025' }
      }
    }
  })

  // Read: Fetch all users and include their posts
  const allUsers = await prisma.user.findMany({
    include: { posts: true }
  })

  console.log(JSON.stringify(allUsers, null, 2))
}

run()

2025년 PostgreSQL의 새로운 기능

• Rust‑Free Engine: Prisma 6/7은 TypeScript 기반 엔진으로 전환되어 콜드 스타트가 빨라지고 Docker 이미지가 작아졌습니다.
• TypedSQL: .sql 파일에 순수 SQL을 작성하고 Prisma가 해당 파일에 대한 TypeScript 타입을 생성하도록 하여 순수 SQL의 힘과 ORM 안전성을 결합합니다.
• Prisma Studio: npx prisma studio를 실행해 PostgreSQL 데이터를 시각적으로 탐색할 수 있는 대시보드를 띄우세요—별도의 DB 관리 도구 없이 빠른 디버깅에 이상적입니다.
• Pro‑Tip: Supabase나 Neon 같은 호스팅 PostgreSQL 제공자를 사용할 때는 .env에 “Connection Pooling” 문자열을 넣어 고 트래픽을 효율적으로 처리하세요.