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을 명시해서 넘겨야 한다.
- 예전 노트에 "필드 5개 중 2개만 넘기면 나머지 3개가 사라진다"고 적었는데 틀렸다. 빈 값으로 지우고 싶으면
- 저장이 끝나면 생성된 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()