📡 05. Drizzle 데이터베이스 연동 — 안정적인 타입 안전성과 DI의 만남

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 전역 Database 모듈 주조하기 🟡
• 🧩 트랜잭션과 Repository 패턴 🟢
• 🧪 따라해보기: 실습 코드 조각 모음
• 💼 베스트 프랙티스와 실무 팁
• ⚠️ 에러 해결 카탈로그
• 🗂️ 치트시트
• 📝 마무리 퀴즈

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분 (전체) / 핵심 파트만: 10분

🧳 전제 지식 체크리스트

• 03장의 의존성 주입(DI) 과 @Injectable()의 개념을 명확히 이해하고 있다.
• Drizzle ORM의 기본 문법(select, insert, eq)을 어느 정도 읽을 줄 안다.
• PostgreSQL과 같은 관계형 데이터베이스의 '트랜잭션(Transaction)'이 무엇인지 안다.

🗺️ 이 문서의 흐름
독립형 라이브러리인 Drizzle을 NestJS 생태계에 편입시키기 → 서비스에서 DB 주입받아 쓰기 → 트랜잭션 다루기 → 대규모 앱을 위한 Repository 분리 → 테스트 Mocking 방안

🎯 이 문서를 다 읽으면 할 수 있는 것

• Drizzle 연동을 위한 전역 모듈(Global Module) 패턴을 완벽히 구축할 수 있다.
• 여러 쿼리가 모두 성공하거나 모두 실패해야만 하는 '트랜잭션' 코드를 짤 수 있다.
• 테스트 코드 작성 시 실제 DB를 건드리지 않도록 Mock 객체를 주입할 수 있다.

🤔 왜 알아야 하는가

Drizzle은 TypeORM이나 Prisma처럼 덩치가 큰 '프레임워크'가 아니라, 가볍게 SQL을 도와주는 '라이브러리(Query Builder)'에 가까워.
그래서 "설정 파일 하나 딱!" 하고 던져주는 편안한 내장 모듈이 아직 빈약한 편이지. 그렇다고 const db = drizzle(...) 해놓고 파일마다 무작정 import 해서 쓰다가는, 테스트(Mocking)가 불가능해지는 문제 상황 를 겪게 돼.
그래서 Drizzle을 NestJS의 DI(의존성 주입) 시스템 안에 예쁘게 포장하는 기술을 반드시 알아야 해.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?

데이터베이스(DB)는 우리 회사 밖 저 멀리 있는 '거대한 창고'야. 창고에 물건을 넣거나 빼려면 특별한 전용 핫라인 전화기 가 필요해.
나쁜 방법 (글로벌 직접 import):
100명의 직원이 각자 자기 자리에 전화기를 몰래 설치해서 창고에 전화를 걸어. 전화선이 수시로 엉키고 창고 아저씨(Max Connections)는 화내면서 전화를 다 끊어버려. 게다가 '연습용 창고(테스트 모드)'로 전화를 돌릴 방법도 없어.

좋은 방법 (NestJS 파이프라인 + DI):
회사 '통신 부서(DatabaseModule)'에서 딱 하나의 최고급 전화기(drizzle 인스턴스)를 개통해. 그리고 전화를 써야 하는 직원(Service)이 출근하면 "이따 창고 전화기 좀 쓸게요!" 하고 본부에 요청해. 그러면 지배인이 깔끔하게 연결해주는 거지.

🧩 전역 Database 모듈 주조하기 🟡

🎯 이 섹션을 읽고 나면:

• useFactory라는 커스텀 프로바이더의 개념을 이해하고, 외부 라이브러리를 NestJS용으로 감쌀 수 있다.

가장 먼저 이 "최고급 전화기"를 세팅하는 통신 부서를 만들자. 아래 코드는 NestJS + Drizzle 연동의 교과서 야.

// database/database.module.ts
import { Global, Module } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from '@repo/schema';
 
// 이 문자열이 식당에서 셰프(DB)를 부를 때 쓰는 명찰(Token)이야!
export const DATABASE_TOKEN = 'DATABASE';
 
@Global() // 🌟 전역 모듈 선언! 다른 부서에서 Imports 안 하고 가져다 쓸 수 있음
@Module({
  providers: [
    {
      provide: DATABASE_TOKEN, // "누가 이 명찰을 부르면..."
 
      // "...이 팩토리 함수를 한 번만 실행해서 진짜 전화기를 쥐어줘라!"
      useFactory: (configService: ConfigService) => {
        const url = configService.getOrThrow<string>('DATABASE_URL');
 
        // 1. 실제 Postgres 연결 클라이언트 생성
        const client = postgres(url, { max: 10 });
 
        // 2. Drizzle로 래핑하고, 우리가 만든 스키마(테이블 구조) 주입
        return drizzle(client, { schema });
      },
 
      // 팩토리 함수가 실행되기 전에 ConfigService가 먼저 조립되어야 함을 뜻해
      inject: [ConfigService],
    },
  ],
  exports: [DATABASE_TOKEN], // 우리 부서 밖으로 개방!
})
export class DatabaseModule {}

