TypeORM으로 개발하면서 엔티티를 정의할 때, 나는 주로 이렇게 작성했다:

@Entity()
export class Post {
@Column()
title: string;

@Column()
content: string;

@Column()
likes: number;

@Column()
isPublished: boolean;
}

TypeScript의 타입만 지정하고, 데이터베이스 컬럼 타입은 TypeORM의 타입 추론에 맡기는 방식이다. 편하고 간단하다. '잘 알아서 해주겠지(해줘!)'식 코딩을 했는데 이 방식에는 생각보다 많은 위험이 존재했다.

TypeORM의 타입 추론 결과

그렇다면 TypeORM은 TypeScript 타입을 어떻게 데이터베이스 타입으로 변환할까? PostgreSQL 기준으로 실제 생성되는 테이블 구조를 살펴보자.

@Entity()
export class TestEntity {
@Column()
numberField: number;

@Column()
stringField: string;

@Column()
boolField: boolean;

@Column()
dateField: Date;
}

위 엔티티는 다음과 같은 PostgreSQL 테이블로 생성된다:

CREATE TABLE test_entity (
"numberField" integer NOT NULL,
"stringField" character varying NOT NULL, -- 길이 제한 없음!
"boolField" boolean NOT NULL,
"dateField" timestamp NOT NULL -- 타임존 없음!
);

추론 결과 분석

number → integer: 대부분INTEGER로 추론된다

string → varchar: 길이 제한이 없는CHARACTER VARYING으로 생성

boolean → boolean: PostgreSQL의BOOLEAN타입

Date → timestamp: 타임존 정보가 없는TIMESTAMP

언뜻 보면 문제없어 보이지만, 실제로는 여러 문제를 야기할 수 있다.

타입을 명시해야 하는 이유

1. 데이터베이스마다 다른 추론 결과

TypeORM의 타입 추론은 데이터베이스마다 다르게 동작한다.

PostgreSQL:

stringField character varying -- 길이 제한 없음
boolField boolean

MySQL:

stringField varchar(255) -- 기본 255자 제한
boolField tinyint(1) -- 0 또는 1

SQLite:

stringField text
boolField integer -- 0 또는 1

같은 엔티티 정의라도 데이터베이스마다 다른 스키마가 생성되며, 이는 마이그레이션 시 예상치 못한 문제를 일으킬 수 있다.

2. 성능 문제 발생 가능

@Entity()
export class Post {
@Column()
@Index() // 인덱스 생성 시도
title: string;
}

PostgreSQL에서 길이 제한 없는 VARCHAR는 인덱스 생성이 비효율적이거나 실패할 수 있다. 인덱스는 고정된 크기의 컬럼에서 가장 효율적으로 작동하기 때문이다.

올바른 방식:

@Column('varchar', { length: 255 })
@Index()
title: string;

3. 의도하지 않은 타입 사용

@Column()
price: number; // → double precision으로 추론

금액 필드에 부동소수점 타입이 사용되면 정밀도 문제가 발생한다:

// 9.99 + 0.01 = 10.000000000001

금액은 반드시 DECIMAL 타입을 사용해야 한다:

@Column('decimal', { precision: 10, scale: 2 })
price: number;

4. 타임존 정보 손실

@Column()
createdAt: Date; // → timestamp (타임존 없음)

글로벌 서비스에서 타임존 정보가 없으면 시간 계산에 오류가 발생한다. 서머타임이나 다른 국가의 사용자를 고려하면 TIMESTAMPTZ를 사용해야 한다:

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

타입 변경 시 마이그레이션이 필요한 이유

엔티티 정의만 수정한다고 데이터베이스 스키마가 자동으로 바뀌지는 않는다. (물론 synchronize: true를 사용하면 자동으로 바뀌지만, 실무에서는 절대 사용하면 안 되는 옵션이다.)

synchronize 옵션의 위험성

synchronize: true

synchronize: true는 엔티티 변경 시 기존 테이블을 DROP하고 재생성할 수 있어, 프로덕션 데이터가 삭제될 위험이 있다.

타입 변경 예시

// 기존
@Column()
views: number; // integer

// 변경
@Column('bigint')
views: string; // bigint

이렇게 엔티티만 수정하면 애플리케이션 코드와 실제 데이터베이스 스키마가 불일치하게 된다. 반드시 마이그레이션을 생성하고 실행해야 한다:

npm run typeorm migration:generate -- src/migrations/UpdateViewsToBigint
npm run typeorm migration:run

생성된 마이그레이션 파일:

export class UpdateViewsToBigint1234567890 implements MigrationInterface {
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE "post" ALTER COLUMN "views" TYPE bigint`
);
}

public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE "post" ALTER COLUMN "views" TYPE integer`
);
}
}

안전한 마이그레이션: 확장 방향으로만

타입을 변경할 때는 확장 방향으로만 변경하는 것이 안전하다. 확장 방향이란 기존 데이터를 모두 수용할 수 있는 더 큰 타입으로 변경하는 것을 의미한다.

