웹 기반의 DB 형상 관리 시스템 구축기(feat. Flyway)

프로젝트 배경

현재 내가 속한 팀은 여러 개의 스쿼드로 나뉘어 운영되고 있다. 스쿼드의 개수가 꽤나 많은데 이 중 4개 이상의 스쿼드가 동일한 공통 데이터베이스를 공유해서 사용하고 있다. 그리고 배포환경도 일반적인 회사들과 비슷하게 여러 환경으로 나누어져 있다.

데이터베이스 쿼리는 아래와 같이 Git을 통해 형상관리되고 있는데, 각 스쿼드는 스프린트 단위로 개발을 진행하면서 필요한 SQL 파일을 생성하고 이를 프로젝트의 changelog 폴더에서 버전별로 관리한다. 그리고 상위 환경으로 배포할 때는 해당 버전에 포함된 쿼리들을 개발자가 수동으로 실행하여 반영하고 있다.

sql/
├── changelog/
│   ├── A/                         # A 스쿼드 
│   │   ├── v5.7.11.md
│   │   ├── v5.7.12.md
│   │   └── v5.9.0.md
│   │   ...
│   ├── B/                         # B 스쿼드
│   │   ├── v6.4.0_B.sql
│   │   └── v6.4.0_B_dml.sql
│   │   ...
│   ├── C/                         # C 스쿼드
│   │   ├── v6.2.0_C_squard.sql
│   │   └── v6.2.0_dml_C_squard.sql
│   │   ...
│   └── D/                         # D 스쿼드
│       ├── v6.3.0_D_squard.md
│       └── v6.4.0_D_squard.md
│       ...
├── init.sql                         
└── schema.sql

 

 

기존 문제점

이런 배경에서 기존의 방식에서는 다음과 같은 문제들이 발생을 하고 있었다.

1. 배포 안정성 저하: 여러 스쿼드가 동일한 스프린트 기간에 개발을 진행하는 상황에서 각 스쿼드가 자신들의 쿼리만을 선택적으로 반영하는 경우가 많고, 이로 인해 필수 쿼리가 누락되어 오류가 빈번하게 발생한다.
2. 변경 이력 추적의 어려움: Git을 통해 누가 해당하는 쿼리를 누가 작성했는지 까지는 알 수 있지만, 실제로 쿼리가 반영된 시점이나 담당자를 추적하기 어렵다.
3. 환경별 데이터베이스 스키마 불일치: 쿼리 반영 과정에서 발생하는 누락으로 인해 환경별 데이터베이스의 테이블 구조가 일치하지 않는 것들이 매우 많다.

실제로 배포 안정성과 효율성을 저하시킬 뿐만 아니라, 개발자 간 소통 비용을 증가시키고 있었다.

이러한 문제를 해결하기 위해 형상 관리 도구 도입을 고려했고 Liquibase와 Flyway 중 고민을 하다가 학습 곡선이 낮고, SQL 기반으로 간단히 작성 가능하며 기존 방식과의 유사성이 높은 Flyway를 선택했다.

 

 

그러나 단순히 Flyway만 도입했을 시 문제점

하지만 Flyway 도입을 위해 여러 상황을 고려하며 도입 문서를 작성하는 과정에서 다음과 같은 문제들이 고려되었다.

1. installed_by가 항상 동일한 사용자로 표시

https://springframework.guru/database-migration-with-flyway/

Flyway는 기본적으로 flyway_schema_history라는 테이블을 생성하여 DB 형상을 관리한다. 그리고 이 테이블에는 installed_by 컬럼이 있어 누가 쿼리를 적용했는지 확인할 수 있다. 하지만 실제로 애플리케이션은 DB Connection을 동일한 계정으로 맺고 있고, Flyway도 편의상 동일한 계정을 사용할 것이기 때문에 Flyway를 통해 작업하면 installed_by가 항상 동일한 사용자로 기록되어 실제로 누가 해당 쿼리를 수행했는지 추적하기가 어렵다. SQL 파일을 작성하면 Git을 통해 변경 이력을 확인할 수는 있다지만, 현재도 SQL이나 MD 파일로 쿼리를 작성하면서 정렬 작업을 수행하지 않는 사람들이 종종 있어 이로 인해 누군가 정렬을 실행할 때마다 변경 이력이 기록되어 실제 작성자를 정확히 파악하기 어려운 상황이었다.

