[DBDiagram, DBDocs] ERD, 문서화에 대한 다양한 팁

왜 글을 작성하게 되었을까?

사실 필자는 과거에 DBDiagram과 DBDocs에 대한 소개를 한 적이 있다.

1. DBDiagram에 대한 소개 : https://devjong12.tistory.com/67
2. DBDocs를 통한 문서화 방법 : https://devjong12.tistory.com/68
3. 문서화한 프로젝트를 DBDocs로 CD구축하는 방법 : https://devjong12.tistory.com/69

사실 해당 포스트를 적을 때만 사용했을 떄만 하더라도 갓 시작할떄라 와 좋다하면서 호다닥 글을 썻던 기억이 난다.

 

하지만 이제 사용기간이 좀 되고, 다양한 경험을 하고 저 글을 보니, 많이 밋밋하다는 느낌을 받고 리뉴얼차원의 글을 작성해 보고자 한다.

추가적으로 나는 현재 유료로 구독을 해서 사용하고있다. 기능이 약간 다를 수 있다.

---

어떤내용이 추가되는 것이며, 어떤 것을 다룰 예정인가?

CD에 대해서는 다룰 예정이 없다. 공식문서가 정말 친절히 설명되어 있기도 하고, 과거에 한 내용에서 추가된게 없기 떄문이다.

주로 다룰 내용은 DBDiagram에서 우아하게 작성하는 법과 이게 DBDocs에서는 어떻게 출력이 되는지를 보여주고자 한다.

• 노트의 멀티라인 사용법
• 스키마에 대한 내용
  • DBDiagram에서의 스키마 구분 방법
  • DBDocs에서의 표기법
• Enum에 대한 활용
  • DBDiagram에서 Enum의 정의 및 활용방법
  • DBDocs에서의 해당 표기 모습
• 유료기능
  • TableGroup
  • HeaderColor
    • 해당 기능의 경우 DBDocs로 올리게될 경우에는 아직 무료사용이 가능한 것으로 알고 있다.

---

프로젝트 예제 페이지

현재 소개할 샘플 예제의 DBDiagram, DBDocs 문서화 페이지 이다.

먼저가서 바로 봐도 괜찮으며, 설명없이도 이해가 가능한 수준이다.

https://dbdiagram.io/d/64551676dca9fb07c49405bc

dbdiagram.io - Database Relationship Diagrams Design Tool

https://dbdocs.io/donsonioc2010/DBDocsSample

dbdocs.io - Database Documentation and Catalog Tool

 

 

추가적으로 과거에 했던 DBDiagram은 아래의 페이지에서 확인이 가능하다.

https://dbdiagram.io/d/62d40b62cc1bc14cc5d32ae5

dbdiagram.io - Database Relationship Diagrams Design Tool

---

노트의 멀티라인 활용법

당시에는 "굳이 멀티라인으로 적어야 하나?" 라는 생각이 매우 컸었기 떄문에 안넣었던 부분이었다.

근데 일을 하다보니 내의사를 명확히 전달해야 하는 경우가 많이 발생했고, 그러기 위해서는 멀티라인으로 넣는 것은 필수였다.

 

사용방법 :  note:'''적고자하는 문자열'''가 DBML에서 안내하는 방법이다.
이후 추가적으로 확인해본 결과 최근에는 패치가 진행된 것인지, note:'문자열'을 해도 멀티라인인 경우에는 인식이 되기는 한다.

하지만 적용이 안되는 경우도 있기 때문에 '''문자열''' 방식으로 쓰기를 권장한다.

 

 

아래의 두개모두 정상 작동 된다..

Project DBDocsSample{
  database_type: 'MariaDB'
  Note: '
    Optinal한 항목입니다. 
    하지만 DBDocs를 활용할 경우 해당 정보를 바탕으로 문서가 생성됩니다.
    해당 프로젝트는 DBDocs와 DBDiagram의 학습이므로 간단하게만 관계를 가져갑니다.
    ---

    MarkDown형식을 지원하지만 HTML을 지원하지는 않습니다. 
    또한 스타일을 바꾸는것역시 제가알기로는 지원하지 않습니다.
  '
}

