Prisma ORM 실전 활용법: Node.js 백엔드 API 개발 가이드

현대 웹 서비스 개발에서 데이터베이스와의 상호작용은 핵심적인 부분입니다. 특히 Node.js 기반의 백엔드 API를 구축할 때, 데이터베이스 작업을 효율적이고 안전하게 관리하는 것은 프로젝트의 성패를 좌우합니다. 이러한 맥락에서 Prisma ORM은 개발자들 사이에서 차세대 ORM(Object-Relational Mapping)으로 각광받고 있으며, 뛰어난 타입 안정성과 개발 편의성을 제공합니다.

이 글에서는 Prisma ORM을 Node.js 백엔드 API 개발에 실질적으로 활용하는 방법에 대해 심층적으로 다룹니다. Prisma의 기본적인 설정부터 스키마 정의, CRUD 작업, 복잡한 관계형 데이터 관리, 트랜잭션 처리, 그리고 백엔드 아키텍처 내에서의 통합 방안까지 폭넓게 살펴보겠습니다. 이 가이드를 통해 Prisma ORM을 여러분의 프로젝트에 성공적으로 도입하고 효율적인 데이터베이스 관리 역량을 강화할 수 있기를 바랍니다.

Prisma ORM이란?

Prisma는 Node.js 및 TypeScript 환경을 위한 오픈 소스 ORM으로, 데이터베이스 작업을 타입 안전하고 개발자 친화적인 방식으로 처리할 수 있도록 돕습니다. 기존 ORM들이 객체 지향 패러다임에 중점을 두었다면, Prisma는 데이터베이스 스키마를 정의하고 이를 기반으로 강력한 타입스크립트 클라이언트를 자동으로 생성하여 개발 경험을 혁신합니다.

Prisma의 주요 구성 요소

• Prisma Schema: 데이터베이스의 모델, 필드, 관계를 정의하는 단일 진실 공급원(Single Source of Truth)입니다. 이 스키마 파일을 기반으로 Prisma Client와 마이그레이션 파일이 생성됩니다.
• Prisma Client: Prisma Schema를 기반으로 자동 생성되는 타입스크립트/자바스크립트 라이브러리입니다. 이 클라이언트를 통해 데이터베이스에 쿼리를 전송하고 결과를 타입 안전하게 받을 수 있습니다.
• Prisma Migrate: 데이터베이스 스키마 변경 사항을 관리하고 적용하는 도구입니다. 마이그레이션 파일을 생성하고 데이터베이스에 적용하여 스키마 버전을 추적할 수 있습니다.
• Prisma Studio: 데이터베이스를 시각적으로 탐색하고 데이터를 관리할 수 있는 GUI 도구입니다. 개발 및 디버깅 과정에서 매우 유용합니다.

Prisma는 PostgreSQL, MySQL, SQLite, SQL Server, MongoDB 등 다양한 데이터베이스를 지원하며, 명확하고 직관적인 API를 통해 복잡한 데이터베이스 작업을 간소화합니다.

Prisma ORM 설정 및 초기화

Prisma를 Node.js 프로젝트에 도입하는 첫 단계는 필요한 패키지를 설치하고 초기 설정을 진행하는 것입니다.

1. Prisma 패키지 설치

먼저 프로젝트 디렉토리에서 Prisma CLI와 Prisma Client를 설치합니다.

npm install prisma @prisma/client
# 또는 yarn add prisma @prisma/client

prisma 패키지는 Prisma CLI 도구를 제공하며, @prisma/client는 데이터베이스와 상호작용할 실제 클라이언트 라이브러리입니다.

2. Prisma 초기화

설치 후 npx prisma init 명령어를 실행하여 Prisma 프로젝트를 초기화합니다.

npx prisma init

이 명령어는 다음 두 가지 파일을 생성합니다:

• prisma/schema.prisma: Prisma 스키마를 정의하는 파일입니다.
• .env: 데이터베이스 연결 URL을 포함하는 환경 변수 파일입니다.

