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.
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.



