의존성 추가#

먼저 build.gradle에 Flyway 의존성을 추가했다

implementation 'org.flywaydb:flyway-core'
implementation 'org.flywaydb:flyway-mysql'

설정 추가#

spring.jpa.hibernate.ddl-auto=validate # create x

spring.flyway.enabled=true
spring.flyway.baseline-on-migrate=false
spring.flyway.locations=classpath:db/migration
spring.flyway.validate-on-migrate=true
spring.flyway.fail-on-missing-locations=true
spring.flyway.user=flyway_user
spring.flyway.password={flyway_user_password}

ddl-auto 옵션을 validate로 설정하여 DB 스키마와 JPA 엔티티 매핑이 일치하는지 검사만 한다 → 불일치 시 에러 발생

• enabled: Flyway 활성화
• baseline-on-migrate: 기존 데이터베이스에 마이그레이션 이력 테이블이 없을 때 자동으로 베이스라인 설정하는데 우리 서비스는 DB를 초기화하고 처음부터 flyway를 적용하였으므로 사용 x
• baseline-version: 베이스라인 버전
• locations: 마이그레이션 스크립트 위치

DB 계정 권한 분리#

기존에 테스트할 때는 root 계정을 애플리케이션 계정으로 사용하였지만 실제 운영 환경에서는 사용자에게 모든 권한을 부여해서는 안되고 데이터에 대한 CRUD(create, select, update, delete)만 부여해줘야 한다고 한다.

spring.datasource.username=user
spring.datasource.password={user_password}

따라서 애플리케이션에서 DB에 접근하는 계정을 root가 아닌 다음과 같이 DML 권한만 부여한 user 계정을 사용하였다.

반면 Flyway는 테이블을 생성해야하기 때문에 user보다 더 많은 권한이 필요하다. Flyway는 스키마 변경과 테이블 생성을 해야 하므로 DDL 권한을 추가하였다.

(IP접근 제한을 설정하여 내 컴퓨터에서만 DB를 접근할 수 있도록 보안을 강화할 수 있다고 하는데 추후에 적용해 봐야겠다.)

디렉토리 구조 생성#

src/main/resources/
  db/
    migration/
      V1__init.sql
      V2__Add_student_column_is_deleted.sql
      

설정에서 locations=classpath:db/migration으로 설정하였으므로 다음과 같은 db/migration 하위 파일에 sql 파일을 작성하면 된다.

스크립트 파일 작성 규칙#

flyway의 마이그레이션 스크립트 파일 이름 규칙이 있다.

V<버전번호>__<설명>.sql

숫자가 작은 버전의 마이그레이션부터 숫자가 큰 버전 순서대로 스크립트가 실행되고 1, 1.1, 2, 3 …처럼 순차적 증가도 가능하고 20250101, 20250203 … 처럼 날짜 형태로 사용해도 괜찮다.

• V : 현재 버전을 새로운 버전으로 업데이트
• U : 현재 버전을 이전 버전으로 되돌리는 경우
• R : 버전에 관계없이 매번 실행하는 경우

예시를 보면 다음과 같다

ex)
V1__init.sql
V2__Add_student_column_is_deleted.sql
...

_가 2개인 걸 꼭 주의하자 _로 작성 후 테스트하다 한참동안 에러를 못 찾았다..!

스크립트 작성#

먼저 Student 엔티티를 구성하자.

@Entity
public class Student{

    @Id
    @GeneratedValue(strategy = IDENTITY)
    private Long id;

    @Column(length = 11, nullable = false, unique = true)
    private String phoneNumber;

    @Column(length = 64, nullable = false)
    private String name;

    @Column(length = 64, nullable = false)
    private String country;

}

이 엔티티에 대한 테이블을 만들기 위해 스크립트를 작성하자. 실행하면 student 초기 테이블이 만들어진다.

V1__init.sql

CREATE TABLE `student`
(
    `id`                      BIGINT       NOT NULL AUTO_INCREMENT,
    `phone_number`            VARCHAR(11)  NOT NULL UNIQUE,
    `country`                 VARCHAR(64)  NOT NULL,
    `name`                    VARCHAR(64)  NOT NULL,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB;
...

이후 개발중 student 테이블에 deleted 필드를 추가할 일이 생겨 필드를 다음과 같이 수정하였다.

@Entity
public class Student{

    @Id
    @GeneratedValue(strategy = IDENTITY)
    private Long id;

    @Column(length = 11, nullable = false, unique = true)
    private String phoneNumber;

    @Column(length = 64, nullable = false)
    private String name;

    @Column(length = 64, nullable = false)
    private String country;

    @Column(name = "deleted", nullable = false)
    private Boolean isDeleted;
}

V1__init.sql에 이어 추가될 스키마에 대한 스크립트를 작성해줘야 한다. 파일 이름을 V2__Add_student_column_is_deleted.sql로 추가 내용과 관련지어 명명하고 스크립트를 다음과 같이 작성해주었다.

V2__Add_student_column_is_deleted.sql

ALTER TABLE student
    ADD COLUMN deleted BOOLEAN DEFAULT FALSE;

다음과 같이 deleted 필드가 잘 적용된 것을 확인할 수 있다.

또한 위에서 변경 사항을 git처럼 추적해준다고 하였는데 flyway가 자동으로 flyway_schema_history 테이블을 생성하고 관리한다.

flyway_schema_history 테이블을 보면 작성한 script에 대해 버전별로 관리되는 것을 볼 수 있다.

결과#

실제 운영 환경에서 DB 마이그레이션이 왜 필요한지 깨달았고 재배포 시에도 테스트하던 데이터를 유지하며 빠르게 할 수 있었다. 일일이 스크립트를 작성해야 한다는 번거로움은 있었지만 버전 관리를 효율적으로 할 수 있었다. 적용하면서 많은 시행착오가 있었는데 그중 가장 헤맸던 명명 규칙을 꼭.. 주의하자..!

참고 자료#

• https://www.code4copy.com/java/spring-boot-flyway-db-migration-integration-example/
• https://da-nyee.github.io/posts/tecoble-flyway/
• https://engineerinsight.tistory.com/206