schema.prisma 파일은 다음과 같은 기본 구조를 가집니다.

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql" // 사용하는 데이터베이스에 따라 변경 (e.g., "mysql", "sqlite")
  url      = env("DATABASE_URL")
}

datasource db 블록의 provider는 사용할 데이터베이스 종류를 명시하며, url은 .env 파일에 정의된 DATABASE_URL 환경 변수를 참조합니다.

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

.env 파일에 실제 데이터베이스 연결 정보를 입력합니다. 예를 들어, PostgreSQL 데이터베이스의 경우 다음과 같이 설정할 수 있습니다.

# .env
DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"

각 데이터베이스 유형에 맞는 연결 문자열 형식은 Prisma 공식 문서를 참조하세요.

스키마(Schema) 정의 및 마이그레이션

Prisma의 핵심은 schema.prisma 파일에 데이터베이스 스키마를 명확하게 정의하는 것입니다. 이 스키마는 데이터베이스의 모델, 필드, 관계를 선언하며, 이를 기반으로 Prisma Client가 생성됩니다.

1. 모델(Model) 정의

schema.prisma 파일에 model 블록을 추가하여 데이터베이스 테이블을 정의합니다.

// prisma/schema.prisma
model User {
  id        String   @id @default(uuid())
  email     String   @unique
  name      String?
  password  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  posts     Post[]
}

model Post {
  id        String   @id @default(uuid())
  title     String
  content   String?
  published Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
}

위 예시에서는 User와 Post 두 가지 모델을 정의했습니다.

• @id: 기본 키(Primary Key)를 나타냅니다.
• @default(uuid()): 필드의 기본값을 UUID로 설정합니다.
• @unique: 고유(Unique) 제약 조건을 추가합니다.
• String?: Nullable 필드를 나타냅니다.
• @default(now()): 현재 시간을 기본값으로 설정합니다.
• @updatedAt: 레코드 업데이트 시 자동으로 현재 시간으로 갱신됩니다.
• @relation: 두 모델 간의 관계를 정의합니다. fields는 현재 모델의 외래 키 필드, references는 관계를 맺을 모델의 기본 키 필드를 지정합니다.

2. 마이그레이션(Migration) 적용

스키마를 정의한 후에는 이 스키마를 실제 데이터베이스에 반영해야 합니다. Prisma Migrate를 사용하여 마이그레이션 파일을 생성하고 적용합니다.

npx prisma migrate dev --name init

• migrate dev: 개발 환경에서 스키마 변경 사항을 추적하고 마이그레이션을 생성/적용합니다.
• --name init: 생성될 마이그레이션 파일에 이름을 부여합니다 (예: 20230101000000_init).

이 명령어를 실행하면 prisma/migrations 디렉토리에 마이그레이션 파일이 생성되고, 데이터베이스 스키마가 업데이트됩니다. 만약 간단한 스키마 변경만 있고 마이그레이션 히스토리를 관리할 필요가 없다면 npx prisma db push를 사용할 수도 있습니다.

3. Prisma Client 재생성

스키마가 변경될 때마다 Prisma Client를 최신 상태로 유지해야 합니다. migrate dev 명령어는 자동으로 클라이언트를 재생성하지만, 수동으로 재생성해야 할 경우 다음 명령어를 사용합니다.

npx prisma generate

Prisma Client 활용: CRUD 작업

Prisma Client는 타입 안전한 방식으로 데이터베이스에 접근하여 CRUD(Create, Read, Update, Delete) 작업을 수행할 수 있도록 해줍니다.

1. Prisma Client 인스턴스 생성

일반적으로 애플리케이션의 진입점에서 Prisma Client 인스턴스를 생성하고 전역적으로 사용합니다.

// src/lib/prisma.ts
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export default prisma;

2. 데이터 생성 (Create)

create 메서드를 사용하여 새로운 레코드를 생성합니다.

// src/services/userService.ts
import prisma from '../lib/prisma';

async function createUser(email: string, name: string, passwordHash: string) {
  const user = await prisma.user.create({
    data: {
      email,
      name,
      password: passwordHash,
    },
  });
  console.log('Created user:', user);
  return user;
}

