TypeORM을 사용해 Postgres 연동하기

이제 드디어 In-Memory의 한계를 넘어, 실제 데이터베이스를 연동할 차례입니다.
Node.js 진영의 표준 ORM인 TypeORM과 오픈소스 RDBMS인 PostgreSQL을 사용하여 영구적인 저장소를 구축해 보겠습니다.

🦅 TypeORM? ORM이란?

Spring 생태계에 JPA(Hibernate)가 있다면, Node.js 생태계에는 TypeORM이 있습니다.

ORM (Object Relational Mapping)
- 객체(Object)와 관계형 데이터베이스(RDB)의 데이터를 자동으로 매핑(연결)해주는 것을 말합니다.
TypeORM
- TypeScript를 지원하는 가장 강력하고 성숙한 ORM 프레임워크입니다.
- JPA와 사용법이 매우 유사하여(Entity, Repository, Decorator 등), Java 개발자가 적응하기 가장 쉬운 라이브러리입니다.

[참고] TypeORM 공식 문서 👉 TypeORM Documentation

💾 DB (Postgres) 설치 - Docker Compose

로컬 환경을 더럽히지 않고 깔끔하게 DB를 띄우기 위해 Docker Compose를 사용합니다.

`docker-compose.yml` 작성

프로젝트 루트 경로에 docker 폴더를 만들고, 그 안에 docker-compose.yml을 작성합니다.

version: '3.8'
# 실행: docker-compose -f docker/docker-compose.yml --env-file .env up -d

services:
  postgres:
    image: postgres:16-alpine
    container_name: nest-crud-postgres
    restart: always
    environment:
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_DATABASE}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

환경 변수 설정 (`.env`)

프로젝트 루트의 .env 파일에 DB 접속 정보를 정의합니다.

DB_HOST=127.0.0.1
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=board-app

DB 실행 및 확인

터미널에서 다음 명령어로 DB를 실행합니다.

$ docker-compose -f docker/docker-compose.yml --env-file .env up -d

🛠️ TypeORM 설치 및 연동

이제 NestJS 애플리케이션과 Postgres를 연결해봅시다.

모듈 설치

필요한 패키지들을 설치합니다.

@nestjs/typeorm: NestJS용 TypeORM 래퍼
typeorm: Core ORM 라이브러리
pg: PostgreSQL 드라이버
@nestjs/config: 환경변수 관리를 위해 (이미 설치했다면 생략)

$ npm install --save @nestjs/typeorm typeorm pg @nestjs/config

당연히 postgres 가 아닌, 다른 DB 를 사용한다면 다른 드라이버를 가져와야 합니다.

TypeORM 설정 분리 (`typeorm.config.ts`)

app.module.ts가 지저분해지는 것을 막기 위해, 설정을 별도 파일로 분리하겠습니다.

ConfigService를 주입받아 환경변수를 안전하게 로드합니다.

src/configs/typeorm.config.ts

import { ConfigService } from '@nestjs/config';
import { TypeOrmModuleOptions } from '@nestjs/typeorm';
import { Board } from '../boards/entities/board.entity';

export const typeORMConfig = async (configService: ConfigService): Promise<TypeOrmModuleOptions> => {
  return {
    type: 'postgres',
    host: configService.get<string>('DB_HOST'),
    port: configService.get<number>('DB_PORT'),
    username: configService.get<string>('DB_USERNAME'),
    password: configService.get<string>('DB_PASSWORD'),
    database: configService.get<string>('DB_DATABASE'),
    entities: [Board],
    synchronize: true,
    dropSchema: false,
  };
};

실제로는 운영 환경에 따라 synchronize 과 dropSchema 는 유동적으로 변경될 수 있도록 구성해야합니다.
왜 그런지는 아래 부록 부분에서 다룹니다!

App 모듈에 등록 (`app.module.ts`)

루트 모듈에서 TypeOrmModule을 비동기(forRootAsync)로 로드합니다.

src/app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { BoardsModule } from './boards/boards.module';
import { typeORMConfig } from './configs/typeorm.config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
    }),
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: typeORMConfig,
      inject: [ConfigService],
    }),
    BoardsModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

