KSCOLD LogoKSCOLD
Blog
Feed
Product
Admin Night
Vault
Guestbook
Info

Vault 목록

TypeORM Repository 메서드 정리

연결된 노트와 함께 읽기

TypeORM Repository 메서드 정리

2026년 11월 5일
  • TypeORM의 리포지토리(Repository)가 제공하는 메서드(Method)를 조회·집계·저장·수정·삭제 순서로 한곳에 모은 노트다.
  • 예전에 메서드마다 따로 적어 두었던 짧은 노트들을 합치면서, 틀리게 적었던 내용(save()가 기존 필드를 지운다, maximun 오타 등)을 바로잡았다.
  • 기준 버전은 TypeORM 0.3이다. 0.2에서 쓰던 findOne(id)처럼 기본 키(Primary Key)만 넘기는 방식은 0.3에서 없어졌다.

한눈에 보기

  • 조회: find, findOne, findOneOrFail, findAndCount, exists, count
  • 집계: sum, average, minimum, maximum
  • 객체 만들기: create, preload
  • 저장: save, insert, upsert
  • 수정: update
  • 삭제: delete, remove, softDelete, restore
  • 메서드 이름 뒤에 By가 붙은 형태(findBy, findOneBy, countBy, existsBy)는 옵션 객체 대신 where 조건만 바로 받는다.
TypeScript

조회

find()

  • 조건에 맞는 행(Row)을 배열로 돌려준다. 조건이 없으면 테이블(Table) 전체를 가져온다.
  • 옵션으로 가져올 열(Column)(select), 조건(where), 정렬(order), 관계(relations), 페이지(skip·take)를 줄 수 있다. 옵션의 자세한 모양은 FindOptions와 FindOptionsWhere에 정리했다.
TypeScript

findOne()

  • 조건에 맞는 첫 번째 엔티티(Entity) 하나를 돌려주고, 없으면 null을 돌려준다.
  • 그래서 반환값이 null인 경우를 호출한 쪽에서 꼭 처리해야 한다.
TypeScript

findOneOrFail()

  • findOne()과 같지만, 찾지 못하면 null 대신 EntityNotFoundError를 던진다.
  • 없으면 안 되는 데이터를 읽을 때 null 검사를 반복하지 않아도 된다. 다만 HTTP 404로 바꿔 주는 건 직접 해야 한다(NestJS 예외 필터 등).

findAndCount()

  • 조건에 맞는 행과 전체 개수를 [rows, count] 튜플로 함께 돌려준다.
  • skip·take로 페이지를 잘라도 count는 자르기 전 전체 개수라서, 페이지네이션 화면을 만들 때 쿼리를 한 번 덜 쓸 수 있다.
TypeScript

exists()

  • 조건에 맞는 행이 있는지 boolean으로만 알려 준다(0.3.11부터).
  • 행 전체를 읽지 않으니 "이미 가입한 이메일인가?" 같은 검사에 findOne()보다 가볍다.
TypeScript

count()

  • 조건에 맞는 행의 개수를 돌려준다.
TypeScript

집계

  • sum(), average(), minimum(), maximum()은 0.3.12부터 있다. 예전 노트에 maximun, minimun으로 적었는데 오타였다.
  • 첫 번째 매개변수(parameter)는 계산할 숫자 열 이름, 두 번째는 where 조건이다.
  • 조건에 맞는 행이 하나도 없으면 0이 아니라 null이 나온다.
TypeScript

객체 만들기

create()

  • 엔티티 객체(Object)만 만드는 팩토리 메서드다. 데이터베이스(DataBase)에 쿼리(Query)를 보내지 않고, 그래서 await도 필요 없다.
  • 일반 객체 리터럴 대신 쓰는 이유는 엔티티 클래스의 인스턴스가 만들어져서 클래스에 정의한 기본값·메서드·리스너가 붙기 때문이다.
  • 실제로 저장하려면 이어서 save()나 insert()를 부른다.
TypeScript

