다른 방언이 명시되지 않는 한 SQL 예제는 PostgreSQL을 사용합니다. 짧은 코드 조각은 참조된 테이블이 이미 존재한다고 가정합니다. 적용하기 전에 대상 데이터베이스에서 DDL을 검증하세요.
데이터베이스 문서화가 실패하는 이유
데이터베이스 문서는 스키마와 별도로 작성되기 때문에 종종 낡은 정보가 됩니다. 누군가 첫 번째 디자인 스프린트 중에 다이어그램을 만들고, 6개월 동안 데이터베이스가 변경되면 문서는 어느새 잘못된 정보를 제공하게 됩니다.
더 나은 접근 방식은 문서를 SQL 소스 가까이에 유지하는 것입니다. DDL에서 다이어그램을 생성하고, 테이블과 관계에 대한 짧은 설명을 추가하며, 스키마가 변경될 때마다 문서를 업데이트하세요.
스키마 문서에 포함할 내용
유용한 데이터베이스 문서는 개발자가 기능을 구축하고 프로덕션 데이터를 디버깅하는 동안 실제로 묻는 질문에 답합니다.
- 하나의 ERD. 테이블, 기본 키, 외래 키 및 주요 관계 경로를 표시합니다.
- 테이블 용도 메모. 각 주요 테이블이 존재하는 이유와 어떤 기능이 이를 소유하는지 설명하십시오.
- 관계 규칙. 카디널리티, 선택적 관계 및 연쇄 동작을 명시하세요.
- 중요한 제약 조건. SQL에 의해 강제되는 고유 키, 체크, 열거형(enum) 값 및 비즈니스 규칙을 문서화하십시오.
- 마이그레이션 컨텍스트. 스키마 변경 사항을 그 이면의 기능, 버그 수정 또는 운영상의 이유와 연결하십시오.
문서 블록 예시
가벼운 문서 항목은 SQL을 평이한 언어의 메모와 결합할 수 있습니다.
CREATE TABLE accounts (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
name TEXT NOT NULL
);
CREATE TABLE invoices (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
account_id BIGINT NOT NULL REFERENCES accounts (id),
status VARCHAR(30) NOT NULL DEFAULT 'draft',
total NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
due_date DATE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE invoice_payments (
id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
invoice_id BIGINT NOT NULL REFERENCES invoices (id) ON DELETE CASCADE,
amount NUMERIC(12, 2) NOT NULL CHECK (amount > 0),
paid_at TIMESTAMPTZ NOT NULL DEFAULT now()
);문서 노트에는 다음과 같이 기재될 수 있습니다: 계정에는 여러 개의 송장이 있고, 송장에는 여러 개의 결제 기록이 있으며, 테스트 송장이 삭제되면 결제 행이 삭제됩니다. 감사 요구 사항이 있는 운영 시스템에서는 연쇄 삭제(cascading deletes)를 제한된 삭제(restricted deletes) 및 아카이브 기록으로 대체할 수 있습니다.
실용적인 문서화 워크플로우
문서를 작성하는 것이 전업 업무가 되지 않으면서도 문서를 유용하게 유지하는 워크플로우입니다.
- SQL 스키마로 시작하여 다음에서 ERD를 생성하세요. Erd Go 편집기.
- 다이어그램을 내보내기 하거나, 로그인하여 저장한 후 스키마가 공개 액세스에 적합한 경우 읽기 전용 공개 링크를 공유하십시오. 비공개 문서에는 이미지 내보내기를 사용하십시오.
- 각 중요한 테이블 클러스터(auth, billing, orders, content, audit 또는 reporting)에 대해 짧은 단락 하나를 추가하세요.
- 마이그레이션 중에 업데이트된 SQL에서 ERD를 다시 생성하여 문서에 변경 사항이 반영되도록 하세요.
- 구문 예제를 다음 항목과 동기화된 상태로 유지하십시오: Erd Go DDL 문서화 미래의 기여자가 다이어그램을 재현할 수 있도록 합니다.
목표는 완벽한 백과사전이 아닙니다. 목표는 사람들이 데이터베이스를 빠르게 이해하고 읽고 있는 내용을 신뢰할 수 있도록 돕는 살아있는 지도입니다.