// Nested Write 예시 (사용자 생성과 동시에 게시물 생성)
async function createUserWithPost(email: string, name: string, passwordHash: string, postTitle: string) {
  const user = await prisma.user.create({
    data: {
      email,
      name,
      password: passwordHash,
      posts: {
        create: {
          title: postTitle,
          content: 'This is the first post content.',
        },
      },
    },
  });
  console.log('Created user with post:', user);
  return user;
}

3. 데이터 조회 (Read)

findUnique, findMany, findFirst 등의 메서드를 사용하여 데이터를 조회합니다.

// src/services/postService.ts
import prisma from '../lib/prisma';

async function getAllPosts() {
  const posts = await prisma.post.findMany();
  console.log('All posts:', posts);
  return posts;
}

async function getPostById(postId: string) {
  const post = await prisma.post.findUnique({
    where: { id: postId },
  });
  console.log('Post by ID:', post);
  return post;
}

async function getPublishedPosts() {
  const publishedPosts = await prisma.post.findMany({
    where: { published: true },
    orderBy: { createdAt: 'desc' },
    select: {
      id: true,
      title: true,
      author: {
        select: { name: true, email: true },
      },
    },
  });
  console.log('Published posts:', publishedPosts);
  return publishedPosts;
}

select를 사용하면 필요한 필드만 선택하여 네트워크 부하를 줄일 수 있습니다.

4. 데이터 업데이트 (Update)

update 또는 updateMany 메서드를 사용하여 데이터를 업데이트합니다.

import prisma from '../lib/prisma';

async function updatePostTitle(postId: string, newTitle: string) {
  const updatedPost = await prisma.post.update({
    where: { id: postId },
    data: { title: newTitle },
  });
  console.log('Updated post:', updatedPost);
  return updatedPost;
}

async function publishAllPostsByUser(userId: string) {
  const { count } = await prisma.post.updateMany({
    where: { authorId: userId },
    data: { published: true },
  });
  console.log(`${count} posts published for user ${userId}`);
  return count;
}

5. 데이터 삭제 (Delete)

delete 또는 deleteMany 메서드를 사용하여 데이터를 삭제합니다.

import prisma from '../lib/prisma';

async function deletePost(postId: string) {
  const deletedPost = await prisma.post.delete({
    where: { id: postId },
  });
  console.log('Deleted post:', deletedPost);
  return deletedPost;
}

async function deleteAllUnpublishedPosts() {
  const { count } = await prisma.post.deleteMany({
    where: { published: false },
  });
  console.log(`${count} unpublished posts deleted.`);
  return count;
}

관계형 데이터 관리

Prisma는 관계형 데이터베이스의 복잡한 관계를 효과적으로 관리할 수 있는 기능을 제공합니다.

1. include를 사용한 관계 데이터 로딩

모델 간의 관계를 스키마에 정의했다면, include 옵션을 사용하여 관련 데이터를 함께 조회할 수 있습니다.

import prisma from '../lib/prisma';

async function getUserWithPosts(userId: string) {
  const userWithPosts = await prisma.user.findUnique({
    where: { id: userId },
    include: {
      posts: true, // User와 연결된 모든 Post를 함께 가져옵니다.
    },
  });
  console.log('User with posts:', userWithPosts);
  // userWithPosts.posts 배열에 게시물 데이터가 포함됩니다.
  return userWithPosts;
}

async function getPostWithAuthor(postId: string) {
  const postWithAuthor = await prisma.post.findUnique({
    where: { id: postId },
    include: {
      author: {
        select: { name: true, email: true }, // author 객체에서 name과 email만 선택
      },
    },
  });
  console.log('Post with author:', postWithAuthor);
  // postWithAuthor.author 객체에 저자 데이터가 포함됩니다.
  return postWithAuthor;
}

include는 중첩될 수 있어 복잡한 관계도 한 번의 쿼리로 가져올 수 있습니다.

2. Nested Writes (중첩 쓰기)

Prisma는 관계형 데이터를 한 번의 작업으로 생성, 업데이트, 삭제할 수 있는 Nested Writes 기능을 지원합니다.

