조용히 비어버린 값 하나에서 시작한 ORM 메이저 업그레이드 검증 전략New

📚 Overview

최근 사내 패키지 업데이트와 더불어 NestJS 12+ / MikroORM v7+ 로 버전 업데이트를 진행했다.

대부분은 타입 에러를 지우고 변경된 API를 따라가는, 예상 범위 안의 작업이었다.

그 과정에서 유독 오래 붙잡고 있었던 문제가 하나 있었다. MikroORM 업데이트 중, 임베디드 값 객체(Value Object)로 매핑한 필드가 특정 조회 경로에서만 조용히 비어버리는 현상이었다.

에러도 불분명했고, 타입 에러조차 나지 않았다. 컴파일은 통과하고 런타임에서만 값이 사라지는 형태라, e2e 시나리오가 아니었다면 아마 조용히 배포되어 운영에서 마주쳤을 문제였다.

이와 더불어 자연스럽게 따라온 질문이 있었다. 다른 지점에서도 같은 성격의 이슈가 더 있지 않을까?

그래서 e2e 시나리오의 검증 축을 옮겼다. 단순히 “응답이 같은가”를 확인하는 것에 더불어, “발행되는 쿼리가 같은가” 에 포커스를 맞추는 방향으로.

이번 포스팅은 그 판단의 과정과, 그래서 만들게 된 쿼리 헬퍼·마이그레이션 전용 테스트·CI 설계를 기록으로 남기고자 한다.

1. 조용히 비는 값 — 임베디드 VO와 컬럼 이름 충돌

문제가 된 구조는 이렇다. 사용자 엔티티가 비밀번호를 값 객체로 감싸 임베디드로 매핑하고 있었다.

값 객체는 형식 검증과 해싱 책임을 갖고, 실제 저장은 컬럼 하나로 떨어진다.

// 값 객체 쪽 — 자식 속성 value 가 실제 컬럼 password 로 저장된다
export const PasswordSchema = new EntitySchema<Password>({
  class: Password,
  embeddable: true,
  properties: {
    value: {
      fieldName: 'password',
      type: 'string',
    },
  },
});

// 사용자 엔티티 쪽 — prefix 를 비워 자식 컬럼을 그대로 쓴다
export const UserSchema = new EntitySchema<User>({
  class: User,
  properties: {
    // ...
    password: {
      kind: ReferenceKind.EMBEDDED,
      entity: () => Password,
      prefix: '',
    },
  },
});

User 엔티티에 선언한 임베디드 프로퍼티 이름(password)과, 그 안의 value 가 실제로 저장되는 컬럼 이름(password)이 같다는 점이 핵심이다.

v6에서는 이 구성이 문제없이 동작했다. 그래서 오랫동안 아무도 의심하지 않았다.

v7로 올린 뒤, 사용자와 관계를 함께 조회하는 경로에서만 실패가 나타나기 시작했다.

관계를 JOIN으로 붙여 한 번에 가져오는 전략에서는 아래처럼 컬럼마다 별칭이 붙는다.

select `e0`.*,
       `u1`.`user_id` as `u1__user_id`,
       `u1`.`password` as `u1__password`   -- 이 별칭이 문제의 출발점
from `exchange_requests` as `e0`
inner join `users` as `u1` on `e0`.`user_id` = `u1`.`user_id`

별칭을 다시 프로퍼티로 되돌리는 단계에서, ORM은 password라는 이름을 컬럼보다 프로퍼티 메타데이터에서 먼저 찾는다.

그런데 그 이름으로 가장 먼저 매칭되는 것은 실제 값을 담는 자식 컬럼이 아니라, Password 임베더블을 가리키는 프로퍼티 자체다.

이 프로퍼티는 하나의 이름이 여러 컬럼으로 펼쳐지는 복합 프로퍼티이기 때문에, 단일 컬럼의 값을 받아야 하는 자리에 놓이는 순간 매핑이 성립하지 않는다.

원인을 찾는 데 시간이 걸린 이유는 세 가지였다.

• 타입 검사로는 전혀 보이지 않는다. 스키마도 엔티티도 정상적인 타입이다.
• User 엔티티만 단독으로 조회할 때는 정상이다. 다른 엔티티에서 User 를 함께 불러오는 경로에서만 깨진다.
• 실패 지점이 도메인과 멀다. 쿼리 조립 내부에서 터지므로, 로그만 보면 비밀번호 매핑이 원인이라는 단서가 없다.

