[Liquibase] DDL 형상관리 툴

onlydev7777·2025년 8월 6일

1. DDL 형상관리의 필요성

하나의 공통 원소스 프로젝트를 여러 고객사의 On-Premise 인프라에 납품하여 운영되는 구조일 때 DDL 형상관리는 필수적이다.

이전 레거시 프로젝트에서는 DDL 형상관리가 되지 않아서 A사 요건으로 추가 된 DDL이 B사에 적용되지 않고 동일한 소스코드가 올라갔을 경우 Missing Column SQL 오류가 발생하는 이슈상황이 너무 빈번했다.

금번 차세대 프로젝트 에서는 On-Premise 상품 운영 시 이러한 이슈상황을 해소하고자 DDL 형상관리를 하게 되었다.

2. Flyway vs Liquibase

대표적인 DDL 형상관리 툴 2가지 이다.

1) Flyway

SQL 방식으로 순차적 형상관리
DB 벤더 별 분기 처리 불가
롤백 기능 미제공
DB서버 간 스키마 비교 기능 없음
Hibernate Entity 기반 DDL 자동화 기능 없음

2) Liquibase

XML, YAML, JSON 과 같이 추상화 된 형상관리 모델 제공
ex) changelog.xml 파일을 작성하면 Liquibase가 DB벤더사에 맞는 SQL로 번역해서 DDL이 실행된다.
DB벤더별 분기 처리 가능

롤백 기능 제공

<changeSet id="1" author="liquibaseuser">
    <createTable tableName="testTable">
        <column name="id" type="int"/>
    </createTable>
    <rollback>
        <dropTable tableName="testTable"/>
    </rollback>
</changeSet>

DB서버 간 스키마 비교 기능

liquibase diff-changelog --changelog-file=example-changelog.xml 
--url="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
--username=<USERNAME>
--password=<PASSWORD>
--reference-url="jdbc:oracle:thin:@<IP OR HOSTNAME>:<PORT>:<SERVICE NAME OR SID>"
--reference-username=<USERNAME>
--reference-password=<PASSWORD>

Hibernate Entity 기반 changelog.xml 파일 자동화 기능 제공

선택

아래와 같은 사유로 Liquibase 를 선택하였다.

Flyway 는 sql 문으로 작성하기 때문에 DB벤더사 마다 개발자가 일일이 DDL 쿼리를 작성 해야 하는 단점이 있다.

Liquibase 는 xml 구조로 작성 가능하며 DDL 반영 시 Liquibase 가 xml 파일을 읽고 각 DB벤더사에 맞는 sql로 번역해주기 때문에 개발자가 일일이 DB벤더사 별로 sql을 작성할 필요가 없다.

On-Premise 사업에 있어서 Flyway의 DB벤더사에 의존해야 한다는 큰 단점으로 인해 금번 차세대 DB형상관리 기술은 Liquibase 로 선택 되었다.

3. Liquibase 운영 방식

개발자는 DDL의 대부분을 직접 작성할 필요가 없다.

Liquibase는 Hibernate Entity와 DB 스키마의 차이를 자동으로 xml 파일로 생성해준다.
이 때 jpa의 ddl-auto의 update 속성과는 다르게 DROP 관련 DDL도 포함되므로 개발자의 각별한 주의가 필요하다.

DROP 관련 DDL은 서비스 운영 시 위험요소로 판단 되기 때문에 자동 생성 대상에서 제외하고 별도 파일에 생성 되도록 커스텀 해놓았다.

앞서 "개발자는 DDL의 대부분을 직접 작성할 필요가 없다" 고 했는데 개발자가 직접 DDL을 작성해야 하는 경우는 어떤 경우일까?

대표적으로 RENAME 태그는 개발자의 교차검증이 필요하다.

Entity 필드에 이전 컬럼(Old Column) 에 대한 속성이 존재하지 않기 때문에 Liquibase는 컬럼명이 변경되면 DROP / ADD 태그로 DDL이 변환된다.

이 때 개발자가 의도한 RENAME DDL을 반영하기 위해서는 ADD 태그를 RENAME 태그로 직접 변환하는 작업을 수행해야 한다.

또는 진짜 DROP을 의미한 Entity의 변경이 있다면 DROP 관련 커스텀 파일에서 해당 DROP 태그를 changelog.xml 파일에 직접 적용해야 한다.

결론적으로 자동생성 된 DDL이라 할지라도 개발자의 교차검증은 반드시 필요하다.

4. Liquibase 모듈

Liquibase 모듈은 개발자의 행위를 2가지로 정의한다.

1) diff DDL 파일 생성

generateDiffChangeLog
개발자 로컬DB와 domain 모듈의 Hibernate Entity 코드를 비교해서 changelog.xml 파일을 생성한다.

2) 생성된 changelog.xml 파일 반영

LiquibaseApplication 실행 >> ApplicationRunner Register Bean

실행주체가 Docker인지 Local인지 검증 한 후 Local 이면 Merge 를 위한 ChangeSet 확인 과정을 추가한다.
liquibase 스키마의 databasechangelog 테이블의 id 컬럼과 changelog.xml 파일의 changeSet 태그의 id 값을 비교해서 DB에 없는 changeSet 태그를 반영한다.