SchemaSpy 완전 초보 따라하기 매뉴얼 (PostgreSQL 기준)

대상: DB/ERD를 처음 접하는 분

목표: PostgreSQL 데이터베이스의 스키마/테이블/뷰/관계(FK) 를 자동 분석해서, 읽기 쉬운 설계 문서(HTML + ERD) 를 생성하고 운영 가능한 수준까지 익히기

0. 먼저 큰 그림 (진짜 초보용 1분 요약)

SchemaSpy는 데이터베이스를 읽어서 아래를 자동으로 만들어주는 도구입니다.

  • 테이블 목록
  • 컬럼(열) 설명
  • PK/FK(기본키/외래키)
  • 인덱스
  • 뷰
  • 테이블 간 관계도(ERD)
  • 통계/품질 관점 리포트(사용 안 하는 테이블/고아 테이블 등)

즉, “DB를 코드처럼 문서화” 해주는 도구라고 이해하시면 됩니다.

1. 용어 사전 (필수)

초보자가 가장 먼저 헷갈리는 용어만 정확히 잡고 시작하겠습니다.

1-1) 데이터베이스(Database)

데이터를 저장하는 큰 창고입니다.

1-2) 스키마(Schema)

데이터베이스 안의 “폴더” 개념입니다.

  • 예: public, billing, analytics

1-3) 테이블(Table)

엑셀 시트처럼 행(row)과 열(column)로 된 데이터 구조입니다.

1-4) 컬럼(Column)

테이블의 속성(필드)입니다.

  • 예: id, email, created_at

1-5) PK (Primary Key, 기본키)

테이블에서 각 행을 유일하게 식별하는 키입니다.

  • 보통 id

1-6) FK (Foreign Key, 외래키)

다른 테이블의 PK를 참조하는 컬럼입니다.

  • 관계를 만들어주는 핵심
  • 예: orders.user_id -> users.id

1-7) 인덱스(Index)

검색 속도를 빠르게 해주는 책갈피 같은 구조입니다.

1-8) 뷰(View)

저장된 SELECT 쿼리 결과를 테이블처럼 보여주는 가상 객체입니다.

1-9) ERD (Entity Relationship Diagram)

테이블과 관계를 선으로 그려 보여주는 다이어그램입니다.

1-10) JDBC

자바 프로그램이 DB와 통신할 때 쓰는 표준 연결 방식입니다.
SchemaSpy는 JDBC를 통해 DB를 읽습니다.

2. 언제 SchemaSpy를 쓰면 좋은가?

  • 신규 입사자가 DB 구조를 빠르게 이해해야 할 때
  • 레거시 시스템 문서가 없을 때
  • 운영 DB 변경 전에 영향도를 파악할 때
  • 감사/보안/품질 관점에서 구조를 정기 점검할 때
  • 기획/개발/QA 간 공통 설계 문서를 공유해야 할 때

3. 설치 없이 가장 빠르게 시작 (Docker 방식, 권장)

왜 Docker를 권장하나?

  • 설치 충돌이 적고
  • 팀 내 재현성이 높고
  • CI/CD 자동화로 확장하기 좋기 때문입니다.

3-1) 준비물

  1. Docker 설치
  2. PostgreSQL 접속 정보
    • 호스트(host)
    • 포트(port, 기본 5432)
    • DB명(db)
    • 사용자(user)
    • 비밀번호(password)
  3. 출력 폴더(문서 생성 경로)

3-2) 가장 기본 실행 예시

아래 명령은 가장 직관적인 예시입니다.

docker run --rm \
  -v "$PWD/output:/output" \
  schemaspy/schemaspy:latest \
  -t pgsql \
  -host 127.0.0.1 \
  -port 5432 \
  -db mydb \
  -u myuser \
  -p 'mypassword' \
  -s public \
  -o /output

옵션 설명

  • -t pgsql: DB 타입(PostgreSQL)
  • -host: DB 서버 주소
  • -port: DB 포트
  • -db: 데이터베이스 이름
  • -u: 사용자명
  • -p: 비밀번호
  • -s: 분석 대상 스키마
  • -o: 결과 HTML 출력 경로

3-3) 실행 결과 확인

생성된 output/index.html 파일을 브라우저로 열면 됩니다.

4. 실무에서 자주 쓰는 고급 옵션

4-1) 특정 스키마만 문서화

-s billing

4-2) 여러 스키마를 각각 분리 생성

스키마별로 명령을 분리해서 실행하는 방식이 운영상 가장 깔끔합니다.

4-3) 메타데이터(설명) 파일 적용

테이블/컬럼 설명을 별도 파일로 관리해 문서에 반영할 수 있습니다.
(팀 용어집/데이터 사전 통합에 매우 유용)

4-4) 다이어그램 렌더러(Graphviz) 관련

관계도 품질이 낮거나 그래프가 비정상일 때 Graphviz 설정을 점검합니다.
대형 스키마는 그래프가 과밀해져 스키마별 분할이 필수입니다.

5. 스키마 문서 읽는 법 (초보 실전)

SchemaSpy 페이지를 열면 보통 아래 순서로 보면 이해가 빠릅니다.

  1. Tables 탭: 테이블 전체 리스트 확인
  2. 핵심 도메인 테이블 1개 선택 (예: users)
  3. 컬럼 + PK/FK + 인덱스 확인
  4. Related Tables(연관 테이블)로 이동
  5. ERD로 관계 방향 확인
  6. 다시 목록으로 돌아와 주요 테이블 반복

