ORM 사용

앞의 글들에서는 사용자를 메모리의 배열이나 Map에 저장했으므로, 서버를 다시 시작하면 데이터가 모두 사라졌습니다. 실제 서비스는 데이터를 데이터베이스에 저장하며, 관계형 데이터베이스와는 SQL로 이야기합니다. 그런데 SQL은 문자열이어서 타입스크립트의 타입 검사를 받지 못하고, 테이블의 행을 객체로 바꾸는 코드도 반복해서 써야 합니다.

ORM(Object-Relational Mapping)은 클래스와 테이블, 객체와 행을 이어 주어 SQL을 직접 쓰지 않고도 객체를 저장하고 조회하게 해 주는 도구입니다. 이 글은 NestJS 12에서 TypeORM 1로 사용자 API를 PostgreSQL에 연결하고, 수정 요청의 의미를 정한 뒤, 운영 중인 데이터베이스의 스키마를 안전하게 바꾸는 마이그레이션의 순서를 봅니다.

ORM이 하는 일과 그 비용

ORM은 클래스 하나를 테이블 하나에, 그 클래스의 속성을 컬럼에 대응시킵니다. 그러면 repository.findOneBy({ id: 1 }) 같은 메서드 호출이 SELECT 문이 되고, 결과의 행은 클래스의 인스턴스가 되어 돌아옵니다. 조건에 쓰는 속성 이름과 값의 타입이 검사되고, 외래 키로 이어진 테이블도 객체의 관계로 따라갈 수 있으며, PostgreSQL이나 MySQL처럼 데이터베이스가 달라도 기본적인 저장과 조회는 같은 API로 할 수 있습니다.

대신 ORM이 만드는 SQL은 코드에 보이지 않습니다. 관계를 따라가는 코드가 행마다 쿼리를 하나씩 더 보내거나, 필요 없는 컬럼까지 읽는 일이 생기므로, 개발 중에는 실행되는 SQL을 로그로 확인해야 합니다. 또 데이터베이스마다 컬럼 타입과 ID를 만드는 방식, 잠금, 인덱스가 다르므로, ORM을 쓴다고 데이터베이스를 아무 때나 바꿀 수 있는 것은 아닙니다.

Node.js에서는 여러 ORM이 쓰입니다. TypeORM은 데코레이터를 붙인 클래스로 엔티티(entity)를 정의하고, Prisma는 별도의 스키마 파일에서 타입이 붙은 클라이언트를 만들어 주며, Drizzle은 타입스크립트 코드로 스키마를 적고 SQL에 가까운 문법으로 쿼리합니다. 이 글은 NestJS가 전용 모듈을 제공하고 14장 2절에서 본 데코레이터와 같은 방식을 쓰는 TypeORM을 씁니다.

설치와 연결

NestJS 프레임워크처럼 nest new로 만들고 모듈 방식으로 CommonJS를 고른 프로젝트에 TypeORM과 PostgreSQL 드라이버, 검증 라이브러리를 설치합니다. @nestjs/typeorm은 NestJS와 TypeORM을 잇는 모듈이고, typeorm이 ORM 본체, pg가 PostgreSQL에 실제로 접속하는 드라이버입니다. 나머지 두 패키지는 14장 2절처럼 요청 본문을 DTO 클래스로 검사하는 데 씁니다.

npm install @nestjs/typeorm typeorm pg class-validator class-transformer

2026년 10월 현재 TypeORM은 1.1이고, TypeORM 1은 Node.js 20 이상을 요구합니다. 학습용 PostgreSQL은 컴퓨터에 직접 설치하거나, Docker가 있다면 docker run --name typeorm-pg -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:18처럼 컨테이너로 띄웁니다. 그다음 AppModule에서 데이터베이스에 연결합니다.

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { User } from "./user/entities/user.entity";
import { UserModule } from "./user/user.module";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: "postgres",
      host: process.env.DB_HOST ?? "localhost",
      port: Number(process.env.DB_PORT ?? 5432),
      username: process.env.DB_USER ?? "postgres",
      password: process.env.DB_PASSWORD ?? "postgres",
      database: process.env.DB_NAME ?? "postgres",
      entities: [User],
      synchronize: true,
      logging: true,
    }),
    UserModule,
  ],
})
export class AppModule {}

