Ch10. 물리적 모델링 - 테이블 정의서

물리적 모델링의 최종 산출물 중 하나는 바로 테이블 정의서(Table Definition Document)다. 테이블 정의서는 데이터베이스의 각 테이블과 컬럼이 무엇을 의미하고, 어떤 규칙을 가지고 있는지 상세하게 설명하는 "설계 명세서"와 같다.

 

테이블 정의서, 왜 필요한가?

문제 상황: 당신은 새로운 프로젝트에 투입된 개발자다. 데이터베이스 스키마를 파악하기 위해 DDL(CREATE TABLE ...) 코드를 열어보았다.

CREATE TABLE order_item (
    oi_id BIGINT NOT NULL AUTO_INCREMENT,
    o_id BIGINT NOT NULL,
    p_id BIGINT NOT NULL,
    price INT NOT NULL,
    qty INT NOT NULL,
    PRIMARY KEY (oi_id)
);

• 이 DDL만 보고 아래 질문에 바로 답할 수 없다.
  • order_item 테이블은 정확히 어떤 데이터를 저장하는 테이블인가?
  • "oi_id", "o_id", "p_id"는 각각 무엇의 ID를 의미하는가?
  • "price"는 상품의 현재 가격인가, 아니면 주문 당시의 가격인가?
  • "qty"는 무슨 수량을 의미하는가?

아마 대부분의 사람은 정확히 답하기 어려울 것이다. 이처럼 DDL은 데이터베이스의 물리적인 구조는 알려주지만, 각 요소가 담고 있는 비즈니스적 의미나 숨겨진 규칙까지 설명해주지는 않는다. 이러한 정보의 공백을 메워주는 것이 바로 테이블 정의서다. 잘 작성된 테이블 정의서는 DDL만으로는 알 수 없는 풍부한 맥락을 제공하여, 개발자나 데이터 분석가가 데이터의 구조와 의미를 명확하게 이해할 수 있도록 돕는다.

 

테이블 정의서의 역할

• 의사소통의 중심: 개발자, DBA, 기획자, 데이터 분석가 등 프로젝트에 참여하는 모든 사람이 데이터에 대해 동일한 이해를 갖도록 돕는 "공통 언어" 역할을 한다.
  • "이 컬럼은 어떤 의미인가요?"와 같은 불필요한 질문과 오해를 줄여준다.
• 유지보수의 핵심: 시간이 흘러 시스템이 복잡해지고 담당자가 바뀌더라도, 테이블 정의서만 보면 누구나 데이터 구조를 빠르게 파악하고 유지보수 작업을 수행할 수 있다.
• 데이터 품질 보증: 각 컬럼의 제약 조건, 기본값, 허용되는 값의 범위 등을 명시함으로써 데이터의 일관성과 품질을 유지하는 데 기여한다.
• 데이터베이스의 청사진: 이 문서만 보면 누구나 데이터베이스의 전체 구조를 이해하고, 테이블을 생성(CREATE) 할 수 있어야 한다.
• 개발의 가이드: 개발자는 이 문서를 보고 테이블과 컬럼의 이름을 정확히 사용하여 SQL을 작성하고, 애플리케이션 코드를 구현한다

테이블 정의서의 구성 요소

• 테이블 정보
  • 테이블 한글명 (논리명): 테이블이 무엇을 나타내는지 비즈니스 용어로 설명한다. (예: 회원)
  • 테이블 영문명 (물리명): 실제 데이터베이스에 생성되는 테이블의 이름이다. (예: member)
  • 테이블 설명: 테이블의 역할과 목적을 상세하게 기술한다.
• 컬럼 정보
  • No: 컬럼의 순번
  • 컬럼 한글명 (논리명): 컬럼의 비즈니스적 의미를 설명한다. (예: 회원 ID, 로그인 ID)
  • 컬럼 영문명 (물리명): 실제 테이블에 생성되는 컬럼의 이름이다. (예: member_id, login_id)
  • 데이터 타입: VARCHAR(100), BIGINT, DATETIME 등 컬럼의 데이터 타입을 명시한다.
  • 제약 조건 (Key): 기본 키(PK), 외래 키(FK), 고유 키(Unique) 여부를 표시한다.
  • NULL 허용 여부: "NOT NULL"(필수값) 또는 "NULL"(선택값) 여부를 표시한다.
  • 기본값 (Default): 컬럼에 기본으로 설정된 값이 있다면 명시한다.
  • 비고 (설명): 컬럼에 대한 추가적인 설명이나 규칙을 자유롭게 기술한다. (예: "비밀번호는 암호화해서 저장", "주문 당시의 가격을 기록")

쇼핑몰 테이블 정의서 예시

테이블 정의: member

No	컬럼 한글명	컬럼 영문명	데이터 타입	제약 조건	기본값	비고
1	회원 ID	member_id	BIGINT	PK	AUTO_INCREMENT	회원의 고유 식별자 (대리 키)
2	로그인 ID	login_id	VARCHAR(50)			회원이 로그인 시 사용하는 ID
3	비밀번호	password	VARCHAR(255)			비밀번호(반드시 암호화해서 저장)
4	회원명	member_name	VARCHAR(50)			회원의 실명
5	이메일	email	VARCHAR(100)	UQ		회원 인증 및 소통을 위한 이메일
6	주소	addr	VARCHAR(255)	NULL		상품 배송을 위한 주소
7	가입일	created_at	DATETIME		CURRENT_TIMESTAMP	회원 가입 시점
8	수정일	updated_at	DATETIME		CURRENT_TIMESTAMP	데이터 수정 시 자동 갱신

• 표를 간결하게 표현하기 위해 NULL 허용을 제약조건에 함께 포함했다.
  • NULL 허용은 별도의 컬럼으로 분리하는 것이 좋다.
• "addr" 축약어 합의

이처럼 테이블 정의서를 작성하면, DDL만 봤을 때는 알기 어려웠던 각 컬럼의 정확한 의미와 규칙(예: 비밀번호는 암호화해서 저장해야 함)을 명확하게 알 수 있다.

실무 팁

테이블 정의서는 한 번 만들고 끝나는 문서가 아니다. 데이터베이스의 스키마가 변경될 때마다 반드시 함께 업데이트되어야 하는 "살아있는 문서(Living Document)"다. 실무에서는 Excel, Google Sheets, 또는 Confluence나 Notion과 같은 위키 시스템을 사용하여 테이블 정의서를 작성하고 팀원들과 공유하며 관리한다.