preload()

  • 넘긴 객체의 기본 키(Primary Key)로 DB에서 엔티티를 읽어 온 뒤, 넘긴 값으로 속성(Property)을 덮어쓴 엔티티를 돌려준다.
  • DB에 그 키가 없으면 undefined를 돌려준다.
  • 덮어쓰기는 메모리에서만 일어나고 UPDATE는 나가지 않는다. 수정 API에서 "있는지 확인 + 바뀐 값 합치기"를 한 번에 할 때 쓰고, 마지막에 save()로 저장한다.
TypeScript

저장

save()

  • 기본 키가 없거나 DB에 없는 행이면 INSERT, 이미 있는 행이면 UPDATE를 한다.
  • 이미 있는 행이면 먼저 SELECT로 현재 값을 읽고, 실제로 바뀐 열만 UPDATE한다. 넘긴 객체에 없는 속성(undefined)은 건드리지 않는다.
    • 예전 노트에 "필드 5개 중 2개만 넘기면 나머지 3개가 사라진다"고 적었는데 틀렸다. 빈 값으로 지우고 싶으면 null을 명시해서 넘겨야 한다.
  • 저장이 끝나면 생성된 id·기본값이 채워진 엔티티를 돌려준다.
  • 기본으로 트랜잭션(Transaction) 안에서 실행되고, cascade가 걸린 관계도 같이 저장한다. 배열을 넘기면 여러 행을 한 번에 저장한다.
  • 편한 대신 SELECT가 앞에 붙으니 대량 저장에서는 insert()·update()보다 느리다.

insert()

  • 무조건 INSERT만 한다. 같은 기본 키·유니크 키가 이미 있으면 중복 키 에러(error)가 난다.
  • 앞에 SELECT가 없고 cascade도 처리하지 않아서 save()보다 빠르다.
  • 엔티티가 아니라 InsertResult(생성된 키 identifiers, 원본 결과 raw)를 돌려준다.

upsert()

  • "INSERT 해 보고 충돌하면 UPDATE"를 쿼리 하나로 처리한다.
  • 두 번째 매개변수에 충돌을 판단할 열(유니크 제약이 걸린 열)을 넘긴다.
  • PostgreSQL·SQLite에서는 ON CONFLICT ... DO UPDATE, MySQL에서는 ON DUPLICATE KEY UPDATE로 바뀐다. 쿼리가 하나라서 save()처럼 SELECT 후 저장하는 사이에 다른 요청이 끼어드는 문제가 없다.
TypeScript
SQL

수정

update()

  • 첫 번째 매개변수는 조건, 두 번째는 바꿀 값이다. 엔티티를 읽지 않고 UPDATE ... WHERE를 바로 보낸다.
  • 조건 자리에 숫자나 문자열 하나만 넘기면 기본 키 조건으로 쓴다.
  • UpdateResult를 돌려주고, affected로 몇 행이 바뀌었는지 알 수 있다.
  • 엔티티를 거치지 않기 때문에 @BeforeUpdate 같은 리스너와 cascade는 동작하지 않는다. @UpdateDateColumn은 TypeORM이 쿼리에 넣어 주므로 갱신된다.
  • 조건을 빈 객체로 주면 전체 테이블이 바뀔 수 있어서 TypeORM이 에러를 낸다.
TypeScript
SQL

삭제

delete()

  • 조건(보통 기본 키)에 맞는 행을 DELETE ... WHERE로 바로 지운다. 엔티티를 먼저 읽지 않아서 DB를 한 번만 다녀온다.
  • 지울 행이 없어도 에러가 나지 않는다. 결과로 받는 DeleteResult를 봐야 실제로 지워졌는지 알 수 있다.
    • affected: 지워진 행 수. 아무것도 못 지웠으면 0이다(드라이버에 따라 undefined일 수 있다).
    • raw: 드라이버가 돌려준 원본 결과. 직접 쓸 일은 드물다.
  • 그래서 API에서는 affected가 0이면 404를 직접 던진다. 예전 노트에 "delete()는 삭제를 못 해도 200을 보여준다"고 적었는데, 정확히는 TypeORM이 에러를 던지지 않아서 컨트롤러가 그대로 성공 응답을 내보내는 것이다.
