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



