DB 스키마 문서를 Notion·GitHub에 올리는 법 — 손으로 다시 치지 않고
· 갱신
어느 팀에나 하나씩 있습니다. 위키의 “데이터베이스 스키마” 페이지. 초기 몇 달 동안 누군가 정성껏 썼고, PNG로 뽑은 다이어그램과 테이블마다 컬럼 표가 있습니다. 그리고 틀렸습니다. 그 뒤로 마이그레이션이 세 번 나갔는데, 고치는 데 한 시간 걸리는 페이지를 다시 열어 본 사람이 없기 때문입니다.
이 페이지가 틀린 건 사람들이 게을러서가 아닙니다. 손으로 쳤기 때문입니다. 테이블명, 컬럼 타입, 어느 컬럼이 외래키인지 — 페이지에 적힌 모든 것은 이미 데이터 모델에 있었습니다. 그것을 위키에 옮겨 적는 순간 사본이 하나 더 생겼고, 사본은 벌어집니다.
이 글은 반대 방향의 방법입니다. 모델에서 스키마 페이지를 마크다운 한 파일로 내보내고, 팀이 읽는 곳에 붙여 넣고, 스키마가 바뀌면 다시 내보냅니다. 파일에 무엇이 들어 있는지, GitHub과 Notion에서 어떻게 그려지는지(Notion은 클릭 한 번이 필요합니다), 다른 도구는 어떤지, 그리고 이 방식이 어디서 멈추는지 순서대로 보겠습니다.
페이지에 필요한 것, 그리고 그 목록이 중요한 이유
스키마 페이지에서 독자가 실제로 쓰는 것만 남기면 짧습니다.
- 다이어그램. 새로 온 사람이 표를 읽기 전에 전체 모양을 보기 위해.
- 테이블 목록. 한 줄씩.
- 테이블마다 컬럼 — 타입, PK/FK, Null 허용, 기본값, 그리고 말로 쓴 설명.
- 인덱스, 그리고 테이블 사이의 관계.
이 중 위키 페이지에서 “작성”하는 항목은 하나도 없습니다. 전부 모델에 대한 사실입니다. 그게 논지의 전부입니다. 다른 곳에 사는 사실만으로 이뤄진 페이지는 그 사실이 사는 곳에서 생성돼야 합니다. 테스트 결과 보고서를 손으로 베껴 쓰지 않는 것과 같습니다.
모델에서 마크다운 한 파일
Sqemo의 내보내기 메뉴에 정의서 내보내기 (Markdown) 항목이 있습니다. .md 파일 하나를 씁니다.
- 프로젝트명과 엔터티·관계 수 한 줄.
erDiagram이 든mermaid코드 블록 — 모든 테이블이 컬럼과 PK/FK 표시를 달고, 모든 관계가 까마귀발 기호로, 식별 관계는 실선·비식별 관계는 점선으로.- 엔터티 목록 표. 각 행이 아래 섹션으로 링크됩니다.
- 엔터티마다 한 섹션: 설명, 컬럼 표(논리명·물리명·타입·도메인·PK·FK·Null·기본값·설명), 인덱스가 있으면 인덱스 표.
- 관계 표.
컬럼 표는 CSV 정의서를 만드는 코드와 같은 코드에서 나오므로 둘이 어긋나는 일은 없습니다. 표 헤더는 앱의 UI 언어를 따릅니다 — 한국어 UI면 한국어 헤더입니다.
왜 PDF나 HTML이 아니라 마크다운인가. GitHub·GitLab·Notion·Obsidian과 대부분의 사내 위키가 붙여넣기로 받아 주는 유일한 형식이 마크다운이고, 마크다운 안의 mermaid는 다이어그램이 텍스트라는 뜻이기 때문입니다. diff가 되고, 병합이 되고, 조용히 낡아 가는 스크린샷이 아닙니다.
GitHub: 코드 옆에 커밋한다
가장 단순한 보관처는 저장소 자체입니다. docs/schema.md로 두면 됩니다. GitHub은 마크다운 파일·위키·이슈·풀 리퀘스트에서 mermaid 블록을 기본으로 그립니다. 플러그인도, 액션도, CI 단계도 없습니다.
파일이 Git에 들어가면 위키에서는 생기지 않는 일 두 가지가 생깁니다.
- diff가 변경 이력이 됩니다. 마이그레이션 뒤에 다시 내보내면 풀 리퀘스트가 어느 컬럼이 생겼고 어느 타입이 바뀌었고 어느 외래키가 옮겨졌는지 그대로 보여 줍니다. 리뷰어는 코드 변경과 같은 PR에서 스키마 변경을 읽습니다.
- 엔터티 목록의 링크가 동작합니다. 목록 표가 GitHub의 제목 앵커로 각 섹션에 연결되므로 테이블 60개짜리 문서도 오갈 수 있습니다.
저장소가 GitLab이어도 같은 파일이 같은 방식으로 그려집니다. GitLab은 몇 년 전부터 mermaid 펜스를 지원했습니다. Azure DevOps 위키도 mermaid를 그리지만 ::: mermaid라는 자체 펜스 문법을 쓰므로 거기서는 블록을 두 줄 고쳐야 합니다.
Notion: 붙여넣고, 한 번 클릭
Notion은 엔지니어가 아닌 독자가 가장 많이 있는 곳이라 가장 꼼꼼히 확인했습니다.
파일 내용을 복사해 빈 Notion 페이지에 붙여넣습니다. Notion은 붙여넣는 순간 마크다운을 변환합니다. # 줄은 제목 블록이 되고, 파이프 표는 Notion 표가 되고, 펜스 블록은 코드 블록이 됩니다. 중요한 건 펜스에 mermaid라고 적혀 있었기 때문에 코드 블록의 언어가 자동으로 Mermaid로 잡힌다는 점입니다. 목록에서 골라 줄 필요가 없습니다.
Notion이 붙여넣기 때 해 주지 않는 딱 한 가지는 블록을 다이어그램 보기로 바꾸는 것입니다. 코드 블록에 마우스를 올리고 오른쪽 위 보기 전환을 열어 미리보기를 고르세요. 다이어그램이 그 자리에 그려지고 그대로 유지됩니다.
GitHub과 다른 점 하나. Notion에는 페이지 안 제목 앵커가 없어서 엔터티 목록의 링크가 밑줄 글자로 보이기만 하고 이동하지는 않습니다. 표와 다이어그램에는 영향이 없습니다. 거슬리면 붙여넣은 뒤 그 블록 하나만 지우면 됩니다.
Obsidian, 그리고 플러그인이 필요한 곳
Obsidian은 읽기 보기에서 mermaid 펜스를 기본으로 그리므로 스키마 노트는 파일 하나 떨어뜨리는 것으로 끝입니다. Confluence는 mermaid를 기본으로 그리지 않습니다. 마켓플레이스 매크로가 필요하고, 어느 매크로가 깔려 있는지는 관리자에게 물어야 합니다. Confluence라면 컬럼 표는 그대로 붙고 다이어그램 블록만 매크로가 필요합니다.
문서를 정직하게 유지하는 순환
이 모든 것의 요점은 첫 번째 내보내기가 아닙니다. 두 번째 내보내기입니다.
스키마가 바뀌면 — 컬럼이 추가되고, 타입이 넓어지고, 관계 방향이 뒤집히면 — 모델에서 고치고, 마크다운을 다시 내보내고, 페이지를 교체합니다. GitHub에서는 diff가 곧 릴리스 노트인 커밋 하나입니다. Notion에서는 페이지 본문 전체 선택, 붙여넣기, 미리보기 전환 한 번입니다.
이 순환은 모델이 실제로 원본일 때만 작동합니다. 운영 DB를 손으로 고치고 모델은 안 고쳤다면, 내보낸 문서는 정확히 모델만큼 틀립니다. Sqemo의 Pro 플랜에 라이브 DB와 모델을 대조하는 드리프트 검사가 있는 이유가 그것이고, 무료 플랜에서는 현행 DDL을 모델 위에 다시 가져오는 것으로 같은 일을 손으로 합니다.
어디서 멈추는가
한계를 구체적으로 적어 두겠습니다. 스키마 페이지가 낡는 건 늘 과하게 약속했기 때문이니까요.
- 설명은 모델에 있어야 합니다. 모델에 설명이 없는 컬럼은 문서에서 논리명이 설명 자리를 대신합니다. 틀린 건 아니지만 문서도 아닙니다. 문서는 빠진 설명을 보이게 해 줄 뿐, 써 주지는 않습니다.
- 아주 큰 스키마는 아주 큰 다이어그램이 됩니다. 테이블 300개짜리
erDiagram은 그려지긴 하지만 아무도 읽지 않습니다. 아래 표는 여전히 쓸모 있으니 다이어그램 블록을 지우거나, 그림이 아니라 지도라고 받아들이면 됩니다. 더 나은 방법은 통째로 내보내지 않는 것입니다. 내보내기 대화상자에 범위(전체·선택한 엔터티·주제영역 하나) 설정이 있어서, 테이블 300개짜리 모델을 주제영역별 문서 열몇 개로 나누면 다이어그램마다 독자가 따라갈 수 있는 크기가 되고, 영역 이름이 파일명과 제목에 붙습니다. - 물리 모델입니다. 문서는 논리명 옆에 물리명을 함께 보여 주고 데이터 타입은 물리 타입을 씁니다. 논리 모델만 보고 싶은 독자에게는 이 페이지가 아닙니다.
테이블 정의서·컬럼 정의서 쓰는 법이 “무엇을 적는가”를 다뤘다면, 이 글은 “어디에 두고 어떻게 최신으로 유지하는가”입니다. 누군가 손으로 친 페이지가 아니라, 모델이 쓴 파일로.