Drizzle ORM 디자인 패턴 완벽 가이드

TypeScript와 완벽하게 통합되는 Drizzle ORM의 핵심 디자인 패턴을 학습합니다. 타입 안전성과 성능을 모두 잡은 현대적인 데이터베이스 접근 방식을 익힐 수 있습니다.

---

---

들어가며

이 글에서는 Drizzle ORM 디자인 패턴 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. 스키마_정의_패턴
2. 관계_정의_패턴
3. 선택적_조회_패턴
4. 필터링_패턴
5. 조인_패턴
6. 삽입_패턴
7. 업데이트_패턴
8. 트랜잭션_패턴
9. Prepared_Statements_패턴
10. 서브쿼리_패턴
11. 마이그레이션_패턴
12. 타입_추론_패턴

---

1. 스키마 정의 패턴

개요

Drizzle의 타입 안전한 스키마 정의 방법입니다. pgTable을 사용하여 테이블 구조를 명확하게 선언합니다.

코드 예제

import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  createdAt: timestamp('created_at').defaultNow()
});

설명

각 컬럼의 타입과 제약조건을 체이닝 방식으로 정의하며, TypeScript가 자동으로 타입을 추론합니다.

---

2. 관계 정의 패턴

개요

테이블 간의 관계를 relations 함수로 명시적으로 정의하는 패턴입니다.

코드 예제

import { relations } from 'drizzle-orm';

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts)
}));

export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, {
    fields: [posts.authorId],
    references: [users.id]
  })
}));

설명

one-to-many, many-to-one 관계를 타입 안전하게 정의하여 조인 쿼리에서 자동완성을 지원합니다.

---

3. 선택적 조회 패턴

개요

필요한 컬럼만 선택하여 조회하는 성능 최적화 패턴입니다.

코드 예제

import { db } from './db';

const result = await db.select({
  id: users.id,
  name: users.name,
  email: users.email
}).from(users).where(eq(users.id, 1));

설명

select 객체에 필요한 필드만 명시하여 불필요한 데이터 전송을 방지하고 타입을 정확하게 추론합니다.

---

4. 필터링 패턴

개요

다양한 조건 연산자를 사용한 타입 안전한 필터링 패턴입니다.

코드 예제

import { eq, and, like, gte } from 'drizzle-orm';

const activeUsers = await db.select()
  .from(users)
  .where(and(
    gte(users.createdAt, new Date('2024-01-01')),
    like(users.email, '%@gmail.com')
  ));

설명

eq, like, gte 등의 연산자를 조합하여 복잡한 조건을 가독성 있게 표현합니다.

---

5. 조인 패턴

개요

leftJoin을 사용하여 관련 데이터를 한 번에 조회하는 패턴입니다.

코드 예제

const usersWithPosts = await db.select()
  .from(users)
  .leftJoin(posts, eq(users.id, posts.authorId))
  .where(eq(users.id, 1));

설명

명시적인 조인 조건으로 관계된 데이터를 효율적으로 가져오며, 결과는 중첩된 객체로 반환됩니다.

---

6. 삽입 패턴

개요

insert 메서드로 새로운 레코드를 추가하는 타입 안전한 패턴입니다.

코드 예제

const newUser = await db.insert(users)
  .values({
    name: 'John Doe',
    email: 'john@example.com'
  })
  .returning();

설명

values의 타입이 스키마로부터 자동 추론되며, returning()으로 삽입된 레코드를 즉시 반환받습니다.

---

7. 업데이트 패턴

개요

update 메서드로 기존 레코드를 수정하는 패턴입니다.

코드 예제

await db.update(users)
  .set({
    name: 'Jane Doe',
    updatedAt: new Date()
  })
  .where(eq(users.id, 1));

설명

set 객체에 변경할 필드만 명시하고, where 조건으로 대상을 정확히 지정합니다.

---

8. 트랜잭션 패턴

개요

여러 작업을 원자적으로 실행하는 트랜잭션 패턴입니다.

코드 예제

await db.transaction(async (tx) => {
  await tx.insert(users).values({ name: 'Alice' });
  await tx.insert(posts).values({
    title: 'First Post',
    authorId: 1
  });
});

설명

transaction 콜백 내의 모든 작업이 성공하거나 모두 롤백되어 데이터 일관성을 보장합니다.

---

9. Prepared Statements 패턴

개요

반복 실행되는 쿼리를 미리 준비하여 성능을 최적화하는 패턴입니다.

코드 예제

const getUserById = db.select()
  .from(users)
  .where(eq(users.id, placeholder('id')))
  .prepare('get_user_by_id');

const user = await getUserById.execute({ id: 1 });

설명

placeholder로 파라미터를 지정하고 prepare로 쿼리를 준비하면, 실행 시 파싱 비용이 절감됩니다.

---

10. 서브쿼리 패턴

개요

복잡한 조회를 위해 서브쿼리를 활용하는 패턴입니다.

코드 예제

const avgPostCount = db.select({
  count: count(posts.id)
}).from(posts).as('avgPosts');

const activeAuthors = await db.select()
  .from(users)
  .where(gte(avgPostCount.count, 5));

설명

서브쿼리를 별도 쿼리로 정의하고 as()로 별칭을 부여하여 메인 쿼리에서 재사용합니다.

---

11. 마이그레이션 패턴

개요

스키마 변경사항을 안전하게 데이터베이스에 적용하는 패턴입니다.

코드 예제

import { migrate } from 'drizzle-orm/postgres-js/migrator';
import { db } from './db';

await migrate(db, {
  migrationsFolder: './drizzle/migrations'
});

설명

drizzle-kit이 생성한 마이그레이션 파일을 자동으로 실행하여 스키마를 동기화합니다.

---

12. 타입 추론 패턴

개요

스키마로부터 TypeScript 타입을 자동 생성하는 패턴입니다.

코드 예제

import { InferModel } from 'drizzle-orm';

type User = InferModel<typeof users>;
type NewUser = InferModel<typeof users, 'insert'>;

const createUser = (data: NewUser): Promise<User> => {
  return db.insert(users).values(data).returning();
};

설명

InferModel로 select와 insert 타입을 자동 생성하여 타입 안전성을 극대화합니다.

---

마치며

이번 글에서는 Drizzle ORM 디자인 패턴 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#TypeScript #Drizzle #ORM #Schema #QueryBuilder