2. 비효율적인 반영 프로세스

Flyway는 기본적으로 src/main/resources/db/migration 폴더에 저장된 .sql 파일을 기준으로 작업을 수행한다. 그리고 파일명 규칙에 따라 작성된 쿼리 파일들은 애플리케이션 실행 시 자동으로 적용되며 실패 시 애플리케이션이 중지된다.

이런 동작 방식은 단순히 데이터베이스에 쿼리를 반영하려는 작업조차 매번 애플리케이션을 재배포해야 하는 번거로움이 발생한다. 특히 우리는 로컬 환경에서 개발용 데이터베이스에 직접 연결해 작업하는 경우가 많은데, 매번 애플리케이션을 실행해서 쿼리를 반영해야 한다면 개발 생산성이 저하될 가능성이 높았다.

물론.. 'Flyway는 CLI 도구도 제공해서 애플리케이션 재배포 없이도 마이그레이션을 수행할 수 있지만.. 과연 이게 더 편할까?'는 의문이다.

3. 엄격한 네이밍 규칙으로 인한 학습 필요

Flyway는 파일명을 기반으로 버전을 관리하기 때문에 다음과 같이 파일명을 엄격한 규칙에 따라 작성해야 한다. 

https://www.red-gate.com/blog/database-devops/flyway-naming-patterns-matter

그렇기에 팀 전체 개발자들이 이런 네이밍 규칙을 준수하기 위해 학습을 해야 하는 추가 비용이 발생한다. 참고로 Flyway로 함께 일하기, 버전 충돌 피하기 같은 아티클에서 언급된 사례들 역시 충분히 고려해야 하는 문제이기 때문에, 네이밍 규칙이 더욱 복잡해진다.

4. 마이그레이션 실패 시 복잡한 복구 절차

Flyway 마이그레이션이 실패했을 경우 복구 절차가 간단하지 않은데, repair 명령어를 사용하거나 flyway_schema_history 테이블에서 실패한 항목(success = FALSE)을 수동으로 제거한 뒤 다시 실행해야 한다. 그렇기에 이러한 절차 또한 학습이 필요해 팀원들에게 추가적인 시간 비용을 유발한다.

5. 사후 쿼리 관리의 이중성

배포 후 별도로 실행해야 하는 사후 쿼리는 Flyway로 관리되지 않기 때문에, 결국 사후 쿼리는 별도로 관리해야 하므로 이중적인 관리가 되어 관리포인트가 늘어난다.

별도로 afterMigrate로 마이그레이션이 전부 완료된 직후 자동으로 수행되게 할 수는 있지만 실행 시점을 임의로 지정할 수는 없기에 이런 기능은 고려하지 않았다.

6. 변경 이력의 파악 어려움

아까 1번에서 flyway_schema_history 테이블의 컬럼들 값을 봤듯이 script 컬럼의 경우 반영한 쿼리를 저장하는 것이 아닌 파일명을 저장한다. 그렇기에 각 환경에서 어떤 쿼리가 반영되었는지 확인하기 위해서는 반영된 SQL 파일을 직접 찾아서 열어봐야 하는 불편함이 존재한다.

 

 

이런 문제를 해결하기 위해 DB 형상 관리 웹 구축

결국 기존보다 더 편리하게 배포와 관리를 수행하고자 도입을 검토한 Flyway는 오히려 새로운 학습 비용과 엄격히 지켜야 할 규칙들이 추가됨으로써, 기존 방식보다 더 큰 불편을 초래할 가능성이 높았다. 그래서 이 문제를 해결하기 위해 많은 고민 끝에 Flyway의 강점은 유지하되 단점들을 보완할 수 있는 웹 기반의 관리 시스템을 구축하기로 결정했다. 지금부터는 편의성을 위해 DMM(Database Migration Manager)으로 부르겠다.

참고로 화면은 타임리프로 그렸는데 Cursor의 도움을 많이 받았다. 생전 처음 만들어보는 화면인데도 꽤나 퀄리티가 잘 나왔다.

1. 로그인 화면

