กลับไปที่คู่มือทั้งหมด
การออกแบบฐานข้อมูล··อ่าน 3 นาที

เอกสารฐานข้อมูล: ใช้ ERD อธิบายสคีมา SQL

จัดทำเอกสารสคีมาฐานข้อมูลด้วย ERD ตัวอย่าง SQL บันทึกความสัมพันธ์ และบริบทการย้ายข้อมูล เพื่อให้ทีมเข้าใจโมเดลข้อมูลได้เร็วขึ้น

แผนภาพลูกค้าต่อคำสั่งซื้อพร้อมบันทึกอธิบายคีย์นอกและกฎทางธุรกิจ
ในคู่มือนี้
  1. ทำไมเอกสารประกอบฐานข้อมูลถึงล้มเหลว
  2. สิ่งที่ควรระบุไว้ในเอกสารประกอบสคีมา
  3. ตัวอย่างบล็อกเอกสารประกอบ
  4. ขั้นตอนการทำเอกสารเชิงปฏิบัติ
  5. ข้อมูลอ้างอิงและการอ่านเพิ่มเติม

ตัวอย่าง SQL จะใช้ PostgreSQL เว้นแต่จะระบุภาษาอื่นไว้ ตัวอย่างสั้นๆ สมมติว่าตารางที่อ้างถึงมีอยู่แล้ว โปรดตรวจสอบความถูกต้องของ DDL ในฐานข้อมูลเป้าหมายของคุณก่อนนำไปใช้งาน

ทำไมเอกสารประกอบฐานข้อมูลถึงล้มเหลว

เอกสารประกอบฐานข้อมูลมักจะล้าสมัยเนื่องจากถูกเขียนแยกจากสคีมา มีคนสร้างแผนภาพในช่วงสปรินต์การออกแบบแรก จากนั้นฐานข้อมูลก็เปลี่ยนไปเป็นเวลาหกเดือน และเอกสารประกอบก็กลายเป็นข้อมูลที่ทำให้เข้าใจผิดไปอย่างเงียบๆ

แนวทางที่ดีกว่าคือการเก็บเอกสารไว้ใกล้กับแหล่งข้อมูล SQL สร้างแผนภาพจาก DDL เพิ่มคำอธิบายสั้นๆ สำหรับตารางและความสัมพันธ์ และอัปเดตเอกสารทุกครั้งที่มีการเปลี่ยนแปลงสคีมา

สคีมา SQL, แผนภาพ ERD, บันทึกความสัมพันธ์ และบริบทการย้ายข้อมูลที่รวมอยู่ในเอกสารประกอบ
เอกสารฐานข้อมูลที่ดีจะจับคู่แหล่งที่มา SQL กับแผนภาพคลาส (ERD) และบันทึกความสัมพันธ์สั้นๆ เพื่อให้เอกสารใช้งานได้จริง

สิ่งที่ควรระบุไว้ในเอกสารประกอบสคีมา

เอกสารประกอบฐานข้อมูลที่มีประโยชน์จะตอบคำถามที่นักพัฒนาถามจริงในขณะสร้างฟีเจอร์และแก้ไขข้อบกพร่องของข้อมูลในการผลิต

  • ERD หนึ่งชุด แสดงตาราง คีย์หลัก คีย์นอก และเส้นทางความสัมพันธ์หลัก
  • บันทึกวัตถุประสงค์ของตาราง อธิบายว่าทำไมแต่ละตารางหลักถึงมีอยู่และฟีเจอร์ใดเป็นเจ้าของ
  • กฎของความสัมพันธ์ ระบุความเป็นคาร์ดินัลลิตี้ ความสัมพันธ์ที่เป็นทางเลือก และการดำเนินการแบบเรียงซ้อน
  • ข้อจำกัดที่สำคัญ จัดทำเอกสารคีย์เฉพาะ, การตรวจสอบ, ค่า enum และกฎทางธุรกิจที่บังคับใช้โดย SQL
  • บริบทการย้ายข้อมูล เชื่อมโยงการเปลี่ยนแปลง Schema เข้ากับฟีเจอร์ การแก้ไขข้อผิดพลาด หรือเหตุผลด้านการปฏิบัติงานที่อยู่เบื้องหลังการเปลี่ยนแปลงนั้น

ตัวอย่างบล็อกเอกสารประกอบ

รายการเอกสารแบบน้ำหนักเบาสามารถจับคู่ 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()
);

บันทึกเอกสารอาจระบุว่า: บัญชีหนึ่งมีใบแจ้งหนี้หลายใบ, ใบแจ้งหนี้มีบันทึกการชำระเงินหลายรายการ และแถวการชำระเงินจะถูกลบหากใบแจ้งหนี้ทดสอบถูกลบ ในระบบการผลิตที่มีข้อกำหนดด้านการตรวจสอบ คุณอาจแทนที่การลบแบบต่อเนื่องด้วยการลบแบบจำกัดและบันทึกถาวร

ขั้นตอนการทำเอกสารเชิงปฏิบัติ

นี่คือเวิร์กโฟลว์ที่ช่วยให้เอกสารมีประโยชน์โดยไม่ต้องเปลี่ยนการทำเอกสารให้เป็นงานเต็มเวลา

  • เริ่มต้นด้วยสคีมา SQL และสร้างแผนภาพคลาส (ERD) ใน ตัวแก้ไข Erd Go.
  • ส่งออกแผนภาพหรือลงชื่อเข้าใช้ บันทึก และแชร์ลิงก์สาธารณะแบบอ่านอย่างเดียวเมื่อสคีมาเหมาะสมสำหรับการเข้าถึงสาธารณะ ใช้การส่งออกรูปภาพสำหรับเอกสารส่วนตัว
  • เพิ่มย่อหน้าสั้นๆ หนึ่งย่อหน้าสำหรับกลุ่มตารางที่สำคัญแต่ละกลุ่ม: auth, billing, orders, content, audit หรือ reporting
  • สร้าง ERD ใหม่จาก SQL ที่อัปเดตในระหว่างการย้ายข้อมูล เพื่อให้เอกสารประกอบสะท้อนถึงสิ่งที่เปลี่ยนแปลงไป
  • รักษาตัวอย่างไวยากรณ์ให้ตรงกับ เอกสาร DDL ของ Erd Go เพื่อให้ผู้ร่วมพัฒนาในอนาคตสามารถสร้างแผนภาพขึ้นใหม่ได้

เป้าหมายไม่ใช่สารานุกรมที่สมบูรณ์แบบ เป้าหมายคือแผนที่ที่มีชีวิตซึ่งช่วยให้ผู้คนเข้าใจฐานข้อมูลได้อย่างรวดเร็วและเชื่อมั่นในสิ่งที่พวกเขากำลังอ่าน

ข้อมูลอ้างอิงและการอ่านเพิ่มเติม

โพสต์เพิ่มเติม