팁

처음부터 전체를 보지 말고,

  • 사용자
  • 주문
  • 결제
    같이 업무 흐름 단위로 쪼개서 보면 압도감이 줄어듭니다.

6. 흔한 오류와 해결법 (문제해결 치트시트)

6-1) 접속 실패

증상: connection refused, authentication failed

점검 순서:

  1. 호스트/포트 정확한지
  2. 계정/비밀번호 정확한지
  3. DB가 외부 접속 허용하는지 (pg_hba.conf / 방화벽)
  4. SSL 강제 환경인지

6-2) 빈 문서가 생성됨

원인: 스키마명 오타, 권한 부족, 대상 DB 잘못 지정

해결:

  • -s public 확인
  • 읽기 권한 있는 계정 사용
  • DB명 재확인

6-3) 관계(선)가 거의 안 보임

원인: FK가 DB에 선언되지 않았거나 앱 레벨에서만 관계를 관리

해결:

  • FK 제약조건 명시
  • 최소한 핵심 관계라도 DB 레벨 FK로 승격

6-4) 다이어그램이 너무 복잡함

해결:

  • 스키마 분리
  • 핵심 테이블 중심으로 별도 문서 세트 생성
  • 읽는 대상(기획/개발/운영)별 문서 분리

7. 보안/운영 모범사례

  1. 운영 DB 계정은 읽기 전용 계정 사용
  2. 민감 스키마는 제외하거나 별도 권한으로 분리
  3. 생성 문서는 내부 저장소(권한관리)로 배포
  4. 정기 생성(예: 매일 새벽)으로 문서 최신화
  5. DDL 변경(PR 머지) 시 문서 자동 재생성

8. CI/CD 자동화 예시 전략

실무 표준에 가까운 운영 방식:

  1. 마이그레이션 반영 (Flyway/Liquibase)
  2. SchemaSpy 실행
  3. 결과 HTML 아티팩트 저장
  4. 내부 문서 사이트/스토리지에 배포
  5. 링크를 팀 채널에 자동 알림

이렇게 하면 “코드 변경 -> 설계 문서 자동 업데이트”가 완성됩니다.

9. 초보자를 위한 학습 로드맵 (7일)

Day 1

  • 용어(PK/FK/인덱스/뷰) 이해
  • 샘플 DB로 문서 1회 생성

Day 2

  • 본인 프로젝트 DB로 실행
  • public 스키마만 분석

Day 3

  • 핵심 테이블 10개 도메인 맵 작성

Day 4

  • FK 누락 구간 찾아 개선 후보 정리

Day 5

  • 인덱스/조회 패턴 문서화

Day 6

  • 팀 공유용 읽기 가이드 작성

Day 7

  • 자동화(cron 또는 CI) 붙이기

10. 실무 체크리스트 (바로 사용 가능)

  • 읽기 전용 DB 계정 준비
  • 대상 스키마 확정 (public 등)
  • Docker 명령 실행 성공
  • index.html 생성 확인
  • 핵심 테이블 관계 확인
  • 누락 FK/인덱스 개선 과제 등록
  • 문서 배포 경로 확정
  • 주기적 자동생성 설정

11. 요약 (핵심만)

SchemaSpy는 PostgreSQL 구조를 자동으로 분석해서
**“사람이 읽을 수 있는 설계 문서”**로 바꿔주는 가장 실용적인 도구 중 하나입니다.

초보자는

  1. Docker로 1회 생성 ->
  2. 용어 이해 ->
  3. 핵심 도메인별로 읽기 ->
  4. 자동화
    순서로 가면 가장 빠르게 실무 수준에 도달할 수 있습니다.

부록 A) 자주 쓰는 명령 템플릿 (복붙용)

# 1) 출력 폴더 준비
mkdir -p ./schemaspy-output

# 2) 문서 생성
docker run --rm \
  -v "$PWD/schemaspy-output:/output" \
  schemaspy/schemaspy:latest \
  -t pgsql \
  -host <DB_HOST> \
  -port 5432 \
  -db <DB_NAME> \
  -u <DB_USER> \
  -p '<DB_PASSWORD>' \
  -s public \
  -o /output

# 3) 결과 확인 (OS에 따라)
# Linux
xdg-open ./schemaspy-output/index.html

부록 B) 초보자 Q&A

Q1. SchemaSpy가 데이터를 수정하나요?

아니요. 읽기 중심입니다. 다만 안전하게 읽기 전용 계정을 쓰는 것이 원칙입니다.

Q2. 뷰(View)도 나오나요?

환경과 권한에 따라 조회됩니다. 권한이 없으면 누락될 수 있습니다.

Q3. ERD가 이상해요.

대부분 FK 정의 누락 또는 스키마가 너무 커서 과밀한 경우입니다.

Q4. 업계 표준인가요?

절대 단일 표준 도구는 없지만, 자동 DB 문서화 도구로는 매우 널리 쓰이는 축입니다.

필요하시면 다음 단계로, 프로젝트 DB 접속정보 기준으로 스키마별 실행 스크립트/자동화(cron or CI)까지 즉시 맞춤 설계해드릴 수 있습니다.