• 환경 선택 지원: 접속할 데이터베이스 환경 선택
• ID/PW: 실제 DB 접근 시 사용하는 발급받은 본인의 계정 입력
• 스키마: 접속할 데이터베이스 스키마 이름 입력
• 로그인 정보 기억: 30일간 브라우저 새로고침 후에도 입력정보를 유지

여기서 로그인한 계정으로 다음과 같이 DB Connection을 맺어놓는다.

private final Map<String, DataSource> userDataSources = new ConcurrentHashMap<>();
private final Map<String, JdbcTemplate> userJdbcTemplates = new ConcurrentHashMap<>();

public boolean connection(String dbEnv, String dbId, String dbPassword, String schema) {
    // 환경에 맞는 JDBC URL 생성
    String jdbcUrl = buildJdbcUrl(dbEnv, schema);  
    // 사용자 고유 키 생성
    String userKey = generateUserKey(dbId, dbEnv, schema);  

    try {
        // 기존 연결이 있다면 정리
        cleanupExistingConnection(userKey);

        // 새로운 연결 생성
        DataSource newDataSource = createDataSource(jdbcUrl, dbId, dbPassword);
        JdbcTemplate newJdbcTemplate = new JdbcTemplate(newDataSource);

        try (Connection connection = newDataSource.getConnection()) {
            // 연결 성공 시 사용자별 정보 저장
            userDataSources.put(userKey, newDataSource);
            userJdbcTemplates.put(userKey, newJdbcTemplate);
            return true;
        }
    } catch (SQLException e) {
        throw new RuntimeException("데이터베이스 연결 실패: " + e.getMessage());
    }
}

그리고 별도의 DB가 아닌 로그인한 데이터베이스의 스키마에 있는 flyway_schema_history 테이블을 사용한다. DMM 프로젝트 말고는 Flyway를 전혀 의존하고 있지 않기 때문에 애플리케이션 실행 시 Flyway 관련 테이블이 자동으로 생성되지 않는다.

따라서 DMM에서는 로그인 시, 접속한 스키마에 flyway_schema_history 테이블이 존재하는지 확인하며, 해당 테이블이 없을 경우 자동으로 생성한 뒤 진입할 수 있도록 다음과 같이 안내 문구를 표시하도록 하여 새로운 스키마에서도 언제든지 사용할 수 있도록 했다.

 

2. 마이그레이션 이력 조회 및 관리

마이그레이션 이력 관리 화면

로그인하면 보이는 메인 페이지다. 특정 환경에서 쿼리를 반영하고, 반영 내역을 모니터링하는 데 유용하게 활용할 수 있다. 대충 현재 화면 하나만 봐도 어떤 기능을 하는지 파악할 수 있다.

실시간 마이그레이션 이력 조회

• 리스트에서 원하는 행(row)을 클릭하거나 키보드 화살표를 사용해 필요한 데이터를 빠르게 확인할 수 있다.
• 선택한 행에 반영된 SQL이 하단에 자동으로 표시된다.
• 페이지네이션, 정렬, 검색 기능을 통해 이력을 효율적으로 조회할 수 있다.

우측 상단의 + Migration 관리 버튼

• 신규 Migration 등록
• 환경 간 Migration 비교
• 스키마 비교

우측 상단의 + Migration 관리 버튼에서 제공해 주는 기능들에 대해서 알아보겠다.

 

3. 신규 Migration(쿼리) 등록

DB 쿼리를 반영할 수 있다. 참고로 기존에는 각자 DBMS를 사용해서 쿼리를 반영했지만 DMM이 도입되고난 이후부터는 모든 조회 쿼리를 제외한 모든 DML 및 DDL 쿼리반영은 여기서 반영을 하도록 팀 내 쿼리 반영 프로세스를 변경했다.

SQL 파일 업로드 또는 직접 입력 방식을 모두 지원하며, 입력된 SQL은 파일로 생성된 후 S3 저장소에 업로드된다. 그리고 이후 Flyway를 통해 데이터베이스에 반영된다.(참고로 Flyway의 S3 지원은 Flyway v7.0부터 제공된다.)