entities는 이 연결에서 쓸 엔티티 클래스의 목록이고, logging: true는 실행되는 SQL을 서버의 콘솔에 찍습니다. synchronize: true는 서버가 시작할 때 엔티티에 맞춰 테이블을 자동으로 만들고 바꾸는 설정으로, 처음 배울 때는 편하지만 컬럼을 지우거나 이름을 바꾸면 그 컬럼의 데이터가 사라질 수 있습니다. 그래서 운영 환경에서는 쓰지 않고, 이 글의 뒤에서 마이그레이션으로 바꿉니다.

연결 정보의 기본값은 학습용입니다. 실제 사용자 이름과 비밀번호는 배포 환경의 비밀 저장소나 환경 변수로 넣고, 소스 코드나 저장소에 올리는 파일에 남기지 않습니다.

엔티티 정의

엔티티는 테이블에 대응하는 클래스입니다. 클래스에 @Entity()를, 속성에 컬럼 데코레이터를 붙여 테이블의 모양을 적습니다.

import { Column, CreateDateColumn, Entity, PrimaryGeneratedColumn } from "typeorm";

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column({ type: "varchar", length: 100, unique: true })
  email!: string;

  @Column({ type: "varchar", length: 50 })
  name!: string;

  @Column({ type: "int", nullable: true })
  age!: number | null;

  @CreateDateColumn({ type: "timestamptz" })
  createdAt!: Date;
}

@PrimaryGeneratedColumn()은 데이터베이스가 1부터 차례로 만들어 주는 기본 키이고, @CreateDateColumn()은 행을 넣을 때의 시각을 자동으로 기록합니다. 속성 뒤의 !는 이 값을 생성자에서 넣지 않아도 ORM이 채운다고 컴파일러에게 알리는 확정 할당 단언입니다. email의 unique: true는 데이터베이스에 유일성 제약을 만들어, 같은 이메일을 두 번 넣으려 하면 데이터베이스가 거절하게 합니다.

컬럼마다 type을 직접 적은 데는 이유가 있습니다. TypeORM은 emitDecoratorMetadata가 남긴 속성의 타입으로 컬럼 타입을 짐작하는데, number | null 같은 유니온 타입은 메타데이터에 Object로만 남아 짐작할 수 없기 때문입니다. nullable: true인 age의 타입에 null을 넣은 것도, 데이터베이스에서 읽은 값이 실제로 null일 수 있다는 사실을 타입에 드러내기 위해서입니다.

요청 DTO와 PATCH의 의미

요청 본문은 엔티티가 아니라 별도의 DTO 클래스로 받습니다. 엔티티를 그대로 받으면 클라이언트가 id나 createdAt까지 보낼 수 있기 때문입니다.

import { IsEmail, IsInt, IsOptional, IsString, Max, Min } from "class-validator";

export class CreateUserDto {
  @IsString()
  name!: string;

  @IsEmail()
  email!: string;

  @IsOptional()
  @IsInt()
  @Min(0)
  @Max(120)
  age?: number | null;
}

일부 필드만 바꾸는 PATCH 요청은 필드를 보내지 않은 것과 null을 보낸 것을 구별해야 합니다. 기존 사용자가 name="Ada", age=20일 때 이 API는 다음처럼 동작하도록 정합니다.

이 표를 DTO로 옮길 때 주의할 점이 있습니다. @IsOptional()은 값이 undefined일 때뿐 아니라 null일 때도 그 필드의 다른 검사를 건너뛰므로, name에 @IsOptional()을 붙이면 {"name": null}이 통과합니다. 그래서 name과 email은 값이 undefined가 아닐 때만 검사를 실행하는 @ValidateIf를 쓰고, null을 허용하는 age에만 @IsOptional()을 씁니다.

import { IsEmail, IsInt, IsOptional, IsString, Max, Min, ValidateIf } from "class-validator";

export class UpdateUserDto {
  @ValidateIf((_object, value) => value !== undefined)
  @IsString()
  name?: string;

  @ValidateIf((_object, value) => value !== undefined)
  @IsEmail()
  email?: string;

  @IsOptional()
  @IsInt()
  @Min(0)
  @Max(120)
  age?: number | null;
}

