Spring Boot 3 + JPA를 활용한 Liquibase 실습하기 (1)

📖 실습 내용

 

1. Spring Boot 3 + Spring Data JPA 환경에서 Liquibase 환경을 설정한다.

2. Entity 파일을 생성한 뒤, 로컬 DB와 스키마 차이에 대한 ChangeLog 파일을 생성한다. (diff)

3. Liquibase를 통해 ChangeLog 파일을 기반으로 데이터베이스에 적용하고 로그를 확인한다.

4. profile 설정을 통해 개발 환경별로 적용한다.

 

📖 실습 1. Liquibase 환경 설정하기

기본 실습 환경은 다음과 같다.

 

1. Spring Boot 3.0.6

2. Maven 3.8.4

3. Java 17

4. MariaDB 10.6

1. Liquibase Dependency 추가

Liquibase를 사용하기 위해서 liquibase-core 의존성을 추가한다.

스프링에서 기본적으로 liquibase 버전 관리를 해주므로 <version>을 직접 입력할 필요는 없다.

특정 버전 관리가 필요하다면 따로 버전을 입력해도 상관없다.

 

<dependency>
	<groupId>org.liquibase</groupId>
	<artifactId>liquibase-core</artifactId>
</dependency>

2. Maven Plugin 추가

liquibase-maven-plugin도 스프링에서 버전 관리를 해주기 때문에 <version>을 입력할 필요는 없다.

 

<plugin>
	<groupId>org.liquibase</groupId>
	<artifactId>liquibase-maven-plugin</artifactId>
	<configuration>
		<diffChangeLogFile>src/main/resources/db/changelog/diff/${maven.build.timestamp}_changelog.xml</diffChangeLogFile>
		<verbose>true</verbose>
		<logging>info</logging>
		<propertyFile>src/main/resources/liquibase.properties</propertyFile>
	</configuration>
	<dependencies>
		<dependency>
			<groupId>org.liquibase.ext</groupId>
			<artifactId>liquibase-hibernate6</artifactId>
			<version>4.20.0</version>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
			<version>3.0.6</version>
		</dependency>
	</dependencies>
</plugin>

 

<configuration>에서 liquibase 데이터베이스 환경 및 대상 데이터베이스 환경을 설정한다.

 

<propertyFile>는 별도의 설정파일 경로를 설정하는 것이다.

 

설정 파일에 데이터베이스와 대상 데이터베이스 정보를 입력한다.

참고로, 꼭 설정 파일을 사용할 필요는 없다. 옵션을 직접 입력하는 것도 가능하다. 예시처럼 일부 옵션만 사용해도 된다.

 

<diffChangeLogFile>은 데이터베이스와 엔티티를 비교한 결과물을 어디에다 저장할지 설정하는 것이다.

 

경로 중에 ${maven.build.timestamp}는 diff 파일을 생성하는 시간으로 이름을 설정하겠다는 의미이다.

 

동일한 이름을 사용할 경우, diff를 여러 번 하는 경우 동일한 내용이 같은 파일에 계속해서 추가될 수 있음을 주의하자.

 

예를 들어, diff 명령을 통해 테이블 2개를 생성하는 changeLog 파일을 생성했을 때, update를 하지 않고 다시 diff 명령을 수행하는 경우 테이블 2개를 생성하라는 내용이 같은 파일에 반복해서 들어간다는 의미이다.

 

<dependencies>에는 데이터베이스 환경에 대한 의존성을 추가한다.

 

기존 개발 환경이 있는데 'DB to DB'가 아닌 예시처럼 'DB to Entity'에 liquibase를 사용하려는 경우에는 Entity 파일에서 사용 중인 외부 의존성을 모두 추가해야 한다는 점을 주의하자.

 

예를 들어, Entity 파일에 @NotNull 등을 사용한다면, 관련 의존성인 javax-validation을 추가해야 한다는 의미이다.

 

'DB to Entity'를 테스트 하는 경우는 반드시 liquibase-hibernate를 추가한다.

(만약, 'DB to DB'로 사용하는 경우에는 해당 의존성은 필요 없다.)

 

참고로, 무조건 liquibase-hibernate6을 사용해서는 안된다.

 

최신 JPA 버전에서는 Hibernate 6을 사용하고 있기 때문에, 버전에 맞게 사용하는 것이다.

만약 환경이 Hibernate 5라면 그에 맞춰서 liquibase-hibernate5로 사용해야 한다.

3. liquibase.properties 파일 설정하기

해당 설정은 MariaDB 환경에 맞게 설정되었다.

다른 DB를 사용하는 경우에는 url, username, password, driver, referenceUrl 중 dialect 부분을 알맞게 설정하면 된다.

 

changeLogFile=src/main/resources/db/changelog/db.changelog-master.xml
url=jdbc:mariadb://{db ip}:{db port}/{database name}
username={db username}
password={db password}
driver=org.mariadb.jdbc.Driver
referenceUrl=hibernate:spring:com.shibaholic.blogliquibase.model?dialect=org.hibernate.dialect.MariaDBDialect

 

changeLogFile은 db.changelog-master.xml 파일이 어디 있는지 경로를 확인하는 것이다.

 

referenceUrl에서 hibernate:spring: 뒤 com.shibaholic.blogliquibase.model 은 엔티티 패키지 경로이다.

본인 프로젝트에 설정한 엔티티 패키지 경로를 입력하면 된다.

4. db.changelog-master.xml  파일 생성하기

 

<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd" >

    <includeAll path="/db/changelog/diff/"></includeAll>

</databaseChangeLog>

 

db.changelog-master.xml 파일에서 데이터베이스로 마이그레이션 할 대상 파일들의 경로를 설정한다.

<includeAll>로 특정 디렉터리를 설정하여 해당 파일에 있는 xml 파일 전체를 마이그레이션 할 수도 있고,

<include>로 파일 개별 설정도 가능하다.

5. application.properties 파일 설정하기

application properties에서는 db.change-master.xml 파일 경로만 설정해주면 된다.

 

spring.liquibase.enabled=true
spring.liquibase.change-log=classpath:/db/changelog/db.changelog-master.xml

 

이것으로 기본적인 Liquid 설정이 끝이 났다.

 

2편에서 Entity 파일을 생성한 뒤, 로컬 DB와 스키마 차이에 대한 ChangeLog 파일을 생성하고 diff하는 방법에 대해 공유하겠다.

REFERENCE

https://docs.liquibase.com/concepts/connections/creating-config-properties.html

Create and Configure a liquibase.properties File

https://www.baeldung.com/liquibase-refactor-schema-of-java-app

https://stackoverflow.com/questions/75093751/liquibase-generate-diff-with-springboot-3

Liquibase generate diff with Springboot 3

https://docs.liquibase.com/change-types/includeall.html

includeAll