만약 Flyway만 단순히 도입하여 사용했다면 프로젝트마다 Flyway 의존성을 추가하고 src/main/resources/db/migration 경로에 SQL 파일을 작성하는 방식으로 진행되었을 것이다. 그러나 DMM 덕분에 각 프로젝트에서는 Flyway에 대해 전혀 알 필요가 없게 되었다.

각 프로젝트에서는 Flyway를 전혀 의존하지 않아도 됨.

그리고 Flyway는 사용자가 로그인한 정보에 따라 수행되어야 하기 때문에 쿼리 반영 시마다 매번 새로운 Flyway 인스턴스를 생성하고 실행한다.

/**
 * Flyway를 사용하여 마이그레이션을 실행
 * 주의: 사용자가 로그인한 DB 정보로 마이그레이션이 실행됨
 */
private void executeMigration(JdbcTemplate jdbcTemplate, String env, String dbId) {
    Flyway flyway = createFlywayInstance(jdbcTemplate, env, dbId);
    try {
        flyway.migrate();
        logger.info("Migration applied successfully");
    } catch (Exception e) {
        logger.error("Migration failed", e);
        throw e;
    }
}

/**
 * Flyway 인스턴스를 생성하고 설정
 */
private Flyway createFlywayInstance(JdbcTemplate jdbcTemplate, String env, String dbId) {
    String schema = getSchemaFromSession();
    
    /**
     * S3 URL 형식: s3:<bucket>(/optionalfolder/subfolder)
     * https://documentation.red-gate.com/fd/locations-224919725.html
     */
    String s3Location = String.format("s3:%s/%s/%s",
                                      getBucketName(env),
                                      MIGRATION_BASE_PATH,
                                      schema);

    return Flyway.configure()
                 .dataSource(jdbcTemplate.getDataSource())
                 .installedBy(dbId)
                 .locations(s3Location)
                 .baselineOnMigrate(true)
                 .outOfOrder(true)
                 .schemas(schema)
                 .load();
}

스크립트의 버전은 타임스탬프 형식으로 자동 생성되며, 수정이 불가능하도록 하여 버전 충돌을 방지했다. 타임스탬프 기반으로 자동으로 버전이 생성되기 때문에 개발자가 직접 버전을 신경 쓰지 않아도 되도록 하였다. 그리고 버전명 뒤에 붙을 네이밍에는 '스쿼드명'과 '스프린트 버전'을 기입하도록 하여 후에 조회 화면에서 필터링을 통해 쉽게 검색할 수 있도록 유도했다.

쿼리 반영 성공

쿼리 반영이 성공적으로 이루어지면, 리스트에 방금 추가한 항목이 반영된다.

쿼리 반영 성공 화면

쿼리 반영 실패

쿼리 반영 실패 화면

쿼리 반영에 실패하면, 실패 원인에 대한 알림과 함께 해당 상태가 실패로 기록된다. 실패한 기록을 삭제하지 않으면 Flyway의 특성상 이후 모든 SQL 반영 시도가 실패하게 된다. 실패한 기록은 휴지통 아이콘을 클릭하여 손쉽게 삭제할 수 있다.

Flyway만 사용했다면, flyway_schema_history 테이블에 기록된 실패 상태를 수동으로 삭제하고, SQL을 수정한 후 재배포해야 했을 것이지만 클릭 한 번으로 실패 기록을 삭제할 수 있어, 복잡한 과정을 간소화하고 개발자 편의성을 크게 향상시켰다.

누군가 반영 중일 경우

Flyway 작업이 진행 중일 때 다른 작업이 동시에 반영되면 파일 생성 순서와 반영에 문제가 발생할 수 있다. 따라서 작업 전후에 락을 걸어 모든 작업이 완료된 후에 동작하도록 구현하였다.(참고로 이를 위해 1번에서 로그인 시에 flyway_schema_history 말고도 lock 관련 테이블을 하나 더 생성한다.)

 

4. 환경 간 Migration 비교 및 적용

사실상 DMM을 하게 된 이유이자 핵심 기능이다. 특정 환경에서 개발이 완료된 후, 다른 환경으로 배포할 때 유용하게 활용할 수 있다. 예를 들어 현재 DEV 환경에는 개발자가 작성한 쿼리가 반영되어 있지만, QA 환경에는 반영되지 않은 경우 누락된 쿼리를 빠르게 확인하고 일괄적으로 적용할 수 있다.

