Quay lại tất cả hướng dẫn
Thiết kế cơ sở dữ liệu··Đọc trong 3 phút

Tài liệu cơ sở dữ liệu: dùng ERD để giải thích lược đồ SQL

Tài liệu hóa các lược đồ cơ sở dữ liệu với ERD, ví dụ SQL, ghi chú mối quan hệ và ngữ cảnh di chuyển để các nhóm có thể hiểu các mô hình dữ liệu nhanh hơn.

Sơ đồ khách hàng-đến-đơn hàng bên cạnh các ghi chú giải thích khóa ngoại và quy tắc nghiệp vụ
Trong hướng dẫn này
  1. Tại sao tài liệu cơ sở dữ liệu thất bại
  2. Những nội dung cần đưa vào tài liệu lược đồ
  3. Khối tài liệu ví dụ
  4. Quy trình tài liệu thực tế
  5. Tài liệu tham khảo và đọc thêm

Các ví dụ SQL sử dụng PostgreSQL trừ khi một phương ngữ khác được chỉ định. Các đoạn mã ngắn giả định rằng các bảng được tham chiếu đã tồn tại. Hãy xác thực DDL trong cơ sở dữ liệu mục tiêu của bạn trước khi áp dụng nó.

Tại sao tài liệu cơ sở dữ liệu thất bại

Tài liệu cơ sở dữ liệu thường trở nên lỗi thời vì nó được viết tách biệt với lược đồ. Ai đó tạo một sơ đồ trong giai đoạn thiết kế đầu tiên, cơ sở dữ liệu thay đổi trong sáu tháng, và tài liệu lặng lẽ trở nên gây hiểu lầm.

Một cách tiếp cận tốt hơn là giữ tài liệu gần với nguồn SQL. Tạo sơ đồ từ DDL, thêm giải thích ngắn gọn cho các bảng và mối quan hệ, và cập nhật tài liệu bất cứ khi nào lược đồ thay đổi.

Lược đồ SQL, sơ đồ ERD, ghi chú mối quan hệ và ngữ cảnh di chuyển được kết hợp thành tài liệu
Tài liệu cơ sở dữ liệu mạnh mẽ kết hợp nguồn SQL với Sơ đồ lớp (ERD) và các ghi chú mối quan hệ ngắn gọn, để tài liệu luôn thiết thực.

Những nội dung cần đưa vào tài liệu lược đồ

Tài liệu cơ sở dữ liệu hữu ích trả lời các câu hỏi mà các nhà phát triển thực sự đặt ra trong khi xây dựng các tính năng và gỡ lỗi dữ liệu sản xuất.

  • Một Sơ đồ ERD. Hiển thị các bảng, khóa chính, khóa ngoại và các đường dẫn quan hệ chính.
  • Ghi chú mục đích của bảng. Giải thích lý do tại sao mỗi bảng chính tồn tại và tính năng nào sở hữu nó.
  • Các quy tắc quan hệ. Kêu gọi tính chất lực lượng (cardinality), các mối quan hệ tùy chọn và các hành động xếp tầng.
  • Các ràng buộc quan trọng. Tài liệu hóa các khóa duy nhất, kiểm tra, giá trị enum và các quy tắc nghiệp vụ được thực thi bởi SQL.
  • Ngữ cảnh di chuyển. Liên kết các thay đổi lược đồ với tính năng, sửa lỗi hoặc lý do vận hành đằng sau chúng.

Khối tài liệu ví dụ

Một mục tài liệu nhẹ có thể kết hợp SQL với các ghi chú bằng ngôn ngữ đơn giản:

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()
);

Các ghi chú tài liệu có thể nói: một tài khoản có nhiều hóa đơn, hóa đơn có nhiều bản ghi thanh toán và các hàng thanh toán sẽ bị xóa nếu hóa đơn thử nghiệm bị xóa. Trong các hệ thống sản xuất có yêu cầu kiểm toán, bạn có thể thay thế việc xóa theo chuỗi bằng xóa hạn chế và các bản ghi lưu trữ.

Quy trình tài liệu thực tế

Đây là một quy trình làm việc giúp tài liệu luôn hữu ích mà không biến việc viết tài liệu thành một công việc toàn thời gian.

  • Bắt đầu với lược đồ SQL và tạo Sơ đồ lớp (ERD) trong Trình chỉnh sửa Erd Go.
  • Xuất sơ đồ hoặc đăng nhập, lưu nó và chia sẻ liên kết công khai chỉ đọc khi lược đồ phù hợp để truy cập công khai. Sử dụng xuất hình ảnh cho tài liệu riêng tư.
  • Thêm một đoạn văn ngắn cho mỗi cụm bảng quan trọng: auth, billing, orders, content, audit, hoặc reporting.
  • Tạo lại ERD từ SQL đã cập nhật trong quá trình di chuyển để tài liệu phản ánh những gì đã thay đổi.
  • Giữ các ví dụ cú pháp đồng bộ với Tài liệu DDL của Erd Go để những người đóng góp trong tương lai có thể tái tạo sơ đồ.

Mục tiêu không phải là một bách khoa toàn thư hoàn hảo. Mục tiêu là một bản đồ sống động giúp mọi người hiểu cơ sở dữ liệu một cách nhanh chóng và tin tưởng vào những gì họ đang đọc.

Tài liệu tham khảo và đọc thêm

Các bài viết khác