Mermaid로 ERD 그리기: 문법부터 한계까지

2026년 8월 18일

README나 위키에 ERD를 넣어야 한다면 Mermaid가 가장 가벼운 답입니다. 코드 블록 하나 적으면 GitHub이 알아서 다이어그램으로 그려 주니, 이미지 파일을 만들고 업로드하고 갱신하는 일이 통째로 사라집니다.

이 글에서는 erDiagram 문법을 게시판 DB 예제로 처음부터 익히고, 관계 기호 읽는 법과 실전에서 부딪히는 지점들, 그리고 Mermaid로는 안 되는 일까지 순서대로 다룹니다.

어디에 적으면 그려지나

Mermaid는 다이어그램을 텍스트로 적는 문법이고, 그걸 그림으로 바꿔 주는 건 렌더러입니다. 이미 쓰고 계신 도구 대부분에 렌더러가 들어 있습니다.

GitHub / GitLab: 마크다운의 ```mermaid 코드 블록을 자동으로 그려 줍니다. README에 ERD를 넣는 가장 흔한 경로입니다.
Notion: 코드 블록을 만들고 언어를 Mermaid로 고르면 됩니다.
VS Code: Markdown Preview Mermaid Support 같은 미리보기 확장을 설치하면 에디터 안에서 바로 보입니다.
mermaid.live: 공식 온라인 에디터입니다. 문법을 실험하거나 PNG/SVG로 뽑을 때 편합니다.

설치할 것도 계정을 만들 것도 없이, 지금 쓰는 문서 도구에 코드 블록만 적으면 된다는 게 Mermaid의 제일 큰 매력입니다.

첫 다이어그램: 테이블 하나부터

erDiagram이라고 선언하고 테이블(개체)을 중괄호로 적습니다. 각 줄은 "자료형 컬럼명 키 표시" 순서입니다.

erDiagram
  MEMBERS {
    bigint id PK
    varchar email UK
    varchar nickname
    datetime created_at
  }

PK, FK, UK가 각각 기본키·외래키·유니크 표시이고, 렌더링하면 표 형태의 개체 박스가 나옵니다. 컬럼 설명을 붙이고 싶으면 줄 끝에 따옴표로 적습니다.

    bigint id PK "대리키"

자료형에 길이까지 적는 varchar(255) 표기도 mermaid 10 기준으로 정상 렌더링됩니다. 다만 GitHub 같은 렌더러는 내장 mermaid 버전이 제각각이라, 오래된 환경에서 오류가 나면 괄호부터 빼 보는 게 가장 빠른 대처입니다.

관계 기호 읽는 법

두 테이블 사이의 관계는 한 줄이면 됩니다.

  MEMBERS ||--o{ POSTS : "작성"

"회원 한 명이 게시글을 0개 이상 작성한다"는 뜻입니다. 기호가 암호처럼 보이지만 구조를 알면 단순합니다. 선 양 끝의 기호가 각 테이블 쪽 카디널리티이고, 안쪽이 최소·바깥쪽이 최대입니다.

기호	의미
`\|\|`	정확히 1
`\|o`	0 또는 1
`}\|`	1 이상
`}o`	0 이상

그래서 자주 쓰는 조합은 이렇게 읽힙니다.

||--o{ — 1 대 0..N (가장 흔한 부모-자식)
||--|{ — 1 대 1..N (자식이 최소 하나는 있어야 할 때)
}o--o{ — N 대 M (다대다)

가운데 선도 의미가 있습니다. --(실선)는 식별 관계, ..(점선)는 비식별 관계입니다. 처음에는 실선 하나로 통일해도 그림을 읽는 데 지장이 없으니, 구분이 필요해지면 그때 나누면 됩니다. 이 기호 체계 자체(까마귀발 표기법)가 낯설다면 ERD 표기법 총정리에서 기초부터 볼 수 있습니다.

실전: 게시판 DB 전체를 그려 보면

회원·카테고리·게시글·댓글, 네 테이블짜리 게시판을 통째로 적으면 이렇습니다.

erDiagram
  MEMBERS ||--o{ POSTS : "작성"
  CATEGORIES ||--o{ POSTS : "분류"
  POSTS ||--o{ COMMENTS : "달림"
  MEMBERS ||--o{ COMMENTS : "작성"

  MEMBERS {
    bigint id PK
    varchar email UK
    varchar nickname
  }
  CATEGORIES {
    int id PK
    varchar name UK
  }
  POSTS {
    bigint id PK
    bigint member_id FK
    int category_id FK
    varchar title
  }
  COMMENTS {
    bigint id PK
    bigint post_id FK
    bigint member_id FK
  }

렌더링 결과는 이렇게 나옵니다.

Mermaid erDiagram으로 그린 게시판 ERD — 4개 테이블과 관계선 렌더링 결과

관계를 위에 몰아서 적고 개체 정의를 아래에 두는 게 요령입니다. 다이어그램의 뼈대(누가 누구와 연결되는가)를 코드 첫 몇 줄만 보고 파악할 수 있고, diff가 났을 때도 관계 변경과 컬럼 변경이 구분되어 보입니다.

이 게시판 설계 자체가 어떻게 나온 건지 궁금하다면, 개체를 뽑고 관계를 정하는 과정부터 ERD 그리는 법에서 같은 예제로 다루고 있습니다.

써 보면 부딪히는 것들

Mermaid ERD를 실제로 쓰다 보면 몇 가지 벽을 만나게 됩니다. 위 렌더링 이미지에도 힌트가 있습니다.

배치를 손댈 수 없습니다. 위 그림에서 CATEGORIES가 오른쪽 위에, COMMENTS가 아래에 놓인 건 전부 Mermaid가 정한 겁니다. 테이블을 끌어서 옮기는 기능은 없고, 코드 순서를 바꾸면 결과가 달라지긴 하지만 원하는 배치를 만드는 방법은 아닙니다. 네 테이블이면 봐줄 만한데, 테이블이 스무 개를 넘어가면 선이 얽히기 시작하고 그때부터는 배치를 못 고치는 게 진짜 불편해집니다.

스키마 정보를 다 담지 못합니다. NOT NULL, 기본값, 인덱스, CASCADE 같은 정보는 적을 자리가 없습니다. 그림용 요약으로는 충분하지만, 이 코드만 보고 실제 테이블을 만들 수는 없다는 뜻입니다.

SQL과 오가는 길이 없습니다. Mermaid 코드를 DDL로 바꿔 주는 기능도, DDL을 읽어 Mermaid를 만들어 주는 기능도 본체에는 없습니다. 그림과 실제 스키마가 각자 관리되는 이중 관리가 시작되는 지점입니다.

명세서가 안 나옵니다. 검수나 인수인계에서 요구하는 테이블 명세서 문서는 별개로 만들어야 합니다.

자주 묻는 질문

Mermaid ERD는 어디서 렌더링되나요?

GitHub과 GitLab은 마크다운 안의 mermaid 코드 블록을 자동으로 그려 주고, Notion도 코드 블록 언어를 Mermaid로 고르면 됩니다. VS Code는 미리보기 확장을 설치하면 되고, 급할 때는 공식 온라인 에디터인 mermaid.live에 붙여넣는 게 가장 빠릅니다.

자료형에 길이(VARCHAR(255))까지 적을 수 있나요?

됩니다. mermaid 10 기준으로 varchar(255)처럼 괄호가 든 자료형도 정상 렌더링되는 걸 확인했습니다. 다만 렌더러마다 내장된 mermaid 버전이 달라서, 오래된 환경에서는 오류가 날 수 있습니다. 안 그려지면 괄호를 빼는 게 가장 간단한 대처입니다.

테이블 위치를 마음대로 옮길 수 있나요?

안 됩니다. Mermaid는 배치를 전부 자동으로 계산하고 수동 조정 기능이 없습니다. 코드 순서를 바꾸면 배치가 조금 달라지긴 하지만 원하는 자리에 놓는 방법은 없어서, 배치를 다듬고 싶은 시점이 전용 도구로 넘어갈 시점입니다.

Mermaid 코드를 실제 DB 테이블로 만들 수 있나요?

Mermaid 자체에는 SQL로 내보내는 기능이 없습니다. 흐름을 반대로 잡는 걸 권합니다. 스키마는 DDL로 관리하고, 문서에 넣을 그림이 필요할 때 DDL에서 Mermaid를 만들어내는 방향이면 두 쪽 다 잃는 게 없습니다.

정리하면, README에 넣을 가벼운 구조도는 Mermaid로 그리고, 편집·검증·명세서가 필요한 단계는 전용 도구로 작업하는 게 효율적입니다. 같은 일을 두 곳에서 하지 말고 단계별로 나눠 쓰면 됩니다.