Spring Boot과 Liquibase로 스키마 버전 관리

개요

애플리케이션이 성장하면 데이터베이스 스키마 변경 관리가 중요한 과제가 된다. Liquibase는 변경 이력을 추적하고 조건에 따라 자동 적용하는 도구다. Spring Boot와 결합하면 배포 파이프라인에서 데이터베이스 상태를 일관되게 유지할 수 있다. 이 글에서는 spring boot liquibase 예제와 함께 설정부터 changelog 작성, 롤백과 테스트 전략까지 단계별로 설명한다.

왜 Liquibase를 사용하는가

기본적인 이유는 세 가지다. 첫째, 변경 이력 추적이다. 둘째, 개발·테스트·운영 환경 간 일관성이다. 셋째, 롤백과 같은 안전성 기능이다. 특별한 스크립트 없이도 데이터베이스 상태를 재현할 수 있어 협업과 배포 안정성이 높아진다.

환경 설정

의존성 추가 (Maven)

Spring Boot 프로젝트에 Liquibase 의존성을 추가한다. 아래는 pom.xml에 넣을 최소 설정 예시다.

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

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

application.properties 예시

Spring Boot 설정 파일에서 Liquibase 동작을 조정할 수 있다. 다음은 기본적인 설정 예시다.

spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
spring.datasource.username=myuser
spring.datasource.password=mypassword
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml
spring.liquibase.contexts=development,test,production
spring.liquibase.enabled=true

Changelog 작성

Liquibase는 여러 포맷(XML, YAML, JSON, SQL)을 지원한다. 여기서는 XML 기반의 database changelog spring boot 예제를 소개한다. 마스터 changelog에서 개별 changeSet 파일을 포함하는 방식이 일반적이다.

마스터 changelog 예제

<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'>

  <include file='db/changelog/changes/001-create-user-table.xml'/>
  <include file='db/changelog/changes/002-add-email-index.xml'/>

</databaseChangeLog>

개별 changeSet 예제

<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'>

  <changeSet id='001-create-user-table' author='dev'>
    <createTable tableName='users'>
      <column name='id' type='BIGINT'>
        <constraints primaryKey='true' nullable='false'/>
      </column>
      <column name='username' type='VARCHAR(100)'></column>
      <column name='created_at' type='TIMESTAMP'></column>
    </createTable>
  </changeSet>

</databaseChangeLog>

Spring Boot와의 통합 동작

애플리케이션을 시작하면 Spring Boot가 자동으로 Liquibase를 호출한다. 스프링 프로퍼티에서 change-log 경로를 지정하면 해당 파일을 읽고 적용한다. 이미 적용된 changeSet은 DATABASECHANGELOG 테이블을 보고 건너뛴다. 따라서 id와 author 조합은 유일하게 관리되어야 한다.

롤백과 마이그레이션 전략

Liquibase는 rollback 태그를 통해 되돌리기를 지원한다. 그러나 복잡한 데이터 변환은 수동 검토가 필요하다. 권장하는 전략은 다음과 같다.

• 작은 단위의 changeSet을 작성해 영향 범위를 최소화한다.
• 데이터 변경이 포함될 경우 백업 또는 별도 스크립트를 준비한다.
• 롤백 절차는 테스트 환경에서 검증한다.

간단한 rollback 예

<changeSet id='003-add-column' author='dev'>
  <addColumn tableName='users'>
    <column name='bio' type='TEXT'/>
  </addColumn>
  <rollback>
    <dropColumn columnName='bio' tableName='users'/>
  </rollback>
</changeSet>

테스트와 CI 통합

CI 파이프라인에서 liquibase spring boot 설정을 활용하면 배포 전 DB 일관성을 보장할 수 있다. 테스트 환경에서 매 빌드마다 마이그레이션을 적용해 문제를 조기에 발견한다. 또한 컨텍스트나 프로파일을 이용해 환경별 설정을 분리한다.

실무 팁과 주의사항

• changeSet id는 의미 있게 작성하고 중복을 피한다.
• 복합 변경은 순서를 명확히 하여 마이그레이션 오류를 방지한다.
• 운영 데이터베이스에서는 대량 DDL 변경 시 잠금과 성능 영향을 고려한다.
• 버전 관리 시스템에 changelog 파일을 함께 커밋해 협업 이력을 남긴다.
• spring boot liquibase 예제 코드를 그대로 운영에 사용하기보다 검토 후 적용한다.

문제 해결 사례

자주 발생하는 문제는 changeSet 충돌과 권한 부족이다. 같은 id로 다른 changeSet이 커밋되면 충돌이 발생한다. 또한 애플리케이션이 데이터베이스에 변경 권한이 없으면 마이그레이션이 실패한다. 이런 경우 로그를 확인하고 DATABASECHANGELOG 테이블과 파일 내용을 비교해 원인을 파악한다.

정리

Liquibase는 Spring Boot와 함께 사용할 때 데이터베이스 스키마를 일관되게 관리하는 강력한 도구다. database changelog spring boot 예제를 통해 초기 구성을 이해하고, changeSet 작성 원칙과 롤백 전략을 준수하면 운영 안정성이 향상된다. 처음 접하는 경우에는 테스트 환경에서 충분히 검증한 뒤 프로덕션에 적용하는 방식이 안전하다.