TypeORM과 TypeScript로 데이터베이스 구축

개요

TypeORM은 TypeScript와 자연스럽게 어울리는 ORM이다. 엔티티를 클래스와 데코레이터로 정의하고, 데이터베이스 마이그레이션을 관리할 수 있다. 이 글은 처음 접하는 개발자도 이해할 수 있게 프로젝트 초기화부터 마이그레이션, 간단한 CRUD 예제까지 설명한다. 주요 키워드는 TypeORM TypeScript 설정, TypeORM Node.js 예제, TypeORM 마이그레이션 사용법이다.

환경 준비

필수 도구

• Node.js LTS
• TypeScript
• 데이터베이스(MySQL, Postgres 등)

패키지 설치

프로젝트 생성 후 필요한 패키지를 설치한다.

npm init -y
npm install typeorm reflect-metadata mysql2
npm install -D typescript ts-node @types/node

TypeScript 설정

tsconfig.json을 간단히 구성한다. 중요한 옵션은 "experimentalDecorators"와 "emitDecoratorMetadata"다.

{
  "compilerOptions": {
    "target": "es2019",
    "module": "commonjs",
    "outDir": "dist",
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "esModuleInterop": true
  }
}

엔티티 작성

엔티티는 데이터베이스 테이블을 클래스로 표현한다. 데코레이터로 컬럼과 관계를 정의한다.

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

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

  @Column({ length: 100 })
  name: string;

  @Column({ unique: true })
  email: string;

  @CreateDateColumn()
  createdAt: Date;
}

데이터소스 설정

TypeORM v0.3 이상에서는 DataSource를 사용한다. 개발 환경과 프로덕션 환경을 분리한다.

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

export const AppDataSource = new DataSource({
  type: "mysql",
  host: process.env.DB_HOST || "localhost",
  port: Number(process.env.DB_PORT) || 3306,
  username: process.env.DB_USER || "root",
  password: process.env.DB_PASS || "password",
  database: process.env.DB_NAME || "test",
  entities: [User],
  migrations: ["src/migration/*.ts"],
  synchronize: false
});

마이그레이션 사용법

마이그레이션은 스키마 변경을 안전하게 적용한다. 개발 중에는 생성, 검토, 실행 순으로 관리한다.

• 마이그레이션 파일 생성: TypeORM CLI 또는 스크립트 사용
• 내용 검토 후 배포 환경에 적용

// 예: package.json scripts
{
  "scripts": {
    "typeorm": "ts-node ./node_modules/typeorm/cli.js",
    "migration:generate": "npm run typeorm -- migration:generate -n Initial",
    "migration:run": "npm run typeorm -- migration:run"
  }
}

위 명령으로 생성된 마이그레이션은 src/migration 폴더에 저장된다. 실행 전에는 항상 내용을 확인한다.

TypeORM Node.js 예제: 간단한 CRUD

AppDataSource를 초기화하고 리포지토리로 작업한다. 비동기 흐름을 명확히 관리하면 안정적이다.

import "reflect-metadata";
import { AppDataSource } from "./data-source";
import { User } from "./entity/User";

async function main() {
  await AppDataSource.initialize();
  const repo = AppDataSource.getRepository(User);

  // 생성
  const user = repo.create({ name: "Alice", email: "alice@example.com" });
  await repo.save(user);

  // 조회
  const list = await repo.find();
  console.log(list);

  // 업데이트
  user.name = "Alice Kim";
  await repo.save(user);

  // 삭제
  await repo.delete(user.id);

  await AppDataSource.destroy();
}

main().catch(console.error);

배포와 운영 고려사항

운영 환경에서는 synchronize 옵션을 끄고 마이그레이션으로 스키마를 관리한다. 연결 풀 설정과 타임아웃을 조정하고, 민감 정보는 환경변수로 관리한다. 대량 데이터 처리 시에는 배치와 인덱스 전략을 미리 설계한다.

결론

TypeORM은 TypeScript 환경에서 엔티티 기반 설계와 마이그레이션 관리를 통합해 준다. 처음에는 데이터소스와 엔티티 설정, 마이그레이션 워크플로우에 익숙해지는 것이 중요하다. 이후로는 리포지토리 패턴과 트랜잭션을 활용해 안정적인 애플리케이션을 운영하면 된다.