• 생성 시 중첩 쓰기: 위 createUserWithPost 예시처럼 사용자를 생성하면서 동시에 게시물을 생성할 수 있습니다.
• 업데이트 시 중첩 쓰기:

import prisma from '../lib/prisma';

async function updateUserAndAddPost(userId: string, newName: string, postTitle: string) {
  const updatedUser = await prisma.user.update({
    where: { id: userId },
    data: {
      name: newName,
      posts: {
        create: {
          title: postTitle,
          content: 'New post added during user update.',
        },
      },
    },
  });
  console.log('Updated user and added post:', updatedUser);
  return updatedUser;
}

Nested Writes는 여러 테이블에 걸쳐 데이터를 변경해야 하는 복잡한 시나리오에서 코드의 간결성과 일관성을 유지하는 데 큰 도움이 됩니다.

트랜잭션(Transactions) 처리

데이터베이스 트랜잭션은 여러 데이터베이스 작업이 하나의 논리적인 단위로 처리되도록 보장하여 데이터의 일관성과 무결성을 유지하는 데 필수적입니다. Prisma는 두 가지 유형의 트랜잭션을 지원합니다.

1. Interactive Transactions

Prisma 2.19부터 도입된 Interactive Transactions는 여러 Prisma Client 작업(쿼리)을 단일 트랜잭션으로 묶어 실행할 수 있게 해줍니다. 이 방식은 실행 순서에 따라 의존성이 있는 작업들을 처리할 때 유용합니다.

import prisma from '../lib/prisma';

async function transferFunds(fromAccountId: string, toAccountId: string, amount: number) {
  await prisma.$transaction(async (tx) => {
    // 1. 출금 계좌 잔액 확인 및 차감
    const fromAccount = await tx.account.findUnique({
      where: { id: fromAccountId },
    });

    if (!fromAccount || fromAccount.balance < amount) {
      throw new Error('잔액이 부족하거나 계좌를 찾을 수 없습니다.');
    }

    await tx.account.update({
      where: { id: fromAccountId },
      data: { balance: { decrement: amount } },
    });

    // 2. 입금 계좌 잔액 증가
    await tx.account.update({
      where: { id: toAccountId },
      data: { balance: { increment: amount } },
    });

    // 3. 거래 내역 기록 (예시)
    await tx.transactionRecord.create({
      data: {
        fromAccountId,
        toAccountId,
        amount,
        type: 'TRANSFER',
      },
    });
  });

  console.log(`Successfully transferred ${amount} from ${fromAccountId} to ${toAccountId}`);
}

prisma.$transaction(async (tx) => { ... }) 내의 모든 작업은 tx (트랜잭션 클라이언트)를 통해 실행되어야 하며, 이 블록 안의 모든 작업이 성공하면 커밋되고, 하나라도 실패하면 롤백됩니다.

2. Batch Transactions

동일한 모델에 대해 여러 개의 독립적인 쓰기 작업을 한 번에 실행해야 할 때 Batch Transactions를 사용할 수 있습니다. 이는 성능 최적화에 도움이 됩니다.

import prisma from '../lib/prisma';

async function updateMultipleUsersStatus(userIds: string[], status: boolean) {
  const results = await prisma.$transaction([
    prisma.user.update({
      where: { id: userIds[0] },
      data: { isActive: status },
    }),
    prisma.user.update({
      where: { id: userIds[1] },
      data: { isActive: status },
    }),
    // ... 더 많은 업데이트 작업
  ]);

  console.log('Batch update results:', results);
  return results;
}

Batch Transactions는 모든 작업이 성공해야 커밋되고, 하나라도 실패하면 모든 작업이 롤백됩니다.

고급 활용 팁

Prisma는 기본적인 CRUD 외에도 다양한 고급 기능을 제공하여 복잡한 쿼리 및 데이터 처리 요구사항을 충족시킵니다.

1. 필터링, 정렬, 페이지네이션

where, orderBy, skip, take, cursor 옵션을 조합하여 정교한 데이터 조회 기능을 구현할 수 있습니다.

import prisma from '../lib/prisma';

