Spring Boot에서 Liquibase – 개발자 가이드

Source: Dev.to

Liquibase가 무엇이며 왜 중요한가

Liquibase는 본질적으로 데이터베이스 스키마를 위한 Git과 같습니다. SQL 스크립트를 수동으로 실행하고 모두가 올바르게 실행하기를 기대하는 대신, 구조화된 형식으로 변경 사항을 정의하고 Liquibase가 적용된 내용을 추적합니다.

예시 XML Changeset

Liquibase는 DATABASECHANGELOG 라는 테이블에 적용된 마이그레이션을 기록하여 다음을 보장합니다:

• 변경 사항은 한 번만 적용됩니다
• 적용 순서가 유지됩니다
• 롤백이 가능합니다

주요 장점

• 일관된 환경 – 개발, 스테이징, 프로덕션이 동기화된 상태를 유지
• 마이그레이션 히스토리 – 누가 언제 무엇을 변경했는지 확인 가능
• 자동 마이그레이션 – Spring Boot가 시작 시 실행
• 롤백 – 필요 시 안전하게 변경 사항을 되돌릴 수 있음

Spring Boot에서 Liquibase 설정하기

Maven 의존성

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

Gradle 의존성

implementation 'org.liquibase:liquibase-core'

Spring Boot는 Liquibase를 자동으로 감지하고 마이그레이션을 실행합니다.

설정 (application.yml)

spring:
  liquibase:
    change-log: "classpath:/db/changelog/changelog.xml"
    contexts: "dev"

일반적인 프로젝트 구조

src/main/resources
 └─ db
    └─ changelog
        └─ changelog.xml

마이그레이션 작성하기

전체 XML Changelog 예시 (changelog.xml)

포맷된 SQL Changeset 예시

-- liquibase formatted sql
-- changeset dev:create-users
CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP
);

-- changeset dev:add-email-index
CREATE INDEX idx_users_email ON users(email);

-- changeset dev:add-phone-column
ALTER TABLE users ADD COLUMN phone_number VARCHAR(20);
-- rollback: ALTER TABLE users DROP COLUMN phone_number;

모범 사례

• 실행된 마이그레이션은 절대 수정하지 않기 – 마이그레이션은 불변이어야 합니다.
• 하나의 changeset = 하나의 변경 – 각 changeset은 하나의 테이블, 컬럼, 인덱스 등 하나의 작업에 집중시킵니다.
• 파일에 번호 매기기 – 여러 파일을 사용할 경우 Git 충돌을 방지하기 위해 번호를 붙입니다.
• 로컬에서 테스트 – DB를 삭제하고 애플리케이션을 실행해 처음부터 마이그레이션이 정상 동작하는지 확인합니다.
• 프로덕션에서는 신중히 – 대형 테이블에 대해 ALTER COLUMN TYPE, DROP COLUMN 또는 NOT NULL 제약을 추가하는 작업은 충분한 계획 없이 수행하지 마세요.

기능 비교

Flyway는 더 간단하지만, Liquibase는 엔터프라이즈 환경에 필요한 유연성을 제공합니다.

결론

Liquibase는 환경 간 데이터베이스 스키마를 일관되게 유지하는 데 큰 도움이 됩니다. 다음 골든 룰을 지키세요:

• 불변의 마이그레이션
• changeset당 하나의 변경
• 로컬에서 마이그레이션 테스트

읽어 주셔서 감사합니다!