데이터 사전 생성기

ErdDocs는 SQL 덤프, Prisma 스키마, 프레임워크 모델로 데이터 사전을 만듭니다. 모든 테이블, 컬럼, 타입, 기본값, 인덱스, 관계를 하나의 참고 문서로 정리합니다. 브라우저에서 인쇄하면 PDF로 저장할 수 있고, 옆에는 ER 다이어그램도 함께 있습니다. 가입도 설치도 필요 없고, 스키마는 브라우저에서 분석됩니다.

내 스키마

CREATE TABLE customers (
    id          bigserial PRIMARY KEY,
    email       varchar(255) NOT NULL UNIQUE,
    full_name   varchar(120),
    created_at  timestamptz  NOT NULL DEFAULT now()
);
COMMENT ON TABLE customers IS '가입한 고객; 한 사람당 한 행';
COMMENT ON COLUMN customers.email IS '로그인 이메일, 쇼핑몰 전체에서 고유';

CREATE TABLE products (
    id        bigserial     PRIMARY KEY,
    sku       varchar(40)   NOT NULL UNIQUE,
    title     varchar(200)  NOT NULL,
    price     numeric(10,2) NOT NULL,
    stock     int           NOT NULL DEFAULT 0
);
COMMENT ON TABLE products IS '상품 카탈로그; 삭제된 상품도 SKU를 유지';
COMMENT ON COLUMN products.stock IS '재고 수량, 창고 연동으로 갱신';

CREATE TABLE orders (
    id           bigserial     PRIMARY KEY,
    customer_id  bigint        NOT NULL REFERENCES customers(id),
    status       varchar(20)   NOT NULL DEFAULT 'pending',
    total        numeric(10,2) NOT NULL,
    placed_at    timestamptz   NOT NULL DEFAULT now()
);
COMMENT ON COLUMN orders.status IS 'pending -> paid -> shipped -> done, 또는 cancelled';

CREATE TABLE order_items (
    order_id    bigint        NOT NULL REFERENCES orders(id),
    product_id  bigint        NOT NULL REFERENCES products(id),
    qty         int           NOT NULL,
    unit_price  numeric(10,2) NOT NULL,
    PRIMARY KEY (order_id, product_id)
);
COMMENT ON TABLE order_items IS '주문 항목; 단가는 구매 시점에 고정';

CREATE TABLE shipments (
    id         bigserial   PRIMARY KEY,
    order_id   bigint      NOT NULL REFERENCES orders(id),
    carrier    varchar(60) NOT NULL,
    tracking   varchar(80),
    shipped_at timestamptz
);

CREATE INDEX idx_orders_customer ON orders(customer_id);
CREATE INDEX idx_shipments_order ON shipments(order_id);

CREATE TABLE customers (
    id          bigserial PRIMARY KEY,
    email       varchar(255) NOT NULL UNIQUE,
    full_name   varchar(120),
    created_at  timestamptz  NOT NULL DEFAULT now()
);
COMMENT ON TABLE customers IS '가입한 고객; 한 사람당 한 행';
COMMENT ON COLUMN customers.email IS '로그인 이메일, 쇼핑몰 전체에서 고유';

CREATE TABLE products (
    id        bigserial     PRIMARY KEY,
    sku       varchar(40)   NOT NULL UNIQUE,
    title     varchar(200)  NOT NULL,
    price     numeric(10,2) NOT NULL,
    stock     int           NOT NULL DEFAULT 0
);
COMMENT ON TABLE products IS '상품 카탈로그; 삭제된 상품도 SKU를 유지';
COMMENT ON COLUMN products.stock IS '재고 수량, 창고 연동으로 갱신';

CREATE TABLE orders (
    id           bigserial     PRIMARY KEY,
    customer_id  bigint        NOT NULL REFERENCES customers(id),
    status       varchar(20)   NOT NULL DEFAULT 'pending',
    total        numeric(10,2) NOT NULL,
    placed_at    timestamptz   NOT NULL DEFAULT now()
);
COMMENT ON COLUMN orders.status IS 'pending -> paid -> shipped -> done, 또는 cancelled';

CREATE TABLE order_items (
    order_id    bigint        NOT NULL REFERENCES orders(id),
    product_id  bigint        NOT NULL REFERENCES products(id),
    qty         int           NOT NULL,
    unit_price  numeric(10,2) NOT NULL,
    PRIMARY KEY (order_id, product_id)
);
COMMENT ON TABLE order_items IS '주문 항목; 단가는 구매 시점에 고정';

CREATE TABLE shipments (
    id         bigserial   PRIMARY KEY,
    order_id   bigint      NOT NULL REFERENCES orders(id),
    carrier    varchar(60) NOT NULL,
    tracking   varchar(80),
    shipped_at timestamptz
);

CREATE INDEX idx_orders_customer ON orders(customer_id);
CREATE INDEX idx_shipments_order ON shipments(order_id);

Your diagram appears here.

아래 스키마에는 한국어 주석이 들어 있습니다. 「데이터 사전」 탭으로 바꾸면 주석이 설명 열에 나옵니다.

데이터베이스에서 데이터 사전까지 세 단계

01스키마를 내보냅니다. PostgreSQL은 pg_dump --schema-only mydb > schema.sql, MySQL은 mysqldump --no-data mydb > schema.sql 명령을 씁니다. Prisma라면 schema.prisma 파일을 그대로 쓰면 됩니다.
02위에 붙여 넣거나 파일을 패널에 끌어다 놓습니다. 스키마를 읽는 동안 데이터 사전이 나타납니다.
03PDF로 저장 버튼을 누르면 브라우저의 인쇄 대화 상자가 문서를 만듭니다. 이때도 서버에는 아무것도 가지 않습니다.

