العودة إلى جميع الأدلة
تصميم قواعد البيانات··قراءة في 3 دقائق

توثيق قاعدة البيانات: استخدام ERD لشرح مخطط SQL

وثق مخططات قاعدة البيانات باستخدام مخططات ERD وأمثلة SQL وملاحظات العلاقات وسياق الترحيل حتى تتمكن الفرق من فهم نماذج البيانات بشكل أسرع.

مخطط عميل إلى طلب بجانب ملاحظات تشرح المفتاح الأجنبي وقاعدة العمل
في هذا الدليل
  1. لماذا يفشل توثيق قاعدة البيانات؟
  2. ما يجب تضمينه في توثيق المخطط
  3. مثال على كتلة التوثيق
  4. سير عمل توثيق عملي
  5. المراجع والقراءات الإضافية

تستخدم أمثلة SQL لغة PostgreSQL ما لم يتم تسمية لهجة أخرى. يفترض المقتطفات القصيرة أن جداولها المُشار إليها موجودة بالفعل. تحقق من صحة DDL في قاعدة بياناتك المستهدفة قبل تطبيقها.

لماذا يفشل توثيق قاعدة البيانات؟

غالباً ما تصبح وثائق قاعدة البيانات قديمة لأنها تكتب بشكل منفصل عن المخطط. يقوم شخص ما بإنشاء مخطط أثناء دورة التصميم الأولى، وتتغير قاعدة البيانات لمدة ستة أشهر، وتصبح الوثائق مضللة بهدوء.

النهج الأفضل هو إبقاء التوثيق قريبًا من مصدر SQL. قم بتوليد المخططات من DDL، وأضف توضيحات قصيرة للجداول والعلاقات، وقم بتحديث الوثائق كلما تغير المخطط.

مخطط SQL، ومخطط ERD، وملاحظات العلاقات، وسياق الترحيل مجتمعة في وثائق واحدة
توثيق قاعدة البيانات القوي يقرن مصدر SQL بمخطط ERD وملاحظات قصيرة للعلاقات، بحيث يظل التوثيق عملياً.

ما يجب تضمينه في توثيق المخطط

توثيق قاعدة البيانات المفيد يجيب على الأسئلة التي يطرحها المطورون فعليا أثناء بناء الميزات وتصحيح أخطاء بيانات الإنتاج.

  • مخطط ERD. عرض الجداول والمفاتيح الأساسية والمفاتيح الخارجية ومسارات العلاقات الرئيسية.
  • ملاحظات الغرض من الجدول. اشرح سبب وجود كل جدول رئيسي والميزة التي تمتلكه.
  • قواعد العلاقات. توضيح الأساسيات الاختيارية، والعلاقات الاختيارية، والإجراءات المتتالية (cascading).
  • قيود مهمة. وثق المفاتيح الفريدة، والتحققات، وقيم التعداد، وقواعد العمل التي تفرضها SQL.
  • سياق الترحيل. اربط تغييرات المخطط بالميزة، أو إصلاح الأخطاء، أو السبب التشغيلي الكامن وراءها.

مثال على كتلة التوثيق

يمكن لإدخال توثيق خفيف الوزن أن يربط كود 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.
  • قم بتصدير المخطط أو تسجيل الدخول وحفظه ومشاركة رابط عام للقراءة فقط عندما يكون المخطط مناسباً للوصول العام. استخدم تصدير الصور للتوثيق الخاص.
  • أضف فقرة قصيرة واحدة لكل مجموعة جداول هامة: المصادقة، والفواتير، والطلبات، والمحتوى، والمراجعة، أو التقارير.
  • إعادة إنشاء منشئ ERD من كود SQL المحدث أثناء عمليات الترحيل حتى يعكس التوثيق ما تم تغييره.
  • حافظ على مزامنة أمثلة بناء الجملة مع توثيق Erd Go DDL حتى يتمكن المساهمون في المستقبل من إعادة إنتاج المخطط.

الهدف ليس موسوعة مثالية. الهدف هو خريطة حية تساعد الناس على فهم قاعدة البيانات بسرعة والثقة فيما يقرؤونه.

المراجع والقراءات الإضافية

المزيد من المنشورات