📖 핵심 개념: useFactory
내가 직접 만든 클래스가 아닌, 외부 라이브러리 패키지(drizzle)는 내 맘대로 코드에 @Injectable() 데코레이터를 달아줄 수가 없잖아? 그럴 땐 저렇게 공장(Factory) 함수를 만들어서 "이 함수가 뱉어내는 결과물을 대신 주입해 줘!" 라고 지정할 수 있어. 이게 바로 커스텀 프로바이더야.

🧩 트랜잭션과 Repository 패턴 🟢

DB 연결을 마쳤으니, 서비스에서 실제 쿼리를 날려볼 시간이야!

1. 기본 주입과 트랜잭션(Transaction)

유저가 결제를 했어. 1번: 유저 지갑에서 돈이 깎임. 2번: 주문이 생성됨.
그런데 1번을 성공하고 2번을 시도하다 서버가 꺼졌어. 유저 돈만 날아갔지? 이걸 막기 위해 두 작업을 "동시에 성공하거나 동시에 실패(Rollback)"하게 묶는 것이 트랜잭션이야.

import { Injectable, Inject } from '@nestjs/common';
import { DATABASE_TOKEN, Database } from '../database';
// ...기타 import
 
@Injectable()
export class OrderService {
  constructor(
    @Inject(DATABASE_TOKEN) // 아까 만든 명찰로 DB 전화기를 주입받음!
    private readonly db: Database,
  ) {}
 
  async createOrder(userId: string, totalAmount: number): Promise<void> {
    // 🔥 이 블록 안에서 일어나는 일은 전부 실패하거나 전부 성공함
    await this.db.transaction(async (tx) => {
 
      // 1. 유저 잔고 감소 (이때 this.db가 아니라 tx를 써야 함 주의!)
      await tx.update(users)
        .set({ balance: sql`${users.balance} - ${totalAmount}` })
        .where(eq(users.id, userId));
 
      // 2. 주문 정보 생성
      await tx.insert(orders).values({ userId, totalAmount });
 
      // 만약 여기서 에러가 나면(throw new Error) 1번의 지갑 차감도 자동 원상복구!
    });
  }
}

2. Repository 패턴으로의 분리 (대규모 앱)

OrderService 파일 하나에 주문 알림 보내기 로직, 포인트 적립 로직 등 비즈니스 코드가 너무 길어지면, 위와 같은 SQL 쿼리 코드는 눈에 거슬리기 시작해. 그때는 데이터 접근만 전담하는 Repository(저장소 담당자) 를 따로 만들어.

// 📁 stocks.repository.ts
@Injectable()
export class StocksRepository {
  constructor(@Inject(DATABASE_TOKEN) private db: Database) {}
 
  findBySymbol(symbol: string) {
    return this.db.query.stocks.findFirst({ where: eq(stocks.symbol, symbol) });
  }
}
 
// 📁 stocks.service.ts
@Injectable()
export class StocksService {
  // DB 전화기 대신 Repository 담당자를 주입받음!
  constructor(private readonly stocksRepo: StocksRepository) {}
 
  async getPrice(symbol: string) {
    const stock = await this.stocksRepo.findBySymbol(symbol);
    return stock.currentPrice;
  }
}

이렇게 하면 서비스는 "** 비즈니스 규칙**"만 고민하고, 레포지토리는 "** 데이터를 어떻게 빨리 뽑아올 지**"만 고민하는 아름다운 분업이 완성돼.

🧪 따라해보기: 실습 코드 조각 모음

테스팅: Mock 객체 꽂아넣기

DB 코드를 완벽하게 분리했으니 보상이 있어야겠지? 이 컨트롤러/서비스 유닛(단위) 테스트를 짤 때, 실제 DB를 끄고도 테스트가 가능해져.

// stocks.service.spec.ts
import { Test } from '@nestjs/testing';
 
// 1. 가짜 DB 전화기 만들기 (Mock)
const mockDb = {
  query: {
    stocks: { findMany: jest.fn().mockResolvedValue([ { symbol: 'AAPL' } ]) },
  },
};
 
describe('StocksService', () => {
  let service: StocksService;
 
  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        StocksService,
        // 2. 가짜 전화기를 진짜 명찰(DATABASE_TOKEN)에 붙여서 주입!
        { provide: DATABASE_TOKEN, useValue: mockDb },
      ],
    }).compile();
 
    service = module.get(StocksService);
  });
 
  it('주식 목록을 잘 가져와야 함', async () => {
    const res = await service.findAll();
    expect(res).toEqual([ { symbol: 'AAPL' } ]); // 실제 DB 안 타고 0.01초 만에 테스트 통과!
  });
});

💼 베스트 프랙티스와 실무 팁 🟡

1. Supabase 연동 시 prepare: false는 생명줄이다.

서버리스 환경이나 Supabase 같은 곳은 Connection Pooler(6543 포트)를 쓰게 되는데, 이때 prepare: false 옵션을 꺼주지 않으면 "Prepared statement ... already exists" 에러가 뿜어지며 서버가 뻗어버려.

