[트러블슈팅] H2 예약어 컬럼명으로 인한 테이블 생성 실패 및 InitData 오류

TROUBLESHOOTING

H2 예약어 컬럼명으로 인한 테이블 생성 실패 및 InitData 오류

목차

• 1. 발생 배경
• 2. 문제
• 3. 원인 파악 과정
• 4. 해결
• 5. 참고
• 6. 배운 점

1. 발생 배경

리팩토링 단계에서 로컬 환경 통합 테스트를 위해 InitData를 작성했다. InitData는 애플리케이션 실행 시 테스트용 데이터를 DB에 자동으로 insert해주는 클래스다.

 

H2 인메모리 DB를 사용하는 로컬 환경에서는 애플리케이션을 실행할 때마다 데이터가 초기화된다. 매번 수동으로 테스트 데이터를 넣는 번거로움을 줄이기 위해 InitData를 작성했는데, 이후 애플리케이션 실행 시 monthly_goals 테이블을 찾지 못한다는 오류가 발생했다.

처음에는 InitData 실행 시점이 테이블 생성보다 빨라서 생긴 문제라고 생각했지만, 실제 원인은 H2 예약어를 컬럼명으로 사용해 테이블 생성 자체가 실패한 것이었다.

2. 문제

애플리케이션 실행 중 InitData가 테스트 데이터를 insert하는 시점에 monthly_goals 테이블을 찾지 못해 실행에 실패했다.

Table "MONTHLY_GOALS" not found; SQL statement:
insert into monthly_goals (created_at, goal_count, month, updated_at, user_id, year, id) values (...)

오류 메시지만 보면 단순히 테이블이 아직 생성되지 않은 상태에서 InitData가 먼저 실행된 것처럼 보였다.

3. 원인 파악 과정

1단계 - InitData 실행 시점 문제로 의심

처음에는 InitData 실행 시점이 테이블 생성보다 빨라서 발생한 문제라고 판단했다. 그래서 실행 시점을 애플리케이션이 완전히 뜬 이후로 늦추기 위해 ApplicationReadyEvent를 사용하도록 변경했다.

하지만 실행 시점을 늦춘 뒤에도 동일한 오류가 발생했다. 이를 통해 단순한 실행 순서 문제가 아니라는 것을 확인했다.

 

2단계 - 테이블 생성 로그 확인

로그를 다시 확인해보니 create table monthly_goals 로그는 출력되고 있었다. 즉, Hibernate가 테이블 생성을 시도하긴 했지만 실제로는 생성에 실패한 상황이었다.

 

3단계 - DDL 실행 WARN 로그 확인

테이블 생성 로그 위쪽을 확인하자 DDL 실행 중 경고 로그가 출력되어 있었다.

GenerationTarget encountered exception accepting command : Error executing DDL "create table monthly_goals (...month integer not null...)"

[*]month integer not null

원인은 month, year가 H2 예약어였기 때문이다. H2에서는 예약어를 컬럼명으로 그대로 사용할 수 없어 monthly_goals 테이블 생성이 실패했다.

결국 테이블이 생성되지 않은 상태에서 InitData가 insert를 시도했고, 그 결과 Table "MONTHLY_GOALS" not found 오류가 발생했다.

초기 MonthlyGoal 엔티티 코드다. year, month 필드가 별도 컬럼명 지정 없이 사용되어 H2 예약어와 충돌했다.

AnnualGoal 엔티티의 year 컬럼도 같은 이유로 테이블 생성에 실패했다.

초기 AnnualGoal 엔티티 코드다. year 필드가 그대로 DB 컬럼명으로 매핑되면서 H2 예약어와 충돌했다.

4. 해결

해결 방법은 엔티티 필드명은 그대로 유지하되, 실제 DB 컬럼명만 H2 예약어가 아닌 이름으로 변경하는 것이었다.

이를 위해 @Column(name = ...)을 사용해 year는 goal_year로, month는 goal_month로 매핑했다.

MonthlyGoal 엔티티에서 @Column(name = "goal_year"), @Column(name = "goal_month")로 DB 컬럼명을 변경한 코드다.

AnnualGoal 엔티티에서 year 필드를 goal_year 컬럼으로 매핑하도록 수정한 코드다.

필드명은 기존처럼 year, month를 유지했기 때문에 Java 코드의 의미는 그대로 가져갈 수 있었다. 대신 DB 컬럼명만 goal_year, goal_month로 변경해 H2 예약어 충돌을 피했다.

5. 참고

• H2에서는 year, month, day, value, key 등이 예약어에 해당할 수 있다.
• MySQL에서는 정상 동작하더라도 H2에서는 예약어 컬럼명 때문에 테이블 생성이 실패할 수 있다.
• MODE=MySQL 설정을 사용하더라도 예약어 충돌 문제가 항상 해결되는 것은 아니다.
• 로컬 테스트용 H2를 사용할 때는 엔티티 필드명이 DB 예약어와 겹치지 않는지 확인하는 것이 좋다.

6. 배운 점

H2를 로컬 환경에서 사용할 때는 컬럼명이 H2 예약어와 겹치지 않는지 확인해야 한다. 특히 year, month처럼 도메인에서 자연스럽게 사용할 수 있는 이름도 DB 입장에서는 예약어일 수 있다.

 

또한 Hibernate의 테이블 생성 실패가 항상 애플리케이션 시작 단계에서 명확한 오류로 드러나는 것은 아니다. 테이블 생성 실패가 WARN 레벨로만 찍히고 애플리케이션이 계속 실행될 수 있기 때문에, 실제 insert 시점에서야 Table not found 오류로 발견될 수 있다.

정리하면, Table not found 오류가 발생했을 때는 insert 실행 시점만 볼 것이 아니라, 그보다 앞선 DDL 생성 로그에서 테이블 생성 실패가 있었는지도 함께 확인해야 한다.