name이 null이면 ValidateIf의 조건이 참이 되어 @IsString()이 실행되고, null은 문자열이 아니므로 거절됩니다. 필드를 보내지 않으면 조건이 거짓이어서 검사를 건너뜁니다. 이 검사는 main.ts에서 app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }))로 ValidationPipe를 등록해야 실행되며, transform: true는 검증한 본문을 DTO 클래스의 인스턴스로 바꾸어 처리 메서드에 넘깁니다.

저장소와 서비스

서비스는 엔티티의 저장소(repository)를 주입받아 데이터베이스 작업을 합니다. 저장소는 그 엔티티의 테이블에 대한 저장, 조회, 삭제 메서드를 가진 객체입니다.

import { Injectable } from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { Repository } from "typeorm";
import { CreateUserDto } from "./dto/create-user.dto";
import { UpdateUserDto } from "./dto/update-user.dto";
import { User } from "./entities/user.entity";

@Injectable()
export class UserService {
  constructor(@InjectRepository(User) private readonly usersRepository: Repository<User>) {}

  create(dto: CreateUserDto): Promise<User> {
    const user = this.usersRepository.create(dto);
    return this.usersRepository.save(user);
  }

  findAll(): Promise<User[]> {
    return this.usersRepository.find();
  }

  findOne(id: number): Promise<User | null> {
    return this.usersRepository.findOneBy({ id });
  }

  async update(id: number, dto: UpdateUserDto): Promise<User | null> {
    const user = await this.usersRepository.findOneBy({ id });
    if (!user) {
      return null;
    }
    this.usersRepository.merge(user, dto);
    return this.usersRepository.save(user);
  }

  async remove(id: number): Promise<boolean> {
    const result = await this.usersRepository.delete(id);
    return (result.affected ?? 0) > 0;
  }
}

@InjectRepository(User)는 NestJS에게 User 엔티티의 저장소를 넣어 달라고 알리고, Repository<User>의 타입 인수 덕분에 findOneBy의 조건에는 User의 속성만 쓸 수 있습니다. create는 객체로 엔티티 인스턴스를 만들 뿐 저장하지 않으며, save가 행이 없으면 INSERT를, 있으면 UPDATE를 실행합니다. merge는 DTO의 값을 엔티티에 옮기고, save는 값이 undefined인 속성을 건너뛰므로 PATCH에서 보내지 않은 필드는 바뀌지 않습니다.

TypeORM 1부터는 조회 조건에 null이나 undefined가 들어오면 기본으로 오류를 던집니다. 예전에는 findOneBy({ id: undefined })가 그 조건을 조용히 무시해 첫 번째 행을 돌려주는 일이 있었기 때문이며, null인 행을 찾으려면 IsNull() 연산자를 씁니다. 이 서비스는 컨트롤러의 파이프가 검증한 숫자 id만 받으므로 그런 일이 생기지 않습니다.

모듈과 컨트롤러

기능 모듈에서 TypeOrmModule.forFeature([User])로 이 모듈이 쓸 엔티티를 등록하면, 그 모듈의 프로바이더가 User의 저장소를 주입받을 수 있습니다. 다음 두 파일 가운데 user.module.ts는 엔티티와 컨트롤러, 서비스를 한 모듈로 묶고, user.controller.ts는 HTTP 요청을 받아 서비스에 넘깁니다. 컨트롤러의 ParseIntPipe는 경로의 id 문자열을 숫자로 바꾸며, 숫자로 바꿀 수 없으면 처리 함수에 닿기 전에 400 응답을 돌려줍니다.

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { User } from "./entities/user.entity";
import { UserController } from "./user.controller";
import { UserService } from "./user.service";

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UserController],
  providers: [UserService],
})
export class UserModule {}

import { Body, Controller, Delete, Get, HttpCode, NotFoundException, Param, ParseIntPipe, Patch, Post } from "@nestjs/common";
import { CreateUserDto } from "./dto/create-user.dto";
import { UpdateUserDto } from "./dto/update-user.dto";
import { User } from "./entities/user.entity";
import { UserService } from "./user.service";