설명은 스키마에서 옵니다

데이터베이스에는 설명을 적을 자리가 이미 있지만, 거기 적은 설명이 문서로 정리되는 일은 드뭅니다. PostgreSQL의 COMMENT ON TABLE과 COMMENT ON COLUMN, MySQL의 COMMENT '설명' 절, Prisma의 /// 주석이 「설명」 열에 들어갑니다. 스키마에 주석이 없으면 이 열은 아예 나타나지 않아, 빈칸이 가득한 문서가 되지 않습니다.

PostgreSQL: COMMENT ON TABLE orders IS '…' 문과 COMMENT ON COLUMN orders.status IS '…' 문. pg_dump가 스키마와 함께 자동으로 내보냅니다.
MySQL: CREATE TABLE 문 안에서 컬럼과 테이블에 붙이는 인라인 COMMENT '…' 절. mysqldump가 그대로 남깁니다.
Prisma: 모델과 필드 위에 쓴 /// 문서 주석이 데이터 사전에 설명으로 들어갑니다.

나머지는 모두 DDL 자체에서 읽습니다. 적힌 그대로의 타입, NULL 허용 여부, 기본값, 키, 인덱스, 그리고 부모 테이블 아래로 접어 넣은 파티션입니다. 외래 키를 하나도 선언하지 않는 덤프도 있습니다(Rails와 Django는 거의 선언하지 않습니다). 그럴 때는 컬럼 이름 규칙으로 관계를 되살리고 그렇게 했다고 표시합니다. 그래서 감사하는 사람은 선언된 키와 추정한 키를 언제든 구분할 수 있습니다.

누가 데이터 사전을 요구하나요

감사와 컴플라이언스. 「데이터 사전을 보내 주세요」는 흔한 요청입니다. ErdDocs는 붙여 넣은 스키마 덤프로 몇 분 만에 답합니다. 운영 중인 데이터베이스를 보며 손으로 만들면 며칠이 걸립니다.
고객 인수인계. 에이전시는 문서와 함께 프로젝트를 마무리합니다. ErdDocs는 그 결과물을 고객이 인쇄해 보관할 수 있는 문서로 만듭니다.
온보딩. 새로 온 엔지니어는 information_schema를 테이블마다 뒤지는 대신 문서 하나를 읽습니다.

데이터 사전이란

데이터베이스를 테이블별로 설명하는 문서입니다. 각 필드의 이름과 타입, NULL 허용 여부, 기본값, 기본 키와 외래 키, 인덱스, 무엇을 저장하는지에 대한 설명이 들어갑니다. 과제와 프로젝트, 감사, 고객에게 시스템을 넘길 때 요구됩니다.

엑셀이나 워드 템플릿보다 나은 점

템플릿은 손으로 채우기 때문에 누군가 테이블을 바꾸는 순간 데이터베이스와 어긋납니다. 여기서는 덤프를 다시 붙여 넣기만 하면 데이터 사전이 최신으로 돌아옵니다. 그러니 납품할 때마다 다시 만들 수 있습니다.

자주 묻는 질문

생성된 데이터 사전에는 무엇이 들어 있나요?

ErdDocs는 모든 테이블을 설명합니다. 테이블마다 선언된 그대로의 데이터 타입, NULL 허용 여부, 기본값과 함께 컬럼을 나열합니다. 기본 키와 외래 키(가리키는 컬럼 포함), 고유 제약, 인덱스, 모든 관계의 양방향도 더합니다. 스키마의 테이블 주석과 컬럼 주석은 설명이 됩니다. 파티션 테이블은 한 번만 나오고, 그 아래에 파티션 이름이 붙습니다.

이미 있는 데이터베이스로 데이터 사전을 만들려면?

먼저 스키마를 SQL로 내보냅니다(PostgreSQL은 pg_dump --schema-only, MySQL은 mysqldump --no-data). 위에 붙여 넣은 뒤 「데이터 사전」 보기로 바꿉니다. 브라우저에서 페이지를 인쇄하면 PDF가 됩니다. 아무것도 설치하지 않으며, SQL은 컴퓨터 밖으로 나가지 않습니다.

설명은 어떻게 데이터 사전에 들어가나요?

스키마 자체에서 들어갑니다. PostgreSQL의 COMMENT ON TABLE 문과 COMMENT ON COLUMN 문, MySQL의 인라인 COMMENT '텍스트' 절, Prisma의 /// 문서 주석이 모두 「설명」 열에 들어갑니다. 주석이 없는 스키마라면 ErdDocs는 설명 열을 빈 채로 인쇄하지 않고 아예 뺍니다.

무료인가요?

다이어그램은 테이블 25개까지 무료로 그려집니다. 데이터 사전은 가장 많이 연결된 테이블 3개를 모두 설명합니다. 그다음 테이블들은 원래 자리에 이름만 있는 틀로 나오고, 나머지는 개수만 표시됩니다. 그래서 받게 될 문서를 그대로 확인할 수 있습니다. 한 번 9달러를 결제하면 데이터 사전 전체와 ERD 전체가 열립니다. 구독도, 갱신도, 계정도 없습니다.

스키마가 어딘가로 업로드되나요?

아니요. 분석, 다이어그램, 데이터 사전은 모두 브라우저에서 만들어지고, PDF도 브라우저가 인쇄할 때 직접 만듭니다. 업로드할 서버가 아예 없으니, 스키마가 서버에 닿을 일도 없습니다.