Project DBDocsSample{
  database_type: 'MariaDB'
  Note: '''
    Optinal한 항목입니다. 
    하지만 DBDocs를 활용할 경우 해당 정보를 바탕으로 문서가 생성됩니다.
    해당 프로젝트는 DBDocs와 DBDiagram의 학습이므로 간단하게만 관계를 가져갑니다.
    ---

    MarkDown형식을 지원하지만 HTML을 지원하지는 않습니다. 
    또한 스타일을 바꾸는것역시 제가알기로는 지원하지 않습니다.
  '''
}

---

스키마 활용방법

가장 다루고 싶었던 내용 2개중 하나이다. 나머지 하나는 Enum이다.

지금은 잘렸지만..? 전에 있던 회사에 있을때 너무 다양한 프로젝트를 진행하려고 하니까 프로젝트별로 스키마를 분류해야 겠다는 생각을 하게 되었다.

즉 2개 이상의 스키마를 표현해야 하는데 한개의 문서에 표현을 하고싶었고, 그러면서 알게 된 부분이 스키마별로 정의를 할 수 있다는 것이었다.

지정하지 않으면 그냥 공통의 Public스키마로 인식한다.

 

---

DBDiagram에서의 사용방법

각 선언부를 가져와봤다. 눈치가 빠른 분들은 금방 알 것같다.

Table auth.t_user as U
Table auth.t_user_profile_resource
Table auth.t_user_provider_key

Table board.article_reply
Table board.article_reply_recent
Table board.article_tags 

Table common.tbl_resource

 

스키마의 선언방법 : ${스키마명}.${테이블명 또는 Enum명}

추가로 선언할떄 입력을 해줘야한다.

---

DBDocs에서의 스키마 표현모습

 

일단 기본적으로 옆의 이미지처럼 DBDocs에서는 GroupBy를 스키마로 할지, 테이블 그룹으로 할지를 지정할 수 있다.

 

그리고 DefaultValue는 스키마로 설정이 되어 있다.

 

 

 

 

 

스키마로 그룹을 묶게 되는 경우 아래의 이미지처럼 표현이 된다. (색상은 구분을 쉽게하기 위해 입혔던걸로, 꼭 입히지 않아도 된다)

 

추가로 설정을 안하게 되면 현재는 없는데 public으로 모두 포함이 된다.

---

Enum의 활용방법

과거에는 그냥 타입지정만 하면 되지 라는 생각이었는데 참 미련했다.
멀티라인으로 설명을 함과 동시에 가장 편한 전달이 Enum이라는 것을 개발꾸준히 하면서 이해하게 되었고, 기록의 필요성을 느꼈다.

 

선언 방법은 간단하다 Table선언을 대신해서 enum선언을 진행하면 된다.

enum의 경우 headercolor라든가, enum자체에 note로의 기록은 불가능하다.
대신 enum의 컬럼들에 대해서는 희망하면 note를 통해 기록이 가능하며, 스키마로 분류하는 것 역시 가능하다..

---

DBDiagram에서의 활용방법

선언 방법

enum auth.user_role{
  GUEST [note: '게스트 권한']
  USER  [note: '사용자 권한']
  ADMIN [note: '관리자']
}

enum auth.user_status{
  WAITING [note: '메일인증 대기상태']
  ACTIVE  [note: '정상 사용']
  DORMANT [note: '휴면']
  BLOCKD  [note: '정지']
  LOCKED  [note: '잠금']
  DELETE  [note: '삭제']
}

enum board.article_status {
  WRITING
  WAITING [note: '대기']
  POST
  HIDING  [note: '숨김처리']
  DELETE  [note: '삭제']
}

---

사용 방법

사용법 역시 직관적이다. 타입대신 enum을 기록해주면 되며, 참고로 Alias는 불가능하다.

enum board.board_status{
  HIDE    [note: '숨김처리']
  USE     [note: '현재 사용중']
  NOT_USE [note: '현재 사용중 X']
  DELETE  [note: '삭제 처리']
}

Table board.category {
  id bigint(20) [pk, not null, increment]
  is_use board.board_status [not null, default: 'USE', note:'카테고리 상태']
}

---

DBDocs에서의 표현 모습

Enum으로 선언한 경우 DBDocs에서는 다음과 같이 타입에 🅴 마크로 Enum형식이라는 것을 직관적으로 알 수 있다.

 

