الجداول والمخطط

يحمل الجدول نوعاً واحداً من الأشياء — منتجات أو طلبات أو رسائل أو فواتير. كل عمود قطعة معلومات عن ذلك الشيء (سعر أو تاريخ أو معرّف مستخدم). ضبط المخطط بشكل صحيح من البداية يوفّر ألماً لاحقاً.

إنشاء جدول

أنواع الأعمدة

يغطي محدّد الأنواع في المحرر البصري أكثر أنواع PostgreSQL شيوعاً. التي ستصل إليها أكثر:

المفاتيح الأساسية

استخدم uuid مع قيمة افتراضية. عشوائي وآمن من التصادم ولا يسرّب معلومات عدد الصفوف:

id UUID PRIMARY KEY DEFAULT gen_random_uuid()

استخدم bigserial (عدد صحيح يتزايد تلقائياً) فقط عندما تحتاج فعلاً ترتيباً أو عناوين URL أقصر. لمعظم التطبيقات، UUID هو الجواب الصحيح.

الطوابع الزمنية

يجب أن يكون لكل جدول هذان العمودان:

created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()

يزرع المحرر البصري المفتاح الأساسي id لكن ليس الطوابع الزمنية — أضف created_at / updated_at بنفسك (في محدّد الأعمدة أو عبر SQL). ستحتاجها للتصحيح والترتيب ومسارات التدقيق لاحقاً، لذا يستحق إضافتها على كل جدول.

لإبقاء updated_at حديثاً، إما حدّثه في سير عملك (SET updated_at = now()) أو أضف محفّزاً. معظم التطبيقات تحدّثه في سير العمل — أبسط.

⚠️ مراجع المستخدمين: استخدم TEXT لا UUID

هذا هو الخطأ رقم 1 الذي يرتكبه الناس. يستخدم نظام مصادقة HeroMate معرّفاً من 32 حرفاً (وليس UUID)، لذا أي عمود يشير إلى مستخدم يجب أن يكون TEXT.

صحيح

CREATE TABLE public.tasks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT NOT NULL REFERENCES system.users(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  done BOOLEAN NOT NULL DEFAULT false,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

خطأ (سينهار وقت التشغيل)

-- ❌ Don't do this
user_id UUID REFERENCES system.users(id)

عندما يحاول endpoint WHERE user_id = ${current_user_id}، سيفشل Postgres بـ:

invalid input syntax for type uuid: "G1LIBXsbMLxUrs99ebCaL9X4auxW26AC"

قاعدة عامة: أي عمود يربط صفاً بمستخدم = TEXT. المفاتيح الأجنبية الأخرى (product_id → products.id و order_id → orders.id) تبقي UUID الطبيعي.

الفهارس

أضف فهرساً لأي عمود تصفّي أو ترتّب به كثيراً. للمحرر البصري لوحة Indexes منفصلة لكل جدول:

أنماط شائعة:

• فهرس كل مفتاح أجنبي (user_id و product_id وغيرها) — تصفّي معظم الاستعلامات بها
• فهرس created_at DESC إذا سردت العناصر الحديثة
• تخطَّ الفهارس على الجداول الصغيرة (أقل من ~1k صف) — Postgres سريع بما يكفي دونها

مثال: جدول tasks منمذج جيداً

هكذا يبدو جدول نموذجي يملكه المستخدم مع كل الاصطلاحات مطبّقة:

CREATE TABLE public.tasks (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id       TEXT NOT NULL REFERENCES system.users(id) ON DELETE CASCADE,
  title         TEXT NOT NULL,
  description   TEXT,
  done          BOOLEAN NOT NULL DEFAULT false,
  due_date      DATE,
  priority      INT NOT NULL DEFAULT 0,
  tags          TEXT[] NOT NULL DEFAULT '{}',
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_tasks_user_id ON public.tasks(user_id);
CREATE INDEX idx_tasks_created_at ON public.tasks(created_at DESC);

انسخ هذا كنقطة انطلاق عندما تبني أي شيء ينتمي إلى مستخدم.

الخطوات التالية