async function getPaginatedPosts(page: number = 1, pageSize: number = 10, searchKeyword?: string) {
  const skip = (page - 1) * pageSize;

  const posts = await prisma.post.findMany({
    where: {
      published: true,
      // 검색 키워드가 있을 경우 title 또는 content에 포함된 게시물 필터링
      OR: searchKeyword
        ? [
            { title: { contains: searchKeyword, mode: 'insensitive' } },
            { content: { contains: searchKeyword, mode: 'insensitive' } },
          ]
        : undefined,
    },
    orderBy: { createdAt: 'desc' },
    skip: skip,
    take: pageSize,
    include: { author: { select: { name: true } } },
  });

  const totalCount = await prisma.post.count({
    where: {
      published: true,
      OR: searchKeyword
        ? [
            { title: { contains: searchKeyword, mode: 'insensitive' } },
            { content: { contains: searchKeyword, mode: 'insensitive' } },
          ]
        : undefined,
    },
  });

  return {
    posts,
    totalCount,
    currentPage: page,
    totalPages: Math.ceil(totalCount / pageSize),
  };
}

2. Raw 쿼리

Prisma Client로 표현하기 어려운 복잡한 쿼리나 특정 데이터베이스 기능이 필요할 경우 $queryRaw 또는 $executeRaw를 사용하여 Raw SQL 쿼리를 실행할 수 있습니다.

import prisma from '../lib/prisma';
import { Prisma } from '@prisma/client';

async function getPostCountPerUser() {
  const result = await prisma.$queryRaw(Prisma.sql`
    SELECT
      u.name,
      COUNT(p.id)::int AS postCount
    FROM "User" u
    LEFT JOIN "Post" p ON u.id = p."authorId"
    GROUP BY u.name
    ORDER BY postCount DESC;
  `);
  console.log('Post count per user:', result);
  return result;
}

async function customUpdateRaw(postId: string, newContent: string) {
  const affectedRows = await prisma.$executeRaw(Prisma.sql`
    UPDATE "Post"
    SET content = ${newContent}, "updatedAt" = NOW()
    WHERE id = ${postId};
  `);
  console.log(`Affected rows: ${affectedRows}`);
  return affectedRows;
}

Prisma.sql 태그드 템플릿 리터럴을 사용하면 SQL 인젝션 공격을 방지하고 쿼리를 안전하게 구성할 수 있습니다.

Prisma ORM과 백엔드 아키텍처

Prisma ORM은 Node.js 기반의 Express, NestJS 등 다양한 백엔드 프레임워크와 잘 통합됩니다. 백엔드 아키텍처 내에서 Prisma를 효과적으로 활용하는 방법을 살펴보겠습니다.

1. 아키텍처 다이어그램

일반적인 계층형 아키텍처에서 Prisma Client는 데이터 접근 계층(Repository Layer)에서 사용됩니다.

+---------------------------+       +---------------------------------+
|     Client / Frontend     |       |       API Gateway /             |
|                           |       |       Load Balancer             |
+---------------------------+       +---------------------------------+
             |                                    |
             V                                    V
+---------------------------------------------------------------------+
|                     Backend Service (e.g., Node.js/Express/NestJS)  |
|                                                                     |
|  +---------------------+                                            |
|  |     Controller      |  <-- Handles HTTP requests, calls service |
|  +---------------------+                                            |
|             |                                                        |
|             V                                                        |
|  +---------------------+                                            |
|  |    Service Layer    |  <-- Business logic, orchestrates data    |
|  +---------------------+      operations, calls repository         |
|             |                                                        |
|             V                                                        |
|  +---------------------+                                            |
|  |   Repository Layer  |  <-- Data access logic, uses Prisma Client|
|  +---------------------+                                            |
|             |                                                        |
|             V                                                        |
|  +---------------------+                                            |
|  |    Prisma Client    |  <-- Generated ORM for database interaction|
|  +---------------------+--------------------------------------------+
|             |                                                        |
|             V                                                        |
+---------------------------------------------------------------------+
|                      Database (PostgreSQL, MySQL, etc.)             |
+---------------------------------------------------------------------+