🏗️ 도메인 구현 (Entity, Repository, Service)

Entity 정의 (`board.entity.ts`)

JPA의 @Entity와 거의 똑같습니다.

import { Column, Entity, PrimaryGeneratedColumn } from "typeorm";
import { BoardStatus } from "./board-status.enum";

@Entity()
export class Board {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  title: string;

  @Column()
  description: string;

  @Column()
  status: BoardStatus;

  @Column()
  priority: number;
}

만약 Index 를 추가하거나, Column 에 별도의 Options을 (Unique 등) 추가해야 할 경우 아래의 공식 문서를 통해 확인하시기 바랍니다.
Column Options (unique 등): TypeORM - Entities > Column Options
Indices & Unique Constraints (인덱스 및 복합 유니크): TypeORM - Indices

Custom Repository 구현 (`boards.repository.ts`)

TypeORM 0.3 버전부터는 @EntityRepository가 Deprecated 되었습니다.

대신 Repository<T>를 상속받고 DataSource를 주입받아 사용하는 방식(Custom Repository)이 권장됩니다.

boards.repository.ts

import { Injectable } from '@nestjs/common';
import { DataSource, Repository } from 'typeorm';
import { Board } from './entities/board.entity';

@Injectable()
export class BoardsRepository extends Repository<Board> {
  constructor(private dataSource: DataSource) {
    super(Board, dataSource.createEntityManager());
  }
}

Module에 등록 (`boards.module.ts`)

커스텀 레포지토리를 사용하기 위해 providers에 등록해줍니다.

boards.module.ts

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { BoardsController } from './boards.controller';
import { BoardsService } from './boards.service';
import { Board } from './entities/board.entity';

import { BoardsRepository } from './boards.repository';

@Module({
  imports: [TypeOrmModule.forFeature([Board])],
  controllers: [BoardsController],
  providers: [BoardsService, BoardsRepository],
})
export class BoardsModule {}

Service에서 사용 (`boards.service.ts`)

이제 In-Memory 배열(private boards = [])을 지우고, 레포지토리를 주입받아 DB와 통신합니다.

boards.service.ts

import { Injectable, NotFoundException } from '@nestjs/common';
import { CreateBoardRequest, CreateBoardResponse } from './dto/create-board.dto';
import { FindBoardResponse } from './dto/find-board.dto';
import { UpdateBoardRequest, UpdateBoardResponse } from './dto/update-board.dto';

import { BoardsRepository } from './boards.repository';
import { BoardStatus } from './entities/board-status.enum';

@Injectable()
export class BoardsService {
  constructor(
    private boardsRepository: BoardsRepository,
  ) {}

  async createBoard(createBoardDto: CreateBoardRequest): Promise<CreateBoardResponse> {

    const { title, description, priority } = createBoardDto;
    const board = this.boardsRepository.create({
      title: title,
      description: description,
      status: BoardStatus.PUBLIC,
      priority: priority,
    });

    await this.boardsRepository.save(board);

    return {
      id: board.id,
      title: board.title,
      description: board.description,
      status: board.status,
      priority: board.priority,
    };  
  }

  async findAllBoards(): Promise<FindBoardResponse[]> {
    const boards = await this.boardsRepository.find();
    return boards.map((board) => ({
      id: board.id,
      title: board.title,
      description: board.description,
      status: board.status,
      priority: board.priority,
    }));
  }

  async findBoard(id: string): Promise<FindBoardResponse> {
    const board = await this.boardsRepository.findOneBy({ id });

    if (!board) {
      throw new NotFoundException(`Board with ID "${id}" not found`);
    }

    return {
      id: board.id,
      title: board.title,
      description: board.description,
      status: board.status,
      priority: board.priority,
    };
  }

