Flyway 실전 도입기 2편: pg_dump로 순수 스키마 SQL 추출하기

전체 작업의 순서는 다음과 같습니다.

1. 로컬 DB 초기화 및 V1 스키마 생성하기
2. pg_dump로 순수 스키마 SQL 추출하기 ← 오늘 다룰 내용
3. 하이버네이트가 만든 스키마의 5가지 문제점과 V1 스크립트 완벽 정제
4. Spring Boot 연동부터 마이그레이션 검증까지 완벽 가이드

1. 서론: 만들어진 스키마를 어떻게 꺼낼까?

지난 1편 포스팅인 'Flyway 실전 도입기 1편: 로컬 DB 초기화 및 V1 스키마 생성하기'에서는 도커로 띄운 빈 PostgreSQL 데이터베이스에 스프링 부트의 ddl-auto: update 기능을 활용하여 23개의 초기 테이블을 생성해 보았습니다.

2026.05.20 - [기술 스택] - Flyway 실전 도입기 1편: 로컬 DB 초기화 및 V1 스키마 생성하기

Flyway 실전 도입기 1편: 로컬 DB 초기화 및 V1 스키마 생성하기

데이터베이스 안에 우리가 원하는 형태의 베이스 스키마가 성공적으로 만들어졌습니다. 이제 남은 과제는 이 스키마 구조를 파일 형태로 예쁘게 빼내는 것입니다. 이 파일을 기반으로 Flyway의 첫 번째 마이그레이션 스크립트인 V1__init.sql을 만들 예정이니까요.

오늘은 PostgreSQL에서 기본으로 제공하는 강력한 백업 도구인 pg_dump를 사용하여, 데이터는 제외하고 오직 '스키마(테이블 구조)'만 순수한 SQL 형태로 추출하는 방법을 알아보겠습니다.

2. pg_dump를 활용한 스키마 추출 명령어

현재 우리의 PostgreSQL은 도커 컨테이너(toktot-db) 내부에서 실행 중입니다. 따라서 호스트 PC가 아닌 컨테이너 내부로 명령을 전달해야 합니다.

터미널을 열고 프로젝트의 toktot-server 디렉토리로 이동한 뒤, 아래의 명령어를 실행해 주세요.

docker exec toktot-db pg_dump -U toktot -d toktot --schema-only --no-owner --no-acl > schema_dump.sql

명령어를 실행하면 터미널 화면에는 아무런 로그도 출력되지 않지만, 현재 디렉토리에 schema_dump.sql 이라는 파일이 생성됩니다.

3. 마법의 옵션들: 왜 이렇게 작성했을까?

위 명령어에는 꽤 많은 옵션 플래그가 붙어 있습니다. Flyway 마이그레이션에 딱 맞는 스크립트를 추출하기 위해 이 옵션들이 각각 어떤 역할을 하는지 짚고 넘어가는 것이 중요합니다.

• pg_dump: PostgreSQL이 기본적으로 제공하는 데이터베이스 백업 도구입니다. 데이터베이스의 상태를 psql로 다시 적용 가능한 SQL 스크립트 형태로 만들어줍니다.
• -U toktot: 데이터베이스 접속에 사용할 사용자명(User)입니다. 환경 변수에 설정해 둔 POSTGRES_USER 값과 동일합니다.
• -d toktot: 대상 데이터베이스 이름(Database)입니다. 하나의 PostgreSQL 인스턴스 안에는 여러 개의 DB가 존재할 수 있으므로, 정확히 어떤 DB를 덤프할지 명시해야 합니다.
• --schema-only (핵심 옵션): 가장 중요한 옵션입니다. 테이블 안에 들어있는 실제 데이터(INSERT 문)는 전부 제외하고, 테이블 생성(CREATE TABLE)이나 인덱스(CREATE INDEX) 같은 뼈대 구조(DDL)만 추출하라는 의미입니다. 우리의 목적은 마이그레이션 스크립트 제작이므로 데이터는 필요하지 않습니다.
• --no-owner: 추출된 SQL 문에서 ALTER TABLE ... OWNER TO toktot; 와 같이 소유권을 지정하는 구문을 제외합니다. Flyway 스크립트는 로컬, 테스트, 운영 등 다양한 환경에서 실행되어야 하므로 특정 소유자에 종속되지 않게 만드는 것이 필수적입니다.
• --no-acl: GRANT나 REVOKE 같은 권한 부여 구문을 제외합니다. 마이그레이션은 철저하게 테이블의 구조적 정의에만 집중하고, 데이터베이스 권한은 인프라 환경별로 별도 관리하는 것이 실무 표준입니다.
• > schema_dump.sql: 추출된 텍스트 결과물(표준 출력)을 화면에 보여주는 대신 파일로 저장(리다이렉트)하라는 의미입니다.

4. 추출된 파일 결과 검증하기

명령어가 성공적으로 수행되었다면, 만들어진 파일이 제대로 된 내용을 담고 있는지 확인해 볼 차례입니다. 동일한 터미널에서 다음 명령어들을 통해 간단히 검증할 수 있습니다.

# 1. 생성된 파일의 전체 라인 수 확인
wc -l schema_dump.sql

# 2. 파일의 처음 50줄 출력하여 내용 확인
head -50 schema_dump.sql

• wc -l 명령어로 확인했을 때, 23개 테이블의 DDL이 담겨 있으므로 수백 라인 정도의 결과가 나와야 정상입니다. 라인 수가 턱없이 적다면 옵션이나 권한 설정이 잘못되었을 수 있습니다.
• head -50 명령어로 확인했을 때 상단에 PostgreSQL 버전 헤더 정보와 몇 가지 셋팅 옵션들이 보이고, 그 아래로 CREATE TABLE 구문이 시작되는 것을 볼 수 있습니다.

5. 마치며: 추출은 끝, 이제 정제할 시간

성공적으로 초기 데이터베이스의 뼈대를 SQL 스크립트 파일로 추출해 냈습니다.

하지만 지금 뽑아낸 schema_dump.sql 파일을 당장 Flyway의 V1__init.sql로 사용할 수는 없습니다. 자동 추출된 파일에는 pg_dump의 헤더나 불필요한 설정 라인들이 포함되어 있고, 하이버네이트가 자동으로 만들어준 외래 키(FK) 관련 인덱스나 컬럼 네이밍, 데이터 타입(timestamp vs timestamptz) 등이 실무 기준에 맞게 완벽히 정리되어 있지 않기 때문입니다.