TypeORM 개념 정리 — 객체와 데이터베이스를 동기화하는 방식

TypeORM을 처음 접할 때 가장 먼저 마주치는 질문은 “왜 SQL을 직접 쓰지 않는가”이다. 이 글은 ORM의 역할과 TypeORM의 핵심 기능을 코드 예시와 함께 정리한 기록이다.

ORM이란 무엇인가

ORM(Object-Relational Mapping)은 코드의 “객체”와 데이터베이스에 있는 “데이터”를 일치시켜주는 도구다. 더 구체적으로는, 개발자가 정의한 클래스(Entity)에 맞춰 SQL을 자동 생성해 데이터와 동기화하는 일을 담당한다.

직접 SQL을 작성할 때는 테이블 구조 변경이 코드에 반영되는 타이밍을 개발자가 관리해야 한다. ORM은 이 간극을 줄이기 위한 추상화 계층이다.

TypeORM의 주요 기능

객체 지향적 데이터베이스 조작 데이터베이스 테이블을 JavaScript 또는 TypeScript 클래스로 매핑한다. 테이블의 각 행은 클래스 인스턴스로 다뤄진다.

쿼리 언어의 대안 SQL 쿼리 대신 TypeScript로 작성된 메서드를 사용해 데이터베이스를 조작할 수 있다. find, save, delete 같은 메서드가 내부적으로 SQL로 변환된다.

자동 마이그레이션 Entity 클래스의 변경 사항을 데이터베이스 스키마에 자동으로 반영하는 기능을 제공한다. 마이그레이션 파일을 생성하거나, 개발 환경에서는 synchronize 옵션으로 즉시 반영할 수 있다.

트랜잭션 관리 여러 데이터베이스 작업을 원자적으로 묶어 실행하고, 실패 시 롤백하는 기능을 지원한다.

액티브 레코드 패턴 지원 데이터베이스 레코드를 객체처럼 다루는 Active Record 패턴을 지원한다. Entity 클래스 자체에 save(), remove() 같은 메서드를 직접 붙여 사용하는 방식이다.

synchronize: true가 필요한 이유

NestJS에서 TypeORM을 설정할 때 아래와 같은 코드를 마주친다.

TypeOrmModule.forRoot({
  type: 'better-sqlite3',
  database: 'db.sqlite',
  entities: [User, Report],
  synchronize: true,
}),

synchronize: true는 애플리케이션이 실행될 때마다 등록된 Entity 클래스의 구조를 읽어 데이터베이스 스키마와 자동으로 맞춰준다. Entity에 컬럼을 추가하거나 타입을 바꾸면, 별도의 마이그레이션 명령 없이 다음 실행 시 스키마에 반영된다.

개발 환경에서는 편리하지만, 프로덕션 환경에서는 이 옵션을 활성화하면 안 된다. 스키마 변경이 예고 없이 즉시 적용되므로, 기존 데이터가 손실되거나 서비스가 중단될 수 있다. 프로덕션에서는 synchronize: false로 두고 마이그레이션 파일을 명시적으로 관리하는 것이 안전하다.

정리

TypeORM은 SQL과 객체 사이의 변환 작업을 추상화해 개발 생산성을 높이는 도구다. synchronize 옵션은 그 추상화가 얼마나 편의를 제공하는지 단적으로 보여주는 예시이기도 하지만, 동시에 옵션의 의미를 정확히 이해하지 않으면 프로덕션에서 문제가 될 수 있다는 점을 초기에 짚어두었다면 더 명확히 사용할 수 있었을 부분이다.