ตัวอย่าง SQL จะใช้ PostgreSQL เว้นแต่จะระบุภาษาอื่นไว้ ตัวอย่างสั้นๆ สมมติว่าตารางที่อ้างถึงมีอยู่แล้ว โปรดตรวจสอบความถูกต้องของ DDL ในฐานข้อมูลเป้าหมายของคุณก่อนนำไปใช้งาน
ทำไมเอกสารประกอบฐานข้อมูลถึงล้มเหลว
เอกสารประกอบฐานข้อมูลมักจะล้าสมัยเนื่องจากถูกเขียนแยกจากสคีมา มีคนสร้างแผนภาพในช่วงสปรินต์การออกแบบแรก จากนั้นฐานข้อมูลก็เปลี่ยนไปเป็นเวลาหกเดือน และเอกสารประกอบก็กลายเป็นข้อมูลที่ทำให้เข้าใจผิดไปอย่างเงียบๆ
แนวทางที่ดีกว่าคือการเก็บเอกสารไว้ใกล้กับแหล่งข้อมูล SQL สร้างแผนภาพจาก DDL เพิ่มคำอธิบายสั้นๆ สำหรับตารางและความสัมพันธ์ และอัปเดตเอกสารทุกครั้งที่มีการเปลี่ยนแปลงสคีมา
สิ่งที่ควรระบุไว้ในเอกสารประกอบสคีมา
เอกสารประกอบฐานข้อมูลที่มีประโยชน์จะตอบคำถามที่นักพัฒนาถามจริงในขณะสร้างฟีเจอร์และแก้ไขข้อบกพร่องของข้อมูลในการผลิต
- 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 เพื่อให้ผู้ร่วมพัฒนาในอนาคตสามารถสร้างแผนภาพขึ้นใหม่ได้
เป้าหมายไม่ใช่สารานุกรมที่สมบูรณ์แบบ เป้าหมายคือแผนที่ที่มีชีวิตซึ่งช่วยให้ผู้คนเข้าใจฐานข้อมูลได้อย่างรวดเร็วและเชื่อมั่นในสิ่งที่พวกเขากำลังอ่าน