안전한 타입 변경 (확장 방향)

varchar(255) → text

위험한 타입 변경 (축소 방향)

text → varchar(255)

축소 방향으로 변경해야 한다면, 반드시 기존 데이터를 확인하고 안전하게 마이그레이션해야 한다:

export class ShrinkTitleLength1234567890 implements MigrationInterface {
public async up(queryRunner: QueryRunner): Promise<void> {
// 1. 먼저 데이터 확인
const longTitles = await queryRunner.query(
`SELECT id, title FROM post WHERE LENGTH(title) > 100`
);

if (longTitles.length > 0) {
// 2. 긴 제목들을 잘라내거나 다른 처리
for (const row of longTitles) {
await queryRunner.query(
`UPDATE post SET title = SUBSTRING(title, 1, 100) WHERE id = $1`,
[row.id]
);
}
}

// 3. 타입 변경
await queryRunner.query(
`ALTER TABLE "post" ALTER COLUMN "title" TYPE varchar(100)`
);
}
}

올바른 타입 명시 방법

기본 원칙

// ❌ 최소 버전 (추론에 의존)
@Column()
title: string;

// ✅ 권장 버전 (명확한 타입 지정)
@Column('varchar', { length: 255 })
title: string;

타입이 제대로 적용된 완전한 엔티티 예시

내 블로그에서 사용하는 PostEntity에 제대로 타입을 먹이면 어떻게 될까? 아래는 AI에게 엔티티에 타입 먹여달라해서 뽑은 결과다.

import {
Entity,
PrimaryGeneratedColumn,
Column,
CreateDateColumn,
UpdateDateColumn,
Index,
ManyToOne,
JoinColumn,
} from 'typeorm';

@Entity('posts')
export class PostEntity {
@PrimaryGeneratedColumn('increment')
id: number;

@Column('varchar', { length: 255 })
@Index()
title: string;

@Column('text')
content: string;

@Column('text', { nullable: true })
previewText: string | null;

@Column('varchar', { length: 500, nullable: true })
thumbnailUrl: string | null;

@Column('integer', { default: 0 })
@Index()
likes: number;

@Column('integer', { default: 0 })
@Index()
views: number;

@Column('boolean', { default: false })
isPublished: boolean;

@Column('decimal', { precision: 10, scale: 2, nullable: true })
price: number | null;

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

@UpdateDateColumn({ type: 'timestamptz' })
updatedAt: Date;

@ManyToOne(() => UserEntity, { onDelete: 'CASCADE' })
@JoinColumn({ name: 'author_id' })
author: UserEntity;

@Column({
type: 'enum',
enum: PostTypeEnum,
default: PostTypeEnum.PUBLIC,
})
type: PostTypeEnum;
}

타입별 가이드라인

ID (자동 증가 정수)

@PrimaryGeneratedColumn('increment') // SERIAL → INTEGER
id: number;

짧은 문자열 (제목, 이름, 이메일)

@Column('varchar', { length: 255 })
title: string;

긴 문자열 (본문, 설명)

@Column('text')
content: string;

작은 정수 (나이, 평점)

@Column('smallint') // -32,768 ~ 32,767
age: number;

일반 정수 (조회수, 좋아요)

@Column('integer') // -21억 ~ 21억
likes: number;

큰 정수 (타임스탬프, 글로벌 ID)

@Column('bigint')
timestamp: string; // JavaScript의 number는 2^53까지만 안전

금액 (정확한 소수)

@Column('decimal', { precision: 10, scale: 2 })
price: number;

불리언

@Column('boolean', { default: true })
isActive: boolean;

날짜/시간 (타임존 포함)

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

Nullable 필드

@Column('text', { nullable: true })
description: string | null; // TypeScript 타입도 null 허용

... 머 요런 식으로 지정해주는게 좋다고 한다.

정리

TypeORM의 타입 추론은 편리하지만, 프로덕션 환경에서는 예상치 못한 문제를 일으킬 수 있다. 특히:

데이터베이스마다 다른 추론 결과로 마이그레이션 충돌 발생

성능 문제(인덱스 생성 실패, 비효율적인 쿼리)

데이터 오버플로우(정수 범위 초과)

정밀도 문제(금액 계산 오차)

타임존 정보 손실(글로벌 서비스에서 시간 오류)

처음부터 명확한 타입을 지정하는 것이 번거로워 보일 수 있지만, 장기적으로는 훨씬 안전하고 유지보수하기 쉬운 코드를 만들 수 있다.

마치며

사실 이 글을 쓰면서 회사 코드도 다시 봤는데 타입이 명시되어 있지 않고 타입 추론에 맡기는 경우도 꽤 많았다. 다른 개발자 포럼에도 물어봤는데, 타입추론에 의존하는 사람들도 분명 존재하긴 하지만 물론 타입 명시하는게 좋다고 FM적으로 말하는 분들이 물론 더 많긴 했다. 앞으로는 꼭 지정해주는걸루 하자..