테이블 명세서는 정해진 양식이 있는 문서가 아닙니다. 그래도 검수자가 반드시 확인하는 항목은 정해져 있습니다. 컬럼명(물리/논리), 자료형과 길이, NULL 허용 여부, 기본값, 키와 제약 조건, 그리고 설명입니다. 이 항목들만 갖추면 어떤 현장에 내도 부족하다는 말은 듣지 않습니다.
이 글에서는 그 필수 항목을 정리하고, 복사해서 바로 쓸 수 있는 양식을 실제 예시와 함께 작성하겠습니다. 검수에서 자주 지적받는 지점들을 짚은 뒤, 마지막에는 이 문서를 직접 작성하지 않고 SQL에서 자동으로 만들어내는 방법까지 다룹니다.
명세서에 꼭 들어가는 항목
명세서는 두 부분으로 나뉩니다. 테이블 자체에 대한 요약과, 컬럼 하나하나의 정의입니다.
테이블 요약에는 물리명(members), 논리명(회원), 테이블 설명, 그리고 필요하면 문자셋 정도가 들어갑니다. 작성자·수정일 칸을 두는 양식도 많은데, 뒤에서 이야기하겠지만 이 칸이 관리되는 현장을 저는 거의 못 봤습니다.
컬럼 정의가 본체입니다. 검수자가 실제로 보는 항목은 이렇습니다.
- 컬럼명 (물리명과 논리명)
- 자료형과 길이:
VARCHAR(255)처럼 길이까지 - NULL 허용 여부
- 기본값
- 키·제약: PK, FK, UNIQUE, 인덱스 여부
- 설명: 이 컬럼이 왜 있는지 한 줄
항목마다 검수자가 보는 포인트가 조금씩 다릅니다. NULL 허용은 단순한 기술 속성이 아니라 업무 규칙의 기록입니다. "전화번호는 없어도 되는가"라는 질문의 답이 이 칸에 남습니다. 기본값은 애플리케이션이 값을 안 넣었을 때 DB가 어떻게 행동하는지를 보여주는 칸이라, 비워져 있으면 "이 컬럼은 반드시 앱이 채운다"는 뜻으로 읽힙니다. 키 칸은 PK·FK·UK(UNIQUE)·IX(인덱스) 정도의 약어로 통일해 두면 표가 깔끔해집니다.
여기에 테이블 수준의 부록으로 인덱스 목록과 FK 관계(어느 테이블의 어느 컬럼을 참조하는지, 삭제 시 동작은 무엇인지)를 붙이면 완성입니다. 부록 예시는 아래 양식에서 함께 보겠습니다. FK 관계를 다이어그램의 기호로 읽는 법이 궁금하면 ERD 표기법 총정리가 있습니다.
바로 쓰는 양식: 게시판 DB 예시
ERD 그리는 법에서 설계한 게시판 DB로 양식을 채워 보겠습니다. 먼저 가장 단순한 members 테이블입니다.
테이블: members (회원): 서비스 가입 계정
| No | 컬럼명 | 논리명 | 자료형 | NULL | 기본값 | 키 | 설명 |
|---|---|---|---|---|---|---|---|
| 1 | id | 회원 번호 | BIGINT | N | AUTO_INCREMENT | PK | 대리키 |
| 2 | 이메일 | VARCHAR(255) | N | — | UK | 로그인 계정, 변경 가능 | |
| 3 | nickname | 닉네임 | VARCHAR(50) | N | — | — | 화면 표시용 |
| 4 | created_at | 가입 시각 | DATETIME | N | CURRENT_TIMESTAMP | — | 앱 미입력 시 DB가 기록 |
FK가 있는 테이블은 한 줄이 더 필요합니다. posts를 같은 양식으로 옮기면 이렇게 됩니다.
테이블: posts (게시글): 회원이 카테고리에 작성하는 글
| No | 컬럼명 | 논리명 | 자료형 | NULL | 기본값 | 키 | 설명 |
|---|---|---|---|---|---|---|---|
| 1 | id | 게시글 번호 | BIGINT | N | AUTO_INCREMENT | PK | 대리키 |
| 2 | member_id | 작성 회원 | BIGINT | N | — | FK | members.id 참조 |
| 3 | category_id | 소속 카테고리 | INT | N | — | FK | categories.id 참조 |
| 4 | title | 제목 | VARCHAR(200) | N | — | — | |
| 5 | content | 본문 | MEDIUMTEXT | N | — | — | 장문 대비 |
| 6 | created_at | 작성 시각 | DATETIME | N | CURRENT_TIMESTAMP | — |
그리고 테이블 아래에 부록 두 개를 붙입니다. 검수자가 관계와 성능을 확인하는 곳이 여기입니다.
외래키
| 이름 | 컬럼 | 참조 대상 | 삭제 시 |
|---|---|---|---|
| fk_posts_member | member_id | members.id | RESTRICT |
| fk_posts_category | category_id | categories.id | RESTRICT |
인덱스
| 이름 | 컬럼 | 유형 |
|---|---|---|
| pk_posts | id | PK |
| uq_members_email | UNIQUE |
이 표들을 그대로 엑셀에 붙여 넣으면 양식이 됩니다. 시트 하나에 테이블 하나, 표지 시트에는 테이블 목록과 문서 기준일(어느 시점의 스키마인지)을 적습니다. 이 구성이 검수받을 때 가장 무난합니다.
한 가지 팁을 드리면, 논리명과 설명 칸을 비워둔 명세서가 의외로 많습니다. 물리명과 자료형은 DB에서 언제든 다시 뽑을 수 있지만, "이 컬럼이 왜 있는지"는 문서에만 남습니다. 명세서를 굳이 만드는 이유가 사실 그 칸에 있습니다.
검수에서 자주 지적받는 다섯 가지
명세서를 받아 보는 입장에서 어떤 지적이 나오는지 알면, 처음부터 그 지점을 피해서 쓸 수 있습니다. 자주 나오는 순서대로 다섯 가지입니다.
1. 논리명이 화면 용어와 따로 노는 것. 화면에서는 "별명"인데 명세서에는 "닉네임"으로 적혀 있으면, 검수자는 어느 쪽이 맞는지부터 물어봅니다. 논리명은 기획서·화면에서 쓰는 용어와 맞추는 게 원칙입니다.
2. 자료형과 실제 데이터의 불일치. VARCHAR(50)이라고 적혀 있는데 실제 데이터에 60자짜리가 들어 있는 경우입니다. 문서를 먼저 쓰고 DB를 나중에 고친 흔적이라, 신뢰도 전체가 의심받는 계기가 됩니다.
3. FK 표기만 있고 참조 대상이 없는 것. "FK"라고만 적으면 어느 테이블의 어느 컬럼을 참조하는지, 부모가 지워질 때 어떻게 되는지 알 수 없습니다. 참조 대상과 삭제 규칙까지가 FK 정보입니다.
4. 어느 시점의 스키마인지 알 수 없는 것. 기준일 없는 명세서는 "지금 DB와 같은가"라는 질문에 답할 수 없습니다. 표지에 기준일 한 줄이면 해결되는데 의외로 빠져 있는 문서가 많습니다.
5. 실제 DB와 대조하면 다른 것. 가장 치명적이고, 가장 흔합니다. 다음 섹션에서 이야기할 수기 관리의 구조적 문제라서, 개인의 꼼꼼함으로는 잘 해결되지 않습니다.
다섯 가지 중 2·3·5번은 뒤에서 다룰 자동 생성으로 원천 차단됩니다. 문서가 스키마에서 나오면 스키마와 다를 방법이 없으니까요.
수기 작성의 함정: 문서가 스키마를 따라가지 못한다
명세서를 한 번 작성하는 것 자체는 어렵지 않습니다. 정작 힘든 건 그다음부터입니다.
스키마는 개발이 진행되는 내내 바뀝니다. 컬럼이 추가되고, 타입이 늘어나고, 인덱스가 생깁니다. 그때마다 엑셀을 같이 고치는 팀은 드뭅니다. 몇 주 지나면 명세서가 실제 DB와 어긋나기 시작하고, 그걸 한 번 확인한 뒤로는 아무도 명세서를 보지 않게 됩니다.
파일 관리도 함정입니다. 명세서_최종.xlsx, 명세서_최종_v2.xlsx, 명세서_진짜최종.xlsx. 웃자고 하는 얘기가 아니라, 어느 파일이 최신인지 아무도 확신하지 못하는 상태는 명세서가 어긋나 있는 상태만큼 위험합니다.
SI 현장이라면 부담이 하나 더 있습니다. 명세서는 계약 산출물이라 검수 대상이고, 검수는 코드보다 문서를 먼저 봅니다. 납품 직전에 명세서와 실제 스키마를 한 줄씩 대조해 본 분이라면, 그 작업을 다시 하고 싶지 않다는 데 동의하실 겁니다.
SQL에서 자동 생성하기
해법은 방향을 바꾸는 겁니다. 명세서의 원본은 문서가 아니라 스키마입니다. DDL에는 컬럼명, 자료형, NULL, 기본값, 키까지 명세서 필수 항목의 대부분이 이미 들어 있습니다. 없는 건 논리명과 설명뿐인데, 이것도 DDL의 COMMENT로 채울 수 있습니다.
CREATE TABLE members (
id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '회원 번호',
email VARCHAR(255) NOT NULL UNIQUE COMMENT '이메일 — 로그인 계정',
nickname VARCHAR(50) NOT NULL COMMENT '닉네임 — 화면 표시용',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '가입 시각'
) COMMENT '회원';이렇게 코멘트를 단 DDL을 WorksCove ERD에 붙여넣으면 다이어그램과 함께 위 양식 그대로의 테이블 명세서가 만들어지고, 검수용 엑셀로도 바로 내보낼 수 있습니다. 운영 중인 DB라면 DDL을 뽑을 필요도 없이 리버스 엔지니어링으로 직접 가져오면 되고, 접근이 제한된 서버라면 SSH 터널을 거쳐 연결하는 방법도 있습니다.
DDL에 적어둔 COMMENT '회원'이 테이블 논리명으로, 컬럼 코멘트가 설명 칸으로 그대로 들어간 것을 볼 수 있습니다. 관계와 인덱스는 스키마에서 읽어낸 것이라 따로 적을 필요조차 없습니다.
코멘트를 다는 팀 규칙 세 가지
자동 생성의 품질은 코멘트의 품질이 정합니다. 팀에서 이 세 가지만 정해두면 명세서가 눈에 띄게 좋아집니다.
- 형식을 통일합니다. "논리명 — 부가 설명" 한 가지 형태로 맞추면, 도구가 논리명과 설명을 나눠 담기도 좋고 사람이 읽기에도 일관됩니다.
- 코드값은 반드시 나열합니다.
status TINYINT COMMENT '상태: 1=활성, 2=휴면, 3=탈퇴'같은 식입니다. 이 한 줄이 없으면 코드값의 의미는 담당자의 기억에만 남게 됩니다. - 숫자에는 단위를 밝힙니다.
amount BIGINT COMMENT '결제 금액(원)'처럼요. 원인지 달러인지, MB인지 GB인지는 코멘트 없이는 알 방법이 없습니다.
이미 코멘트 없이 운영 중인 DB라면 전체를 한 번에 달려고 하지 않아도 됩니다. 새로 만드는 테이블과 수정하는 테이블부터 적용하고, 기존 것은 핵심 도메인(회원·주문처럼 모두가 보는 테이블)부터 채워 나가는 쪽이 현실적입니다.
갱신은 수정이 아니라 재생성
이 방식의 진짜 이점은 첫 생성이 아니라 그 뒤에 있습니다. 스키마가 바뀌면 명세서를 고치는 게 아니라 다시 생성합니다. 문서가 어긋날 틈 자체가 없어지고, "최신본이 어느 파일이냐"는 질문도 사라집니다. 엑셀을 요구하는 검수 프로세스는 그대로 두고, 엑셀을 만드는 일만 자동화하는 겁니다.
앞에서 본 검수 지적 다섯 가지 중 자료형 불일치(2), FK 정보 누락(3), 실DB와의 불일치(5)가 이 지점에서 사라집니다. 남는 건 논리명을 화면 용어와 맞추는 일(1)과 표지에 기준일을 적는 일(4)인데, 이건 자동화가 아니라 습관의 영역입니다.
자주 묻는 질문
테이블 명세서와 테이블 정의서는 다른 문서인가요?
현장에 따라 부르는 이름이 다를 뿐 사실상 같은 문서입니다. 명세서·정의서·스키마 정의서 모두 테이블의 컬럼 구성과 제약 조건을 정리한 산출물을 가리킵니다. 발주처나 팀이 쓰는 용어를 따르면 됩니다.
명세서는 꼭 엑셀로 만들어야 하나요?
표준이라기보다 관행입니다. 검수·납품 과정에서 엑셀을 요구하는 곳이 많아 최종 산출물은 엑셀인 경우가 흔하지만, 원본까지 엑셀로 관리할 이유는 없습니다. 스키마에서 자동 생성하고 제출할 때만 엑셀로 내보내는 쪽이 안전합니다.
컬럼 코멘트는 어디까지 자세히 써야 하나요?
논리명 하나, 필요하면 부가 설명 한 줄이면 충분합니다. 다만 코드값을 담는 컬럼은 값의 의미를 반드시 나열하고(1=활성, 2=휴면처럼), 숫자 컬럼은 단위를 밝혀 주세요. 문장형 설명을 길게 쓰는 것보다 이 두 가지를 지키는 쪽이 문서의 쓸모를 훨씬 크게 만듭니다.
이미 운영 중인 DB의 명세서를 만들어야 하는데 처음부터 써야 하나요?
쓸 필요 없습니다. DDL을 내보내 ERD 도구에 붙여넣거나 DB에 직접 연결해 가져오면, 컬럼·자료형·제약·코멘트가 그대로 명세서로 정리됩니다. 처음부터 타이핑하는 건 오타만 늘립니다.
정리하면, 필수 항목을 갖춘 양식으로 시작하되 그 양식을 직접 작성하는 단계는 가능한 한 빨리 벗어나는 게 좋습니다. 원본은 스키마에 두고 문서는 생성하는 방식으로 바꾸면, 명세서 때문에 반복되던 작업 대부분을 줄일 수 있습니다.
다음 주제로는 테이블을 어디까지 쪼갤지 정하는 정규화가 자연스럽게 이어집니다. 게시판 예제를 그대로 들고 가서 살펴볼 예정입니다.