const client = postgres(url, {
  max: 10,
  prepare: false // 👈 Supabase Transaction Mode의 안정적인 단짝
});

2. NestJS Health Check 추가하기

내 서버를 배포했을 때 DB가 뻗으면 서버 앱도 "나 지금 비정상이야" 라고 외쳐야 오토스케일링이 대처할 수 있어.

// health.controller.ts
@Get('db')
async checkDatabase() {
  try {
    // 가장 가벼운 쿼리를 날려봄
    await this.db.execute(sql`SELECT 1`);
    return { status: 'Database is healthy!' };
  } catch (error) {
    throw new ServiceUnavailableException('Database unavailable'); // 503 에러
  }
}

⚠️ 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ Nest can't resolve dependencies of the StocksService (?).

원인: StocksService에서 @Inject(DATABASE_TOKEN) private db 로 명찰(토큰)을 부르며 찾고 있는데, app.module.ts의 imports 쪽에 DatabaseModule을 넣지 않아서 NestJS가 그 명찰이 뭔지 모름!
(참고: DatabaseModule에 @Global()을 달았다면 app.module.ts 한 곳에만 딱 한 번 import 해두면 돼!)

❌ Remaining connection slots are reserved for non-replication superuser connections

현상: 갑자기 DB 조회 응답이 엄청 느려지더니 에러가 남.
원인: postgres 드라이버를 AppModule 외부에서 글로벌 변수처럼 매번 함수 호출때마다 찍어내서 Connection 객체가 수백 개 넘게 폭증했기 때문.
해결책: 반드시 NestJS의 싱글톤 모듈(useFactory) 안에서 단 한 번만 생성되도록 코드를 고쳐야 해!

🗂️ 치트시트 — 실무 요약 카드

📝 마무리 퀴즈

Q1. 외부 라이브러리인 Drizzle은 내가 직접 @Injectable()을 붙일 수 없기 때문에 어떤 방식으로 프로바이더를 생성해야 하는가?

• A) 컨트롤러 안에서 매일 require('drizzle')을 호출한다.
• B) @Global() 데코레이터만 달면 알아서 주입된다.
• C) useFactory 함수를 써서 코드로 인스턴스를 찍어내 반환한다.
• D) useClass 속성을 쓴다.

✅ 정답: C

💡 설명: 커스텀 프로바이더의 정수! 팩토리를 통해 공장을 돌려서 찍어낸 결과물을 던져주는 방식이야.

Q2. 결제 비즈니스 로직 도중, 다음 두 쿼리가 하나의 트랜잭션으로 묶여있지 "않을" 때 나타나는 문제점으로 가장 정확한 것은?

await this.db.update(users).set({ point: point - 10 }); // 유저 포인트 차감
// <--------- (만약 이 틈에 서버가 셧다운된다면?)
await this.db.insert(orders).values({ item: 'Apple' }); // 주문 1건 생성

• A) 컴파일 에러가 발생한다.
• B) 유저의 포인트는 차감되었는데, 돈을 지불한 주문 내역(상품)은 없는 상태가 된다.
• C) Drizzle ORM이 알아서 다시 실행해준다.

✅ 정답: B

💡 설명: 돈만 먹고 아이템을 안 주는 위험한 불일치 상황! 트랜잭션(db.transaction(tx => ...))으로 양쪽을 강제 결합시켜 한쪽이 깨지면 반드시 전부 원상복구(Rollback) 시켜야 해.

Q3. 디버깅 퀴즈: 아래 코드에서 트랜잭션이 하나도 동작하지 않는 이유를 찾아봐.

await this.db.transaction(async (tx) => {
  await this.db.insert(users).values({ name: 'Kim' }); // 1번
  await this.db.insert(logs).values({ action: 'signin' }); // 2번
});

✅ 정답: 트랜잭션 블록 내부에서 계속 기존 this.db를 쓰고 있기 때문!
설명: 트랜잭션 환경을 열어줬으면, 그 안에서는 파라미터로 넘어온 tx를 써서 await tx.insert(...)로 호출해야 하나의 트랜잭션 흐름으로 취급해. this.db를 쓰면 바깥의 트랜잭션과 무관한 독립 쿼리로 날아가 버려!

🐣 영철이의 퇴근 일기

오늘은 NestJS와 Drizzle을 연결하는 일이 단순히 DB 객체를 import하는 문제가 아니라는 걸 배웠다. 외부 라이브러리도 useFactory로 프로바이더를 만들면 Nest의 DI 흐름 안에 들어온다.

트랜잭션 예제는 특히 세게 남았다. 영수네 포인트 결제에서 포인트만 빠지고 주문이 없으면 그건 코드 버그가 아니라 바로 운영 사고다.

💡 "DB 연동의 핵심은 쿼리를 날리는 법이 아니라, 실패 단위와 주입 경계를 명확히 만드는 법이다."

내일은 서비스 코드에서 여러 쿼리가 이어지면 먼저 트랜잭션 경계를 확인해야겠다.

🔗 더 알아보기

• NestJS - Custom Providers: useFactory
• Drizzle ORM Query API Docs
• 06. 인증 처리 (Authentication) 가이드