정리하면 “업그레이드로 인해 런타임 규칙이 바뀌었는데, 그 변화가 검증되지 않은 채 특정 경로에서만 조용히 드러나는” 형태였다.

최종적으로 택한 해법은 이름 충돌 자체를 없애는 것이었다.

// 임베디드 프로퍼티 이름을 컬럼 이름과 분리하고, 프로퍼티가 점유할 키 이름도 fieldName 으로 따로 지정한다
hashedPassword: {
  kind: ReferenceKind.EMBEDDED,
  entity: () => Password,
  prefix: '',
  fieldName: '_password',
},

이 방법을 고른 이유는 DB 스키마를 전혀 건드리지 않기 때문이다. 컬럼 이름은 그대로 password이므로 마이그레이션이 필요 없고, 구버전 애플리케이션과의 공존도 그대로 유지된다.

이 지점이 중요했던 건, 롤링 배포 과정에서 스키마 마이그레이션을 함께 진행하는 것이 부담스러웠기 때문이다.

컬럼 이름을 바꾸는 선택을 했다면 신규 필드 추가 → 마이그레이션 → 구/신 필드 병행 조회(하위 호환) → deprecated 필드 제거 라는 단계를 밟아야 한다.

배포 중 두 버전의 애플리케이션이 같은 테이블을 동시에 바라보는 구간이 생기고, 각 단계마다 별도의 배포와 검증이 따라붙는다. 이번 문제의 크기에 비해 지불해야 할 비용이 지나치게 비싸다고 판단했다.

반면 프로퍼티 이름만 바꾸는 선택은 변경이 애플리케이션 코드 안에서 끝난다. 배포 순서에 제약이 없고, 되돌리는 것도 코드 되돌리기 한 번이면 된다.

검토했다가 접은 대안도 남겨둔다.