@Controller("users")
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  create(@Body() dto: CreateUserDto): Promise<User> {
    return this.userService.create(dto);
  }

  @Get()
  findAll(): Promise<User[]> {
    return this.userService.findAll();
  }

  @Get(":id")
  async findOne(@Param("id", ParseIntPipe) id: number): Promise<User> {
    const user = await this.userService.findOne(id);
    if (!user) throw new NotFoundException("User not found");
    return user;
  }

  @Patch(":id")
  async update(@Param("id", ParseIntPipe) id: number, @Body() dto: UpdateUserDto): Promise<User> {
    const user = await this.userService.update(id, dto);
    if (!user) throw new NotFoundException("User not found");
    return user;
  }

  @Delete(":id")
  @HttpCode(204)
  async remove(@Param("id", ParseIntPipe) id: number): Promise<void> {
    const removed = await this.userService.remove(id);
    if (!removed) throw new NotFoundException("User not found");
  }
}

POST /users에 {"name":"Ada","email":"[email protected]","age":20}을 보내면 데이터베이스가 만든 id와 createdAt이 채워진 사용자가 201과 함께 돌아오고, 서버의 콘솔에는 트랜잭션 안에서 실행된 INSERT INTO "user" 문이 찍힙니다. 없는 ID를 조회, 수정, 삭제하면 404가 되고, 삭제에 성공하면 본문 없이 204가 돌아옵니다. 같은 이메일로 다시 가입하면 데이터베이스의 유일성 제약이 거절하는데, 이 오류는 따로 처리하지 않았으므로 500이 되며, 실제 서비스에서는 그 오류를 409 같은 응답으로 바꾸는 처리를 더합니다.

이 글의 서비스는 TypeORM의 Repository<User>에 직접 의존하고, 컨트롤러는 User 엔티티를 그대로 응답합니다. 그림은 이를 넓혀, 공개 응답 DTO와 도메인 서비스, 도메인이 정한 저장소 인터페이스, 그 인터페이스를 TypeORM으로 구현한 어댑터를 나눈 설계입니다. 이렇게 나누면 저장 방식을 바꾸어도 도메인 코드와 응답의 모양이 그대로이고, 엔티티에 내부용 컬럼을 더해도 응답에 저절로 나가지 않습니다. 앞 글의 toMemberResponse 같은 변환 함수가 그 첫걸음입니다.

마이그레이션으로 스키마 바꾸기

마이그레이션(migration)은 스키마의 변경을 순서가 있는 파일로 남기고, 그 파일을 데이터베이스에 차례로 적용하는 방법입니다. 데이터베이스에는 어느 마이그레이션까지 적용했는지가 기록되므로, 개발, 테스트, 운영 환경의 스키마를 같은 순서로 맞출 수 있습니다. 마이그레이션을 쓰기 시작하면 AppModule의 synchronize를 false로 바꿉니다. 두 방식을 함께 쓰면 실제 스키마와 마이그레이션의 기록이 어긋나기 때문입니다.

TypeORM의 CLI는 연결 설정을 담은 데이터 소스 파일을 읽어 동작합니다. 타입스크립트 파일을 바로 읽도록 ts-node를 설치하고, package.json의 scripts에 CLI를 더합니다.

npm install --save-dev ts-node

{
  "scripts": {
    "typeorm": "typeorm-ts-node-commonjs"
  }
}

import { DataSource } from "typeorm";
import { User } from "./user/entities/user.entity";

export const AppDataSource = new DataSource({
  type: "postgres",
  host: process.env.DB_HOST ?? "localhost",
  port: Number(process.env.DB_PORT ?? 5432),
  username: process.env.DB_USER ?? "postgres",
  password: process.env.DB_PASSWORD ?? "postgres",
  database: process.env.DB_NAME ?? "postgres",
  entities: [User],
  migrations: ["src/migrations/*.ts"],
  synchronize: false,
});

npm run typeorm migration:generate src/migrations/CreateUser -- -d src/data-source.ts
npm run typeorm migration:run -- -d src/data-source.ts
npm run typeorm migration:revert -- -d src/data-source.ts

migration:generate는 엔티티와 연결한 데이터베이스의 실제 스키마를 비교해, 그 차이를 메우는 SQL을 담은 파일을 이름 앞에 시각 숫자를 붙여 만듭니다. migration:run은 아직 적용하지 않은 마이그레이션을 차례로 실행하고, migration:revert는 마지막 하나의 down을 실행해 되돌립니다. 앞에서 synchronize: true로 이미 테이블을 만든 데이터베이스라면 차이가 없어 만들 파일이 없다고 나오므로, 새 데이터베이스에 연결하거나 엔티티를 바꾼 뒤에 실행합니다.

