테이블 명세서 양식이 필요해서 오셨을 겁니다. 바로 받으세요.
회원가입도 이메일 입력도 없습니다. 표지부터 개정 이력까지 일곱 장의 시트로 구성된 엑셀 파일이고, 실무에서 검수받는 명세서에 필요한 요소를 전부 담았습니다. 아래에는 각 시트에 뭐가 들어 있는지, 그리고 이 양식을 왜 이렇게 짰는지를 적어 두었습니다. 마지막에는 이 파일을 아예 자동으로 만드는 방법도 있으니, 급한 분은 양식만 받아 가시고 시간 되실 때 그 부분만 다시 읽으셔도 됩니다.
양식 구성 (시트 7장)
표지. 프로젝트명, DBMS, 스키마 기준일, 작성자, 문서 버전을 적는 칸과 테이블 목록 표가 있습니다. 기준일 칸을 표지에 둔 건 의도한 배치입니다. 어느 시점의 DB를 옮긴 문서인지 알 수 없는 명세서는 검수에서 가장 먼저 지적받기 때문입니다. 목록의 예시 행에는 해당 시트로 이동하는 링크를 걸어 두었습니다.
작성 가이드. 칸별 작성 요령과 키 약어(PK·FK·UK·IX) 정의, 자주 하는 실수 세 가지를 한 장에 정리했습니다. 팀원들과 공유해 작성 방법을 통일하면 문서 품질이 고르게 나옵니다.
작성 예시 2장. FK가 없는 단순한 테이블(members)과 FK·인덱스가 있는 테이블(posts)을 각각 실제로 작성해 놓았습니다. 예시 데이터는 연노랑 배경으로 표시해서 실제 작성분과 구분됩니다. 외래키 부록에는 참조 대상과 삭제 시·갱신 시 동작까지 적는 칸이 있습니다.
빈 양식. 테이블 하나당 이 시트를 복사해서 작성하면 됩니다. 컬럼 20행에 NULL 칸은 Y/N, 키 칸은 PK·FK·UK·IX 드롭다운을 넣어 두었고(직접 입력도 됩니다), 헤더 행은 틀 고정이 되어 있어 스크롤해도 항목명이 보입니다.
공통 코드 정의. status 같은 코드값 컬럼의 값 의미(1=활성, 2=휴면)를 한 시트에 모아 관리합니다. 컬럼 설명 칸마다 코드값을 반복해서 적지 않아도 됩니다.
개정 이력. 문서를 고칠 때마다 버전·일자·변경 내용을 한 줄씩 남기는 표입니다. 검수자가 "지난번 제출본과 뭐가 달라졌나"를 물을 때 여기를 보여주면 됩니다.
인쇄 설정도 잡아 두었습니다. 시트마다 A4 기준으로 폭이 맞게 출력되도록 해 두어서, 종이 검수가 필요한 현장에서도 그대로 인쇄하면 됩니다.
양식을 이렇게 짠 이유
시중에 도는 명세서 양식은 칸이 너무 많거나 너무 적습니다. 이 양식은 검수하는 사람이 실제로 확인하는 항목만 남기고, 관리가 안 되는 칸은 뺐습니다.
작성자·수정일 칸을 컬럼마다 두지 않았습니다. 이 칸이 끝까지 관리되는 현장을 본 적이 거의 없습니다. 오래된 관리 정보가 남아 있으면 오히려 문서 전체를 의심하게 만들기 때문에, 문서 단위 정보는 표지에 한 번만 적게 했습니다.
FK 부록을 별도 표로 뺐습니다. 컬럼 행의 키 칸에 FK라고만 적힌 명세서가 많은데, 검수자가 정말 알고 싶은 건 어느 테이블의 어느 컬럼을 참조하는지, 부모 행이 지워지면 어떻게 되는지입니다. 이 두 가지를 적을 자리가 없으면 명세서가 관계를 설명하지 못합니다. 관계를 다이어그램의 기호로 읽는 방법은 ERD 표기법 총정리에서 다룹니다.
인덱스 부록에 비고 칸을 넣었습니다. 인덱스는 이름과 컬럼만 나열하면 왜 만들었는지가 남지 않습니다. "회원별 글 목록 조회용" 같은 한 줄이 있어야 다음 담당자가 함부로 지우지 않습니다.
코드값은 별도 시트로 뺐습니다. 같은 코드값(회원 상태 등)을 여러 테이블의 설명 칸에 반복해서 적다 보면 한 곳만 고쳐지는 사고가 납니다. 공통 코드 정의 시트에 한 번만 적고, 컬럼 설명에는 코드 그룹명만 남기는 구조입니다.
항목별 작성 요령은 테이블 명세서 작성법에 따로 정리되어 있습니다. NULL 칸을 어떻게 읽어야 하는지, 코드값과 단위를 왜 반드시 적어야 하는지까지 다루니 처음 써 보신다면 함께 읽는 걸 권합니다.
작성 전에 정할 것 두 가지
기준일부터 적으세요. 오늘 날짜가 아니라, 문서에 옮기는 스키마를 확인한 날짜입니다. 기준일이 있으면 나중에 스키마가 바뀌어도 "8월 18일 기준으로는 맞는 문서"로 남습니다.
용어를 하나로 정하세요. 논리명은 기획서와 화면에서 쓰는 말과 맞춥니다. 화면에는 "별명", 명세서에는 "닉네임"으로 적혀 있으면 검수자는 어느 쪽이 맞는지부터 묻게 됩니다.
작성하는 순서
빈 양식을 위에서부터 한 칸씩 작성하는 것보다, 성격이 같은 정보끼리 묶어서 작성하는 쪽이 빠르고 정확합니다.
- 물리 정보부터 한 번에. 컬럼명·자료형·NULL·기본값·키는 전부 DB에 이미 있는 정보입니다. DB 툴에서 테이블 정의(DDL)를 열어 두고 옮겨 적으세요. 기억에 의지해서 적으면 자료형 길이 같은 데서 오타가 나고, 검수에서 실제 DB와 다르다는 지적을 받게 됩니다.
- 논리명과 설명은 그다음에. DB에 없는 정보라 사람이 직접 입력해야 합니다. 기획서와 화면을 옆에 두고 용어를 맞춰 가며 적습니다. 코드값 컬럼(status 같은)은 설명 칸에 값의 의미를 꼭 나열하세요. 1=활성, 2=휴면 같은 식으로요.
- FK·인덱스 부록은 마지막에. 컬럼 정의가 끝난 뒤 관계만 따로 모아 적으면 빠뜨린 FK를 찾기 쉽습니다.
해 보면 1번과 3번은 단순히 옮겨 적는 작업이라는 걸 알게 됩니다. 바로 그 부분이 아래에서 이야기할 자동화가 대신할 수 있는 부분입니다.
같은 문서를 자동으로 만드는 방법
이 파일을 작성하는 일은 테이블 열 개만 넘어가도 시간이 꽤 걸립니다. 더 큰 문제는 그 뒤입니다. 스키마가 바뀔 때마다 엑셀을 같이 고쳐야 하고, 한 번이라도 밀리면 문서와 DB가 어긋나기 시작합니다.
그래서 이 양식과 같은 구성의 문서를 자동으로 만드는 방법도 있습니다. 원리는 단순합니다. 명세서에 들어가는 정보 대부분(컬럼명·자료형·NULL·기본값·키)은 이미 DDL 안에 있고, 없는 건 논리명과 설명뿐인데 그건 DDL의 COMMENT로 채울 수 있습니다.
CREATE TABLE posts (
id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '게시글 번호',
member_id BIGINT NOT NULL COMMENT '작성 회원',
title VARCHAR(200) NOT NULL COMMENT '제목',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '작성 시각',
CONSTRAINT fk_posts_member FOREIGN KEY (member_id) REFERENCES members (id)
) COMMENT='게시글';이런 DDL을 WorksCove ERD에 붙여넣으면 ERD와 함께 위 양식 구성 그대로의 명세서가 전체 테이블 분량으로 만들어지고, 검수 제출용 엑셀로도 내보낼 수 있습니다. DDL을 뽑는 방법은 SQL to ERD의 1단계에 DBMS별로 정리되어 있습니다. mysqldump 한 줄이면 됩니다.
스키마가 바뀌면 문서를 고치는 게 아니라 다시 생성하면 되니, 명세서를 최신으로 유지하는 작업 자체가 없어집니다.
자주 묻는 질문
이 양식 그대로 검수에 제출해도 되나요?
필수 항목(물리명·논리명·자료형·NULL·기본값·키·설명)과 FK·인덱스 부록, 표지의 기준일까지 갖춘 구성이라 대부분의 현장에서 그대로 쓸 수 있습니다. 발주처가 별도 표준 양식을 지정하는 경우만 그쪽 양식으로 옮기면 되는데, 항목 자체는 거의 같아서 열 순서만 맞추는 수준입니다.
테이블이 수십 개인데 시트를 하나씩 복사해야 하나요?
빈 양식 시트를 복사해 쓰는 구조라 테이블 수만큼 반복 작업이 됩니다. 솔직히 그 단계부터는 직접 만들 일이 아닙니다. DDL을 ERD 도구에 붙여넣으면 전체 테이블의 명세서가 한 번에 생성되고 엑셀로도 내보낼 수 있으니, 테이블이 열 개를 넘어가면 자동 생성을 권합니다.
운영 중인 DB에 코멘트가 없어서 논리명 칸을 채울 수가 없습니다.
흔한 상황입니다. 논리명은 DB 어디에도 없고 담당자 기억에만 있는 정보라, 이번 기회에 DDL의 COMMENT로 옮겨 두는 걸 권합니다. 한 번 코멘트로 넣어 두면 다음부터는 명세서를 만들 때마다 자동으로 들어갑니다.
테이블 명세서와 테이블 정의서 양식이 따로 있나요?
따로 없습니다. 명세서·정의서·스키마 정의서는 현장마다 부르는 이름이 다를 뿐 같은 문서라, 이 양식을 그대로 쓰면 됩니다. 문서 제목 칸의 이름만 발주처가 쓰는 용어로 바꿔 주세요.
다운로드 링크를 다시 남깁니다. 테이블 명세서 엑셀 양식 내려받기 (.xlsx)
직접 작성해 보시고 시간이 많이 소요된다면, 그때 자동 생성 방법을 검토해 보세요.