[ORACLE] COMMENT() 구문으로 테이블과 컬럼 설명 문서화하기

[Oracle] COMMENT

 

1. ORACLE COMMENT란?

Oracle에서 COMMENT는 테이블, 칼럼, 뷰 등 객체에 대한 설명을 추가하는 기능입니다. COMMENT 구문은 메타데이터에 정보를 기록하여, 개발자와 DBA가 테이블 구조를 이해하는 데 도움을 줍니다.

2. COMMENT 구문의 기본 문법

COMMENT ON TABLE 테이블명 IS '설명문';
COMMENT ON COLUMN 테이블명.컬럼명 IS '설명문';

예제 1: 테이블에 주석 추가

COMMENT ON TABLE employees IS '사원 기본 정보 테이블';

예제 2: 컬럼에 주석 추가

COMMENT ON COLUMN employees.salary IS '사원의 월급 정보';

3. COMMENT 활용 목적

• 데이터베이스 객체의 의미 명확화
• SQL Developer, TOAD 등의 도구에서 자동 설명 표시
• 개발자 간 협업 시 데이터 구조 이해 보조
• 문서화 비용 절감 및 유지보수 효율 향상

4. COMMENT가 가능한 객체

• TABLE
• COLUMN
• VIEW
• MATERIALIZED VIEW
• OPERATOR
• INDEX (11g 이상 일부 버전부터)

5. COMMENT 변경 및 삭제

기존 주석을 수정하려면 같은 구문을 다시 실행하면 됩니다. 주석을 삭제하려면 NULL을 입력합니다.

예제 3: 주석 수정

COMMENT ON COLUMN employees.salary IS '사원의 연봉';

예제 4: 주석 제거

COMMENT ON COLUMN employees.salary IS NULL;

6. COMMENT 정보 조회 방법

테이블 주석 확인

SELECT * FROM user_tab_comments WHERE table_name = 'EMPLOYEES';

칼럼 주석 확인

SELECT * FROM user_col_comments WHERE table_name = 'EMPLOYEES';

7. 실무 예제: 프로젝트용 테이블 주석 일괄 등록

COMMENT ON TABLE orders IS '고객 주문 내역';
COMMENT ON COLUMN orders.order_id IS '주문 고유 번호';
COMMENT ON COLUMN orders.customer_id IS '고객 ID (외래 키)';
COMMENT ON COLUMN orders.order_date IS '주문일';

8. COMMENT 활용 시 주의사항

• 주석은 데이터 사전에 저장되므로 너무 긴 설명은 피함
• NULL 입력 시 주석이 제거됨
• 다국어 환경에서는 인코딩 문제 발생 가능 (UTF-8 권장)
• 주석 변경 시 별도 권한 필요 없음 (객체 소유자 또는 DBA 권한 필요)

9. COMMENT와 문서화 자동화 도구 연동

• SQL Developer: 주석이 데이터 모델 문서에 자동 포함됨
• ERD 도구 (예: ERWin, DBeaver): COMMENT를 기반으로 필드 설명 출력 가능
• REST API 문서 자동 생성 시 COMMENT 활용 사례 존재

10. COMMENT 관련 시스템 뷰

• USER_TAB_COMMENTS: 현재 사용자 테이블 주석
• USER_COL_COMMENTS: 현재 사용자 칼럼 주석
• ALL_TAB_COMMENTS, ALL_COL_COMMENTS: 접근 가능한 모든 주석
• DBA_TAB_COMMENTS, DBA_COL_COMMENTS: 전체 데이터베이스 주석

11. 결론

Oracle COMMENT는 개발자와 운영자가 테이블 구조를 명확히 이해하고 유지보수 비용을 줄이는 데 필수적인 기능입니다. 간단한 SQL 구문만으로도 풍부한 설명을 데이터베이스에 포함시킬 수 있으며, 이를 통해 협업 품질이 향상되고 시스템의 신뢰성도 증가합니다.

출처

• Oracle 공식 문서: https://docs.oracle.com/en/database/
• Oracle SQL Language Reference
• 오라클 실무 데이터 설계와 문서화 전략 - 김태경 저