  async updateBoard(id: string, request: UpdateBoardRequest): Promise<UpdateBoardResponse> {
    const board = await this.boardsRepository.findOneBy({ id });

    if (!board) {
      throw new NotFoundException(`Board with ID "${id}" not found`);
    }

    if (request.title) {
        board.title = request.title;
    }
    if (request.description) {
        board.description = request.description;
    }
    if (request.status) {
        board.status = request.status;
    }
    if (request.priority) {
        board.priority = request.priority;
    }

    await this.boardsRepository.save(board);

    return {
      id: board.id,
      title: board.title,
      description: board.description,
      status: board.status,
      priority: board.priority,
    };
  }

  async deleteBoard(id: string): Promise<void> {
    const result = await this.boardsRepository.delete(id);
    
    if (result.affected === 0) {
        throw new NotFoundException(`Board with ID "${id}" not found`);
    }
  }

  async findBoardsByPriority(priority: number): Promise<FindBoardResponse[]> {
    const boards = await this.boardsRepository.find({ where: { priority } });
    return boards.map((board) => ({
      id: board.id,
      title: board.title,
      description: board.description,
      status: board.status,
      priority: board.priority,
    }));
  }
}

Controller 수정 (`boards.controller.ts`)

Service가 Promise를 반환하게 되었으므로, Controller도 async/await를 사용하도록 수정합니다.

boards.controller.ts

import { Body, Controller, Delete, Get, HttpCode, Param, Patch, Post } from '@nestjs/common';
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
import { BoardsService } from './boards.service';
import { CreateBoardRequest, CreateBoardResponse } from './dto/create-board.dto';
import { FindBoardResponse } from './dto/find-board.dto';
import { UpdateBoardRequest, UpdateBoardResponse } from './dto/update-board.dto';

@ApiTags('boards')
@Controller('boards')
export class BoardsController {
  constructor(private readonly boardsService: BoardsService) {}

  @Post()
  @ApiOperation({ summary: 'Create a board' })
  @ApiResponse({ status: 200, description: 'The board has been successfully created.', type: CreateBoardResponse })
  @HttpCode(200) // 201이 기본이지만 200으로 설정
  async createBoard(@Body() createBoardDto: CreateBoardRequest): Promise<CreateBoardResponse> {
    const response = await this.boardsService.createBoard(createBoardDto);
    return response;
  }

  @Get()
  @ApiOperation({ summary: 'Find all boards' })
  @ApiResponse({ status: 200, description: 'Return all boards.', type: [FindBoardResponse] })
  @HttpCode(200)
  async findAllBoards(): Promise<FindBoardResponse[]> {
    const response = await this.boardsService.findAllBoards();
    return response;
  }

  @Get(':id')
  @ApiOperation({ summary: 'Find a board by id' })
  @ApiResponse({ status: 200, description: 'Return the board.', type: FindBoardResponse })
  @HttpCode(200)
  async findBoard(@Param('id') id: string): Promise<FindBoardResponse> {
    const response = await this.boardsService.findBoard(id);
    return response;
  }

  @Patch(':id')
  @ApiOperation({ summary: 'Update a board' })
  @ApiResponse({ status: 200, description: 'The board has been successfully updated.', type: UpdateBoardResponse })
  @HttpCode(200)
  async updateBoard(
    @Param('id') id: string,
    @Body() updateBoardDto: UpdateBoardRequest
  ): Promise<UpdateBoardResponse> {
    return await this.boardsService.updateBoard(id, updateBoardDto);
  }

  @Delete(':id')
  @ApiOperation({ summary: 'Delete a board' })
  @ApiResponse({ status: 204, description: 'The board has been successfully deleted.' })
  @HttpCode(204) // 204 No Content
  async deleteBoard(@Param('id') id: string): Promise<void> {
    await this.boardsService.deleteBoard(id);
  }

  @Get('/priority/:priority')
  @ApiOperation({ summary: 'Find boards by priority' })
  @ApiResponse({ status: 200, description: 'Return boards with the specified priority.', type: [FindBoardResponse] })
  @HttpCode(200)
  async findBoardsByPriority(@Param('priority') priority: number): Promise<FindBoardResponse[]> {
    const response = await this.boardsService.findBoardsByPriority(priority);
    return response;
  }
}