TypeScript

remove()

  • 조건이 아니라 이미 읽어 온 엔티티 인스턴스를 받아서 지운다. 그래서 보통 findOne() 후 remove()로 DB를 두 번 다녀온다.
  • 엔티티를 거치므로 @BeforeRemove 리스너와 cascade 삭제가 동작한다.
  • 지운 엔티티를 돌려준다(id는 비워진다). HTTP 404 같은 건 TypeORM이 내지 않는다. 예전 노트의 "지우지 못하면 404"는 틀린 말이다.
  • 리스너나 cascade가 필요 없으면 delete()가 가볍다.

softDelete()와 restore()

  • softDelete()는 행을 지우지 않고 @DeleteDateColumn 열에 삭제 시각을 채운다. 그래서 이 열이 엔티티에 있어야 한다.
  • 소프트 삭제된 행은 find 계열 조회에서 자동으로 빠진다. 함께 보려면 withDeleted: true를 준다.
  • restore()는 그 시각을 다시 비워서 되살린다. 소프트 삭제한 행만 되살릴 수 있다.
  • 엔티티 인스턴스로 하고 싶으면 짝이 되는 softRemove()·recover()를 쓴다.
TypeScript

무엇을 쓸까

  • 하나 읽고 없으면 404: findOne() + null 검사, 또는 findOneOrFail()
  • 목록 + 전체 개수(페이지네이션): findAndCount()
  • 있는지만 확인: exists()
  • 새로 만들기: create() → save(), 대량이면 insert()
  • 일부 열만 수정: update(), 수정 전에 존재 확인과 값 합치기가 필요하면 preload() → save()
  • 있으면 수정·없으면 생성: upsert()
  • 지우기: 리스너·cascade가 필요 없으면 delete(), 필요하면 remove(), 복구 가능해야 하면 softDelete()

Synapse Map Insight

// 둘은 같은 쿼리다 await repository.find({ where: { firstName: 'Timber' } }); await repository.findBy({ firstName: 'Timber' });
const users = await repository.find({ select: { id: true, firstName: true }, where: { isActive: true }, order: { createdAt: 'DESC' }, take: 20, });
const user = await repository.findOne({ where: { id: 1 } }); if (!user) { throw new NotFoundException('사용자가 없습니다'); }
const [rows, total] = await repository.findAndCount({ where: { firstName: 'Code Factory' }, skip: 0, take: 10, });
const taken = await repository.exists({ where: { email } });
const count = await repository.count({ where: { firstName: 'Code Factory' }, });
const total = await repository.sum('age', { firstName: 'Timber' }); const avg = await repository.average('age', { firstName: 'Timber' }); const youngest = await repository.minimum('age', { firstName: 'Timber' }); const oldest = await repository.maximum('age', { firstName: 'Timber' });
const user = repository.create({ firstName: 'Timber', age: 30 }); await repository.save(user);
const user = await repository.preload({ id: 1, firstName: 'Code Factory' }); if (!user) throw new NotFoundException(); await repository.save(user);
await repository.upsert( [ { externalId: 'abc123', firstName: 'Code' }, { externalId: 'bca321', firstName: 'Factory' }, ], ['externalId'], );
INSERT INTO "user" ("externalId", "firstName") VALUES ('abc123', 'Code'), ('bca321', 'Factory') ON CONFLICT ("externalId") DO UPDATE SET "firstName" = EXCLUDED."firstName";
await repository.update({ age: 18 }, { category: 'ADULT' }); await repository.update(1, { firstName: 'Code Factory' });
UPDATE "user" SET "category" = 'ADULT' WHERE "age" = 18; UPDATE "user" SET "firstName" = 'Code Factory' WHERE "id" = 1;
async deleteBoard(id: number): Promise<void> { const result = await this.boardRepository.delete(id); if (result.affected === 0) { throw new NotFoundException(`Can't find Board with id ${id}`); } }
await repository.softDelete(1); await repository.find({ withDeleted: true }); await repository.restore(1);