누락된 Migration 확인

여러 배포 환경과 비교했을 때 현재 환경에서 반영되지 않은 쿼리들을 한눈에 확인할 수 있다. 각 환경별 DB의 flyway_schema_history를 비교해 버전이 일치하지 않은 것들을 보여준다. 

누락된 Migration 일괄 적용

확인된 누락된 쿼리들은 선택 후 한 번에 해당 환경으로 마이그레이션을 진행할 수 있다. 참고로 선택한 누락된 쿼리는 선택 순서와 관계없이 버전 순서대로 자동 적용되므로, 적용 순서로 인해 발생하던 문제를 초기에 방지하고 개발 편의성을 크게 향상시켰다.

가장 큰 도움이 되는 기능으로, 개발 특성상 DEV 환경에서 꼭 우선적으로 쿼리 반영이 일어나야 한다거나 하지는 않는다. QA 환경에 배포된 이후 bugfix 과정에서 QA 환경에만 쿼리를 반영하고 다른 여러 스테이징 또는 개발 환경에는 반영하지 않거나, 반대로 개발 환경에만 반영하는 경우도 많았다. 그리고 당장에 에러가 발생하지 않으면 해당 쿼리 반영이 누락되었음을 끝까지 눈치채지 못하는 일이 흔했다. 하지만 이 기능을 통해 누락된 쿼리들을 손쉽게 찾고 반영할 수 있게 되었다.

 

5. 스키마 비교

환경별 스키마 테이블 구조의 차이를 한눈에 확인할 수 있는 기능이다. 기존에 환경별로 누락된 쿼리가 많아 정합성을 맞추는 데 도움을 주기 위해 만들었으며, 이후에도 주기적으로 확인하면서 스키마의 정합성을 유지하는 데 유용하게 활용할 수 있을 것이라 생각되어 만들었다.

스키마 비교 요약

추가된 테이블 식별

삭제된 테이블 식별

위와 같이 편하게 확인할 수 있다. 

변경된 테이블 식별

그리고 변경된 테이블에 대해서는 서로 일치시키기 위한 DDL을 자동으로 생성하여 정합성을 맞추는 데 도움을 주고자 하였다.

 

 

결론 

프로젝트 도입 이후 조회 쿼리를 제외한 모든 DML 및 DDL 작업은 DMM을 통해 반영하도록 DB 반영 프로세스를 새롭게 수립하였다. 그리고 실제로 스프린트를 한 사이클 돌려본 결과 큰 문제없이 안정적으로 프로세스가 정립되었다. DMM 덕분에 기존에는 각자가 DBMS를 통해 쿼리를 개별적으로 반영하면서, 해당 환경에 쿼리가 제대로 반영되었는지 확인하기가 어려웠지만 이제는 한눈에 반영 상태를 파악할 수 있게 되었고, 환경 간 누락된 쿼리를 손쉽게 확인할 수 있게 되었다. 

그리고 누락된 마이그레이션으로 인해 책임 소재를 따지기 위한 불필요한 소통도 줄었다. 기존에는 쿼리가 누락되었을 가능성이 있더라도 "이거 반영된 걸까?", "반영해도 될까?", "괜히 했다가 문제가 생기면 내가 책임져야 할 것 같은데, 다른 사람이 해주겠지"와 같은 생각 때문에 선뜻 반영하지 못하는 경우가 많았지만 이제는 누락된 쿼리를 명확히 인지할 수 있어 확인한 사람이 바로 반영만 하면 되게 되었다.

프로젝트를 진행하면서 항상 머릿속에 가지고 있었던 생각은 '새로운 프로세스를 정립하는 것이 기존보다 더 복잡하거나 어렵지 않아야 한다.'였다. 그렇기에 단순히 Flyway를 도입하는 데 그치지 않고, 팀원들이 별도로 Flyway 규칙을 학습하지 않아도 되는 시스템을 설계하고자 했다. 그리고 기획부터 디자인(?), 프론트엔드, 백엔드까지 전반적으로 혼자 진행해 보았는데 만족스러운 성과가 나온 것 같다.