만들어진 파일은 그대로 적용하지 않고 SQL을 읽어 봅니다. 예를 들어 속성의 이름을 바꾸면 ORM은 그것을 컬럼을 지우고 새로 만드는 변경으로 볼 수 있는데, 그대로 적용하면 그 컬럼의 데이터가 사라집니다.

운영 중인 스키마 바꾸기

서비스가 계속 돌아가는 중에 스키마를 바꿀 때는, 새 버전의 코드가 배포되는 동안 옛 버전의 코드도 같은 데이터베이스를 쓴다는 점을 생각해야 합니다. 그래서 한 번에 바꾸지 않고, 두 버전이 함께 동작할 수 있는 구간을 일부러 만듭니다.

name 컬럼을 displayName으로 바꾸는 경우를 예로 들면, 먼저 displayName을 비어 있어도 되는 컬럼으로 더하는 확장(expand) 마이그레이션을 적용합니다. 그다음 두 컬럼에 함께 쓰고, 읽을 때는 displayName이 비어 있으면 name을 쓰는 코드를 배포해 옛 코드와 새 코드가 함께 동작하게 합니다. 이어서 기존 행의 displayName을 작은 묶음으로 나누어 채우는 백필(backfill)을 하고, 결과를 확인한 뒤에야 읽기를 새 컬럼으로 전환합니다.

전환한 뒤에는 오류와 지연, 옛 컬럼을 읽는 코드가 남아 있는지를 지켜봅니다. 옛 컬럼을 쓰는 곳이 더는 없다고 확인되면, 다음 배포에서 name을 지우는 축소(contract) 마이그레이션을 따로 적용합니다. 그림처럼 이 과정은 TypeORM의 CLI가 대신해 주는 것이 아니라 팀이 계획하는 절차이며, 지운 컬럼의 데이터는 down이 컬럼을 다시 만들어도 돌아오지 않으므로 삭제 전에 복구 방법을 따로 준비합니다.

정리

• ORM은 클래스와 테이블, 객체와 행을 이어 타입이 검사되는 API로 데이터베이스를 다루게 하지만, 실행되는 SQL은 로그로 확인해야 합니다.
• TypeORM의 엔티티는 데코레이터로 테이블의 모양을 적으며, 유니온 타입의 속성은 메타데이터로 짐작할 수 없으므로 컬럼 타입을 직접 적습니다.
• 요청 본문은 엔티티가 아닌 DTO로 받고, PATCH에서 보내지 않은 필드와 null을 보낸 필드를 구별해 검증합니다.
• @IsOptional()은 null일 때도 검사를 건너뛰므로, 비울 수 없는 필드에는 undefined일 때만 건너뛰는 @ValidateIf를 씁니다.
• TypeORM 1은 조회 조건의 null과 undefined를 기본으로 오류로 처리하며, save는 값이 undefined인 속성을 건너뜁니다.
• 운영에서는 synchronize를 끄고 마이그레이션을 쓰며, 스키마는 확장, 공존, 백필, 전환, 관찰, 축소의 순서로 나누어 바꿉니다.

연습 문제

1. PATCH의 세 가지 본문

기존 사용자가 name="Ada", age=20입니다. {}, {"age": null}, {"name": null}을 각각 PATCH로 보내면 어떻게 되나요? UpdateUserDto의 name에 @IsOptional()을 썼다면 세 번째 요청은 어떻게 되나요?

2. 없는 사용자의 수정과 삭제

ID 99인 사용자가 없을 때 PATCH /users/99를 보내면 서비스는 merge와 save를 몇 번 부르나요? DELETE /users/99는 어떤 응답을 받나요?

3. 만들어지지 않는 마이그레이션

synchronize: true로 서버를 여러 번 실행한 데이터베이스에 연결해 migration:generate를 실행했더니 만들 변경이 없다고 나왔습니다. 왜 그런가요? 운영에서 컬럼을 지운 마이그레이션을 migration:revert로 되돌리면 데이터도 돌아오나요?

이것으로 14장의 백엔드 개발을 마칩니다. 다음 장의 Jest를 사용한 단위 테스트에서는 서버와 라이브러리의 코드를 Jest로 테스트하고, 바깥 의존성을 모의 함수로 바꾸어 검사하는 방법을 다룹니다.