• Controller Layer: 클라이언트의 요청을 받아 유효성을 검사하고, 비즈니스 로직을 수행할 서비스 계층의 메서드를 호출합니다.
• Service Layer: 핵심 비즈니스 로직을 구현합니다. 여러 Repository 메서드를 조합하여 복잡한 작업을 수행할 수 있으며, 트랜잭션 관리도 이 계층에서 이루어질 수 있습니다.
• Repository Layer: 데이터베이스와 직접 상호작용하는 계층입니다. Prisma Client를 사용하여 CRUD 작업을 수행하며, 서비스 계층에 추상화된 데이터 접근 인터페이스를 제공합니다.

2. Repository Pattern 적용

Repository Pattern을 적용하면 데이터베이스 구현 세부 사항으로부터 비즈니스 로직을 분리하여 코드의 유연성과 테스트 용이성을 높일 수 있습니다.

// src/repositories/userRepository.ts
import prisma from '../lib/prisma';
import { User, Prisma } from '@prisma/client';

export interface UserRepository {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  create(data: Prisma.UserCreateInput): Promise<User>;
  update(id: string, data: Prisma.UserUpdateInput): Promise<User>;
  delete(id: string): Promise<User>;
}

export class PrismaUserRepository implements UserRepository {
  async findById(id: string): Promise<User | null> {
    return prisma.user.findUnique({ where: { id } });
  }

  async findByEmail(email: string): Promise<User | null> {
    return prisma.user.findUnique({ where: { email } });
  }

  async create(data: Prisma.UserCreateInput): Promise<User> {
    return prisma.user.create({ data });
  }

  async update(id: string, data: Prisma.UserUpdateInput): Promise<User> {
    return prisma.user.update({ where: { id }, data });
  }

  async delete(id: string): Promise<User> {
    return prisma.user.delete({ where: { id } });
  }
}

// src/services/authService.ts
import { PrismaUserRepository } from '../repositories/userRepository';
import bcrypt from 'bcrypt';

export class AuthService {
  private userRepository: PrismaUserRepository;

  constructor(userRepository: PrismaUserRepository) {
    this.userRepository = userRepository;
  }

  async registerUser(email: string, name: string, passwordPlain: string) {
    const existingUser = await this.userRepository.findByEmail(email);
    if (existingUser) {
      throw new Error('User with this email already exists.');
    }

    const hashedPassword = await bcrypt.hash(passwordPlain, 10);
    const newUser = await this.userRepository.create({
      email,
      name,
      password: hashedPassword,
    });

    // 민감한 정보 제외 후 반환
    const { password, ...userWithoutPassword } = newUser;
    return userWithoutPassword;
  }

  // ... 로그인 로직 등
}

이렇게 Repository Pattern을 사용하면 서비스 계층은 데이터베이스 구현에 의존하지 않고 UserRepository 인터페이스에만 의존하게 됩니다. 나중에 다른 ORM이나 Raw SQL로 변경하더라도 서비스 계층 코드를 크게 수정할 필요 없이 PrismaUserRepository 구현체만 교체하면 됩니다.

마무리

Prisma ORM은 Node.js 및 TypeScript 기반 백엔드 API 개발에서 데이터베이스 상호작용을 혁신하는 강력한 도구입니다. 타입 안정성, 직관적인 스키마 정의, 강력한 마이그레이션 도구, 그리고 개발자 친화적인 API는 개발 생산성을 크게 향상시키고 유지보수성을 높이는 데 기여합니다.

이 글에서 다룬 기본적인 설정부터 CRUD 작업, 관계형 데이터 관리, 트랜잭션 처리, 그리고 고급 활용 팁 및 백엔드 아키텍처 통합 방안까지 익히신다면, Prisma ORM을 여러분의 프로젝트에 성공적으로 적용하고 견고한 백엔드 시스템을 구축하는 데 큰 도움이 될 것입니다. Prisma와 함께 더욱 효율적이고 안정적인 데이터베이스 기반 애플리케이션을 만들어나가시기를 바랍니다.