🚀 실행 및 테스트

재대로 연결이 되는지 Postman 과 Swagger 등으로 확인해봅니다.

🧐 Deep Dive: 꼭 알아야 할 TypeORM 핵심 개념

구현은 성공적으로 마쳤지만, 그냥 넘어가기엔 중요한 개념들을 확실히 짚고 넘어 갑니다.

설정 부분을 제외하면 JPA 와 매우 유사하지만, Node.JS 의 특성과 TypeORM 만의 철학에 따라 다른 부분이 있습니다.

Data Mapper vs Active Record 패턴

TypeORM은 두 가지 패턴을 모두 지원합니다.

이번 글에서 우리는 Data Mapper 패턴을 사용하여 구현했습니다.

🅰️ Active Record 패턴

엔티티 클래스 내부에 데이터베이스 접근 로직(save, remove, find 등)을 정의하는 방식입니다.

코드 예시: user.save(), Board.find()
특징: 모델 안에 비즈니스 로직과 DB 로직이 섞여 있습니다. (Ruby on Rails 스타일)
장점: 소규모 프로젝트에서 매우 빠르고 직관적입니다.

🅱️ Data Mapper 패턴 (우리가 사용한 방식)

엔티티는 순수한 데이터 객체(POJO)로 남고, DB 접근 로직은 Repository라는 별도 클래스가 담당합니다.

코드 예시: boardRepository.save(board)
특징: 도메인 객체와 영속성 로직이 분리되어 있습니다.
장점: Spring Data JPA와 철학이 같습니다. 대규모 애플리케이션에서 유지보수가 좋고, 테스트 작성이 훨씬 수월합니다.

[Spring 개발자 Note]
우리는 익숙하고 구조적인 Data Mapper(Repository) 패턴을 선택했습니다. 엔티티를 가볍게 유지하고, 관심사를 분리하기 위함입니다.

👉 [공식 문서] Active Record vs Data Mapper 더 알아보기
TypeORM Official - Active Record vs Data Mapper

왜 `async / await`를 써야 할까? (동기 vs 비동기)

Spring(Java)에서는 Repository에서 데이터를 가져올 때 단순히 리턴값을 받았습니다.

public Board findBoard(Long id) {
    // DB에서 데이터를 가져올 때까지 스레드가 멈춰서 기다림
    return repository.findById(id); 
}

하지만 NestJS(Node.js)는 싱글 스레드 이벤트 루프 기반입니다.

DB에 다녀오는 동안 스레드를 멈춰버리면(Blocking), 그 시간 동안 서버는 다른 요청을 전혀 처리하지 못하고 멈춰버립니다.

// NestJS (Non-Blocking I/O)
async findBoard(id: string): Promise<Board> {
    // await: "DB야, 데이터 가져올 때까지 난 딴 일 하고 있을게. 다 되면 알려줘."
    // 이 시점에 스레드는 해제되어 다른 요청을 처리합니다.
    return await this.repository.findOneBy({ id }); 
}

Promise: "지금은 데이터가 없지만, 나중에 완료되면 값을 주겠다"는 약속 객체입니다.
Async / Await: 비동기 코드를 마치 동기 코드처럼(위에서 아래로) 읽히게 만들어주는 문법입니다.

결론: Node.js 환경에서 DB 접근과 같은 I/O 작업은 반드시 비동기(async/await)로 처리해야 서버의 성능을 온전히 사용할 수 있습니다.

Custom Repository와 `super()`의 비밀

TypeORM 0.2 버전까지는 @EntityRepository라는 데코레이터를 사용했지만, 0.3 버전부터는 Deprecated(사용 중단) 되었습니다.

그래서 우리는 Repository 클래스를 상속받고 DataSource를 주입받는 방식을 사용했습니다.

@Injectable()
export class BoardsRepository extends Repository<Board> {
  constructor(private dataSource: DataSource) {
    // 💡 부모(Repository) 클래스 초기화
    super(Board, dataSource.createEntityManager());
  }
}

이 코드는 다음과 같은 의미를 가집니다.