이후 마우스오버를 하는 경우 다음과 같이 Enum의 항목들을 표현해주며, Note를 기록하지 않은 경우 항목만 출력한다.

---

부가적으로 유용한 유료 기능들

TableGroup

내가 주시하고 싶은 Table을 Grouping하는 기능이며, 알고 있는 사항으로는 구독을 해야 DBDiagram에서 정상 사용이 가능한 것으로 알 고 있다. 

 

해당 기능은 DBDiagram에서는 사실 무슨느낌이지 라는 생각인데 이게 DBDocs로 문서화가 되면 또 맛깔나게 변하는 기능이다.

또한 TableGroup은 테이블마다 한번씩만 선언 가능하며, 타 테이블에 중복해서 추가하는 작업은 불가능하다.

---

DBDiagram에서의 선언 방법

Admin이라는 주제로 관심사가 뭉칠 수 있는 테이블을 묶어봤다.

묶게될 경우 아래의 사진처럼 표시가 된다.

TableGroup Admin{
  codes.t_code_category
  codes.t_code_key
  codes.t_code_value
  logs.t_logs
  logs.t_user_login_logs
}

그룹핑을 할경우 이렇게 박스자체를 하이딩 시키는 유용한 기능도 존재한다..!

---

DBDocs에서는?

먼저 Table Group같은 경우에는 검색조건(Group By)를 Table Group으로 설정해야한다.

아래처럼 말이다.

 

그러면 다음과 같이, 그룹으로 묶은 테이블, 묶지 않는 테이블로 나뉘게 되며, no Group을 클릭하게 될경우 해당 테이블리스트를 접거나, 펼치는 기능만 존재한다.

 

하지만 Group으로 묶은 항목에 대해서는 제목을 클릭하게 될 수 있다.

아래처럼, 그룹핑한 테이블의 정보만 메인페이지에서 처럼 출력이 되는데, 관심사가 있는 부분만 모아서 보기 정말 유용한 기능이다.

---

headercolor

헤더 컬러의 경우에도 유용하게 사용하는 기능이다. 나는 보통 스키마 또는 비슷한 기능끼리 묶어주도록 노력을 하는 편인데, 유료기능이다.
DBDiagram에서만 지금은 유료제공이라 DBDocs에서는 무료로 알고있다. 선언하고 DBDocs 올리면 사용은 가능할 것이다. 

---

DBDiagram에서의 선언 방법 및 표현 모습

Table의 선언시 다음과 같이 선언을 해봐라. 16진수로 컬러를 입력하면 되며, headercolor: colorValue 를 하면 된다.

Table common.tbl_resource [
  headercolor: #24BAB1,
  note: '파일의 저장 정보 테이블'
]

선언시 무료기능에서 나오는지는 확실치 않지만, 유료기능의 경우 DBDiagram에서 다음의 컬러색으로 헤더가 변경이 된다.

---

DBDocs에서의 표현 모습

필자의 경우 headercolor에서 이 기능이 가장 마음에 들었다. 

DBDocs로 프로젝트를 commit을 진행할 경우 아래의 이미지처럼, 해당 컬러가 Table로 보이게 된다.

 

해당 부분이 매우 만족스러웠고, 기능이 유사하지만 다른 스키마인 경우 컬러를 통해 표현하는 경우를 많이 해보다보니, 이 headercolor를 자주 사용하게 되었다.

 

혹시 사용할 일이 있다면 해보는것을 추천한다

 

---

글을 작성하며..

해당 툴을 쓰기 시작한지 곧 1년이 다되가는데 믿기지가 않는다. 😱

쓰는 방식을 늘려가면서 많은 성장을 아직도 해야하지만, 성장하고 있다고 느끼는 과정중 하나라고 생각은 한다.

 

멀티라인이랑 Enum을 왜 써야하는지, 스키마는 왜 분류를 해줘야하는지, 그 과정에서 어떻게 해야 조금이라도 더 이해하기 쉽게 하기 위해 보기 좋게 만들것인지 고민을 했던 과정들이 다시금 느끼지만... DBDiagram팀에서 왜 이 기능들을 만들게 된지를 많이 느꼇던부분 같고, 나도 개발하면서 왜 필요한지를 체감을 많이 할 수 있었다..