스프링부트 3.x 버전 data.sql 삽입 오류 해결

최근 진행 중인 프로젝트에서 프론트엔드 측에서 백엔드 데이터 연동 테스트를 위한 테스트 계정 생성을 요청했다.

 

배포 후 직접 DB에 사용자를 추가하는 방법도 생각했지만, 매번 수동으로 데이터를 넣는 것은 비효율적이기 때문에, 서버 실행 시점에 테스트용 계정과 샘플 데이터도 자동으로 삽입해 두기로 했다. (샘플 데이터는 초기 데이터 연동 확인이 용이하게 하기위해 추가로 넣어두었다.)

 

데이터 삽입 방법

일단, 데이터를 넣는 방법에는 여러 가지가 있다.

• @PostConstruct를 사용해 Bean 초기화 이후 실행
• CommandLineRunner 또는 ApplicationRunner로 삽입
• data.sql을 활용한 자동 초기화

여러 방법을 비교하다가, 단순하게 SQL 스크립트로 초기 데이터를 넣는 data.sql 방식을 선택했다.

그러나 src/main/resources/data.sql 파일에 각 데이터를 작성해두고 실행했을 때, 제대로 들어가지 않았다.

로그를 확인해보니, data.sql이 Hibernate가 테이블을 생성하기 전에 너무 일찍 실행되어 테이블이 존재하지 않는 상태에서 실행된 문제였다. (이는 엔티티로 스키마를 생성하는 시점과 data.sql이 실행되는 시점이 분리되어 있기 때문이다.)

 

해결 방법

찾아낸 해결책은 import.sql을 사용하는 것이었다.

파일명을 data.sql -> import.sql로 변경하자 애플리케이션 실행 시점에 정상적으로 데이터가 삽입되었다.

 

근본적인 원인

해결 방안을 제시한 대부분의 글에서는 근본적인 원인에 대해 설명이 없어서, 직접 찾아보았다. 원인은 아래와 같다.

 

Spring Boot 2.5 버전 이후부터는 data.sql의 실행 시점이 변경되었다.

기존에는 Hibernate가 엔티티 기반으로 스키마를 생성한 이후에 data.sql이 실행되었지만,

2.5 버전부터는 그 이전 단계, 즉 데이터베이스 연결 직후에 실행되도록 변경되었다.

 

그 결과,

테이블이 아직 만들어지기 전이라면 data.sql이 실패하거나 무시되는 문제가 발생한다.

 

반면 import.sql은 Hibernate의 기능으로, spring.jpa.hibernate.ddl-auto=create 등의 설정이 있을 때

DDL(스키마 생성)이 완료된 직후 자동으로 실행된다. 그래서 import.sql은 문제없이 동작한 것이다.

 

참고: data.sql을 사용하고 싶다면?

아래 설정을 추가 (application.yml)

spring:
    jpa:
     defer-datasource-initialization: true

이 설정은 “Hibernate가 스키마를 모두 생성한 다음에 data.sql을 실행하라”는 의미이다.

이렇게 하면 data.sql도 정상적으로 작동한다.

 

data.sql / import.sql 작성 시 주의할 점

Spring Boot는 기본적으로 data.sql 또는 import.sql 파일을 SQL 문 단위로 세미콜론(;)을 기준으로 구분해서 실행한다.

따라서 SQL 문이 여러 줄에 걸쳐 있더라도, 한 문장은 반드시 세미콜론으로 끝나야 한다.

 

일부 환경에서는 줄바꿈이 들어가면 구문 파싱이 꼬여서 “Failed to execute SQL script statement #1” 같은 오류가 발생할 수 있다.

 

그래서 가장 안전한 방법은 한 문장을 한 줄에 작성하는 것

-- 안전한 방식
INSERT INTO term_categories (id, name, user_id) VALUES (1, 'Project Management', 1);
INSERT INTO term_categories (id, name, user_id) VALUES (2, 'KPI', 1);
INSERT INTO term_categories (id, name, user_id) VALUES (3, 'Roadmap', 1);
INSERT INTO term_categories (id, name, user_id) VALUES (4, 'Stakeholder', 1);
INSERT INTO term_categories (id, name, user_id) VALUES (5, 'Workflow', 1);

-- 비추천 (환경에 따라 실행 안 될 수 있음)
INSERT INTO term_categories
(id, name, user_id)
VALUES (1, 'Project Management', 1);

---

참고 문서

• Spring Boot Reference – Data Initialization
• Spring Boot 2.5 Release Notes