extends Repository<Board>: "나는 Board 엔티티를 다루는 TypeORM의 기본 기능(find, save, delete 등)을 물려받아 쓰겠다."
super(...): "부모 클래스야, 나는 Board 엔티티를 쓸 거고, 현재 연결된 DB(DataSource)의 매니저를 사용할 거야. 세팅해 줘."

이렇게 하면 TypeORM의 강력한 기본 메서드를 그대로 사용하면서, 우리만의 커스텀 비즈니스 로직(createBoard 등)을 추가 확장할 수 있습니다.

👉 [공식 문서] Custom Repository 생성 방법
TypeORM Official - Custom Repositories

`synchronize: true` 옵션의 치명적인 함정 🚨

우리는 typeorm.config.ts에서 synchronize: true 옵션을 켜두었습니다.

이 옵션은 Spring JPA의 ddl-auto: update와 매우 유사합니다.

기능: 애플리케이션 실행 시, 엔티티(Entity)와 데이터베이스 스키마를 비교하여 변경된 부분(컬럼 추가, 삭제, 타입 변경 등)을 자동으로 DB에 반영합니다.
장점: 개발 초기 단계에서는 DB 테이블을 일일이 수정할 필요가 없어 생산성이 매우 높습니다.

⚠️ 하지만 운영 환경(Production)에서는 절대 사용하면 안 됩니다!

만약 운영 서버에서 이 옵션이 켜져 있다면 어떤 일이 벌어질까요?

실수로 엔티티의 필드명을 바꾸거나 타입을 변경해서 배포했습니다.
서버가 재시작되면서 TypeORM이 이를 감지합니다.
데이터가 들어있는 기존 컬럼을 DROP(삭제)하고 새로 생성할 수 있습니다.
결과: 대규모 데이터 유실 사고 발생 😱

✅ 올바른 운영 환경 관리 전략

따라서 실무에서는 환경(Environment)에 따라 설정을 분리해야 합니다.

로컬/개발 환경 (Local/Dev):
- synchronize: true (빠른 개발을 위해 허용)
운영 환경 (Production):
- synchronize: false (필수)
- Migrations 사용: DB 스키마 변경은 반드시 이력 관리가 가능한 마이그레이션 도구를 사용해야 합니다.

[대안 1] TypeORM Migrations (공식 권장)
TypeORM 내장 기능을 사용하여 엔티티 변경 사항을 SQL 파일로 생성하고, 배포 시점에 migration:run 명령어로 안전하게 반영합니다.
[대안 2] Flyway / Liquibase (Spring 개발자에게 익숙함)
Spring 생태계에서 쓰이는 Flyway 등을 NestJS에서도 똑같이 사용할 수 있습니다.
SQL 스크립트를 직접 작성하여 버전 관리하는 방식입니다.
[대안 3] DBA 검수 후 직접 실행
가장 보수적인 방법으로, 변경된 DDL(CREATE, ALTER) SQL을 DBA가 검수한 뒤 직접 DB에 접속하여 실행합니다.

결론: synchronize: true는 오직 내 컴퓨터(Local)에서만 쓰세요. 운영 환경 설정 파일(.env.prod)에서는 반드시 꺼져 있는지 두 번 확인해야 합니다.

👉 [공식 문서] Migrations 가이드
TypeORM Official - Migrations

🚀 마무리

이번 포스팅에서는 TypeORM을 사용하여 PostgreSQL 데이터베이스를 연동하고, Custom Repository 패턴을 통해 데이터를 안전하게 저장하는 방법을 알아보았습니다.

Docker Compose로 DB 환경 구축
TypeORM 설정 및 연결 (synchronize 옵션 주의)
Repository Pattern을 통한 계층 분리

저 또한 학습하면서 진행한 것이라 완벽하게 100% 정답이 아닐 수 있습니다.

또한 다음 글은 없습니다. 실제로 좀 더 써봐야 어떤 부분을 정리하고 주의해야 하는지 알 것 같습니다.

[NestJS] TypeORM을 사용해 Postgres 연동하기

스택 시리즈NestJS 스택