• 커스텀 매핑 타입으로 교체: 메인테이너가 단일 속성 임베더블 대신 권고하는 방향이다(discussion #3685). 구조적으로는 가장 깨끗하지만, 값 객체가 가진 검증·해싱 책임을 타입 변환 계층으로 옮겨야 해서 변경 범위가 컸다.
• 전역 로딩 전략을 별도 쿼리 방식으로 고정: JOIN 별칭을 만들지 않게 하는 우회다. 그러나 쿼리 빌더에서 명시적으로 조인해 함께 select하는 코드가 남아 있으면 그대로 실패한다. 무엇보다 문제를 덮는 선택이었다.
• 접두사 설정을 끄고 값 객체 쪽에 필드명을 주는 방식: 과거에 비슷한 회피를 시도한 선례가 있었지만, 값 객체의 캡슐화를 깨뜨리는 대가가 따라왔다.

2. 응답 비교만으로는 잡히지 않는 변화 — 발행 쿼리 수를 계약으로 만들기

이 이슈를 넘기고 나니 더 신경 쓰이는 것은 같은 성격의 문제가 또 있는데 아직 안 보이는 것 아닐까 하는 점이었다.

메이저 업그레이드에서 위험한 변화는 대체로 이런 모양을 한다.

• 응답 JSON은 완전히 동일하다.
• 그런데 내부에서 발행되는 SQL은 달라졌다.
• 그 차이가 실행 계획을 바꾸거나, 특정 조건에서만 값이 비게 만든다.

e2e 테스트는 응답을 검증하므로 이 변화를 구조적으로 통과시킨다. 실제로 이번 업그레이드에서도 CI는 전부 초록이었다.

그래서 발행 쿼리 자체를 관측 대상으로 끌어올리는 헬퍼를 만들었다. 커넥션이 SQL을 실행하는 단일 지점을 감싸 호출 횟수를 센다.

export function installQueryCounter(orm: MikroORM): QueryCounter {
  const connection = orm.em.getConnection();
  const original = connection.execute;
  let executed = 0;

  // 원본의 반환값과 예외를 그대로 통과시킨다 — 동작을 바꾸면 안 된다
  connection.execute = (...args) => {
    executed += 1;
    return original.apply(connection, args);
  };

  return {
    count: () => executed,
    reset: () => {
      executed = 0;
    },
    restore: () => {
      connection.execute = original;
    },
  };
}

여기서 한 가지 결정을 했다. SQL 문자열을 그대로 단언하지 않는다.

기대값으로 SQL을 박아두면 테스트는 강력해지지만, 동시에 구현을 고정해버려 재작성 자체를 막는다. 업그레이드 과정에서는 쿼리를 바꾸는 것이 목적인데, 그 목적과 정면으로 충돌한다.

대신 계약을 두 가지로 잡았다.

1. 입력과 출력 — 같은 조건에 같은 결과, 같은 총 건수.
2. 발행 쿼리 수의 상한과 하한.

/**
 * 시나리오별 발행 쿼리 수 상한.
 * 업그레이드 이전 버전에서 실제로 측정한 값을 그대로 기대값으로 삼는다.
 * 재작성 결과가 이 값을 넘으면 N+1 이 생겼거나 로딩 전략이 바뀐 것이다.
 */
const QueryCountLimits = {
  // find 옵션에 populate 를 함께 넘겨 연관을 한 번에 가져오는 경로
  inlinePopulate: 4,
  // 루트를 먼저 조회한 뒤 em.populate() 로 연관을 나중에 채우는 경로
  populateAfterFind: 4,
  // to-one 관계만 두 단계로 타고 들어가는 중첩 조회 경로
  nestedToOneOnly: 3,
  // to-one 관계 하나만 함께 가져오는 가장 단순한 경로
  toOneOnly: 2,
} as const;

/**
 * 시나리오별 발행 쿼리 수 하한.
 * 루트 조회 1회 + populate 가 타고 들어가는 계층마다 최소 1회가 필요하므로,
 * 어떤 전략을 쓰더라도 이보다 적게 나올 수는 없는 값이다.
 * (예: toOneOnly 는 JOIN 으로 합쳐도 최소 1회, 별도 쿼리라면 2회)
 *
 * 이 값이 필요한 이유는 상한 단언만으로는 "쿼리가 너무 적게 나온 경우"를 잡을 수 없기 때문이다.
 * 카운터가 SQL 발행 지점을 놓쳐 0 을 세더라도 상한은 만족하므로 테스트가 통과해버린다.
 */
const QueryCountFloors = {
  /* ... */
} as const;

하한을 함께 둔 이유가 꽤 중요하다. 래퍼가 어떤 실행 경로를 놓쳐 카운트가 0이 되어도, 상한 단언만 있으면 테스트는 그대로 통과한다. 이 경우 테스트는 아무것도 검증하지 못하면서 통과 신호만 보내게 된다.

이 축을 잡고 나니 v7의 기본 로딩 전략 변경(balanced)처럼 쿼리 개수 자체가 달라지는 변화도 테스트가 말해주게 되었다.

3. 마이그레이션 전용 테스트와, 떼어내기 쉬운 CI 구성

다음 문제는 “이 테스트들을 어디에 둘 것인가”였다.

이번에 추가한 테스트들은 처음부터 한시적인 성격이었다.

v6 에서 knex API 를 직접 쓰고 있던 일부 쿼리를 쿼리 빌더 기반으로 재작성해야 했고, 이 테스트들은 그 재작성이 기존 동작을 그대로 유지하는지 확인하기 위한 장치였다.

바꿔 말하면, 재작성이 끝나고 검증까지 마치면 역할도 함께 끝난다. 그 이후로는 CI 컨테이너 실행 시간만 늘릴 뿐이다.

그래서 마이그레이션 전용 디렉터리를 따로 만들어 그 아래에만 모았다. 디렉터리째 지우면 테스트도, CI 설정도 함께 정리되는 구조를 원했다.

계약의 축이 HTTP 응답이 아니라 입출력과 발행 쿼리 수였기 때문에, 컨트롤러를 거치지 않고 애플리케이션 컨텍스트에서 쿼리를 직접 디스패치하도록 했다.

/**
 * 쿼리 재작성 전 동작을 계약으로 고정하는 쿼리 전용 테스트용 헬퍼.
 * 계약 축이 SQL 문자열이 아니라 입출력과 발행 쿼리 수라, HTTP 대신 버스로 직접 디스패치한다.
 */
export async function createQueryTestContext(): Promise<QueryTestContext> {
  const app = await createE2eApp();

  return { ...app, queryBus: app.get(QueryBus) };
}

CI에서는 e2e 를 도메인 단위로 나눠 병렬 실행하고 있었는데, 이 디렉터리는 도메인 구조 밖에 있어 자동 탐색에 걸리지 않았다.

그래서 탐색 스크립트를 조금 손봤다. 마이그레이션 디렉터리가 있을 때만 실행 그룹을 하나 덧붙이고, 디렉터리를 지우면 그 그룹도 같이 사라지게 했다.

여기에 검사를 하나 더 넣었다. 어느 실행 그룹에도 잡히지 않는 e2e 파일이 있으면 CI 를 실패시키는 것이다. 로컬 jest 는 파일 위치와 무관하게 긁어가기 때문에, 위치를 잘못 두면 로컬에서는 멀쩡히 돌고 CI 에서는 그 파일의 존재조차 모른 채 조용히 성공한다. 위치를 사람이 매번 기억하는 것보다는 스크립트가 걸러주는 편이 낫다고 봤다.

테스트를 다 짜고 나니 한 가지가 더 궁금해졌다. 지금 이 테스트가 보장하는 건 결국 내가 작성한 시나리오 안에서 쿼리가 같다는 것뿐인데, 운영에서 실제로 나가는 쿼리와 비교하면 어떨까?

마침 운영 APM 이 DB 스팬에 SQL 본문을 그대로 남기고 있었다. 덕분에 배포하지 않고도 운영이 발행한 쿼리를 꺼내볼 수 있었다.

같은 API 경로를 로컬에서 새 버전으로 실행해 SQL 을 모으고, 양쪽을 정규화(공백 축약, 리터럴을 자리표시자로 치환)해서 비교했다.

• 가장 크게 재작성한 집계 쿼리: 정규화 후 959자가 전부 일치
• UNION 파생 테이블을 쓰는 검색 쿼리: 구조는 같고 각 갈래를 괄호로 감싸는 표기만 차이
• 값 객체 문제를 고친 뒤의 JOIN 별칭: 운영과 완전히 동일

🤔 Understanding

이번 업그레이드에서 얻은 교훈은, 메이저 버전 변경이 타입으로 드러나지 않는 런타임 규칙까지 함께 바꾼다는 점이다.

공식 업그레이드 가이드에도 조용히 동작이 달라지는 항목들이 분명히 적혀 있다.

Change detection is no longer automatic on scalar properties, an explicit em.persist call is required now

Both are now enabled by default, and the auto-fixing mechanism is removed.

Default loading strategy is balanced

세 줄 모두 컴파일러가 알려주지 않고, 응답만 보는 테스트도 알려주지 않는다. 검증의 축을 결과에서 쿼리로 옮긴 것이 이번 작업에서 가장 값어치 있는 결정이었다고 생각하는 이유다.

임베디드 값 객체 이야기로 돌아가면, 프로퍼티 이름과 컬럼 이름을 맞추는 방식은 오래전부터 이어온 팀 컨벤션이었다. v6 에서는 문제없이 동작했으니 누구도 의심할 이유가 없었고, 그 컨벤션이 v7 에서 어긋난 것 자체는 우리가 감당할 몫이라고 생각한다.

다만 하나의 프로퍼티 이름이 여러 컬럼으로 펼쳐지는 구조가 단일 컬럼 자리에 놓였다면, ORM 이 진단 가능한 메시지를 주는 편이 맞다고 본다. 지금은 조회 경로에 따라 값이 비는 형태로만 드러나서 원인까지 도달하는 거리가 너무 멀었다.

같은 사례의 업스트림 이슈는 찾지 못했다. 재현 조건을 좁히고 “버그”로 볼지 “진단 메시지 개선 요청”으로 볼지 스스로 먼저 결론을 낸 뒤, 최소 재현 저장소와 함께 제보해볼 생각이다. 메인테이너가 이미 단일 속성 임베더블보다 커스텀 타입을 권고하고 있으니, 설계를 그대로 둔 채 동작만 바꿔달라는 요구가 되지 않도록 다듬는 일이 먼저다.

참고 자료

• MikroORM 공식 문서 — Upgrading from v6 to v7
• MikroORM 7 릴리스 노트
• Discussion #3685 — 값 객체 매핑에 대한 메인테이너 권고
• MikroORM 공식 문서 — Embeddables