التوثيق

دليل ربط قاعدة البيانات

العودة للوحة التحكم

دليل ربط قاعدة البيانات بتطبيقك

هذا الدليل يشرح بالتفصيل الممل كيفية ربط قاعدة البيانات التي تم إنشاؤها لك بتطبيقك، سواء كان تطبيق HTML بسيط أو أي تطبيق ويب آخر. ستتعلم كيفية استخدام المفتاح والرابط للقراءة والكتابة وإدارة الجداول بشكل كامل.

1

ما هي قاعدة البيانات؟

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

عند إنشاء قاعدة بيانات لعميل، يحصل العميل على ثلاثة أشياء أساسية:

المفتاح (Key)

سلسلة فريدة من الأحرف تعمل ككلمة مرور للوصول إلى قاعدة البيانات. بدونها لا يمكن لأي شخص القراءة أو الكتابة.

الرابط (URL)

عنوان الخادم الذي توجد عليه قاعدة البيانات. من خلاله يتصل تطبيقك بالبيانات.

رابط المكتبة (Library)

رابط تحميل مكتبة الاتصال الخاصة بك. تضيفه في ملف HTML لتحميل الأدوات اللازمة للاتصال بقاعدة البيانات.

2

الخطوة الأولى: الحصول على بيانات الاتصال

بعد أن يقوم الأدمن بإنشاء قاعدة البيانات لك، ستحصل على المفتاح والرابط. احتفظ بهما في مكان آمن، لأن المفتاح هو وسيلة الوصول الوحيدة لبياناتك.

تنبيه مهم: لا تشارك المفتاح مع أي شخص غير موثوق. من يملك المفتاح يمكنه قراءة وتعديل جميع بياناتك.

3

الخطوة الثانية: إضافة قاعدة البيانات إلى ملف HTML

لإضافة قاعدة البيانات إلى تطبيق HTML الخاص بك، تحتاج إلى إضافة سطر واحد في قسم<head>من ملف HTML الخاص بك. هذا السطر يقوم بتحميل المكتبة اللازمة للاتصال، وهو رابط المكتبة الذي حصلت عليه عند إنشاء قاعدة البيانات.

<script src="ضع_رابط_المكتبة_هنا"></script>

بعد تحميل المكتبة، تحتاج إلى تهيئة الاتصال باستخدام المفتاح والرابط الخاصين بك. أضف هذا الكود في نهاية ملف HTML قبل إغلاق وسم</body>:

<script>
  // تهيئة الاتصال بقاعدة البيانات
  const db = new DatabaseClient({
    key: "ضع_المفتاح_هنا",
    url: "ضع_الرابط_هنا"
  });

  // اختبار الاتصال
  db.connect().then(() => {
    console.log("تم الاتصال بقاعدة البيانات بنجاح");
  });
</script>
4

الخطوة الثالثة: إنشاء الجداول

الجدول هو المكان الذي تخزن فيه نوعاً معيناً من البيانات. مثلاً، إذا كان تطبيقك يدير المستخدمين، ستحتاج جدولاً باسم users.

// إنشاء جدول جديد باسم "users"
await db.createTable("users", {
  name: "string",      // اسم المستخدم
  email: "string",     // البريد الإلكتروني
  age: "number",       // العمر
  active: "boolean"    // هل الحساب نشط
});

يمكنك إنشاء أي عدد من الجداول، وكل جدول يحتوي على أعمدة (حقول) تحدد نوع البيانات المخزنة فيه.

5

الخطوة الرابعة: إضافة البيانات (الكتابة)

لإضافة سجل جديد إلى جدول، استخدم دالة الإدراج. كل سجل هو مجموعة من القيم المطابقة للأعمدة التي عرّفتها.

// إضافة مستخدم جديد
await db.insert("users", {
  name: "أحمد محمد",
  email: "ahmed@example.com",
  age: 30,
  active: true
});
6

الخطوة الخامسة: قراءة البيانات

لقراءة البيانات من جدول، استخدم دالة الاستعلام. يمكنك جلب جميع السجلات أو تصفيتها حسب شروط معينة.

// جلب جميع المستخدمين
const allUsers = await db.query("users").getAll();

// جلب مستخدمين محددين حسب شرط
const activeUsers = await db.query("users")
  .where("active", "==", true)
  .getAll();

// جلب مستخدم واحد حسب البريد
const user = await db.query("users")
  .where("email", "==", "ahmed@example.com")
  .first();
7

الخطوة السادسة: تحديث وحذف البيانات

يمكنك تعديل سجل موجود أو حذفه بالكامل. التحديث يغيّر قيمة حقل أو أكثر، والحذف يزيل السجل نهائياً.

// تحديث عمر المستخدم
await db.update("users", userId, {
  age: 31
});

// حذف مستخدم
await db.delete("users", userId);

// حذف جميع السجلات المطابقة لشرط
await db.query("users")
  .where("active", "==", false)
  .deleteAll();
8

الخطوة السابعة: إدارة الجداول بشكل كامل

لديك تحكم كامل في قاعدة البيانات. يمكنك إضافة أعمدة جديدة، حذف جداول، أو مسح جميع البيانات.

// إضافة عمود جديد لجدول موجود
await db.addColumn("users", "phone", "string");

// حذف جدول بالكامل
await db.dropTable("users");

// مسح جميع بيانات جدول (مع الإبقاء على هيكله)
await db.clearTable("users");

// عرض قائمة بجميع الجداول
const tables = await db.listTables();
9

مثال كامل متكامل

هذا مثال كامل لصفحة HTML تستخدم قاعدة البيانات لتخزين وعرض قائمة مهام بسيطة:

<!DOCTYPE html>
<html lang="ar" dir="rtl">
<head>
  <meta charset="UTF-8">
  <title>قائمة المهام</title>
  <script src="ضع_رابط_المكتبة_هنا"></script>
</head>
<body>
  <h1>قائمة المهام</h1>
  <input id="taskInput" placeholder="أدخل مهمة جديدة">
  <button onclick="addTask()">إضافة</button>
  <ul id="taskList"></ul>

  <script>
    // تهيئة الاتصال
    const db = new DatabaseClient({
      key: "ضع_المفتاح_هنا",
      url: "ضع_الرابط_هنا"
    });

    // إنشاء الجدول عند التحميل
    db.connect().then(async () => {
      await db.createTable("tasks", {
        title: "string",
        done: "boolean"
      });
      loadTasks();
    });

    // إضافة مهمة
    async function addTask() {
      const input = document.getElementById("taskInput");
      await db.insert("tasks", {
        title: input.value,
        done: false
      });
      input.value = "";
      loadTasks();
    }

    // عرض المهام
    async function loadTasks() {
      const tasks = await db.query("tasks").getAll();
      const list = document.getElementById("taskList");
      list.innerHTML = "";
      tasks.forEach(task => {
        const li = document.createElement("li");
        li.textContent = task.title;
        list.appendChild(li);
      });
    }
  </script>
</body>
</html>

نصائح مهمة

  • احتفظ بنسخة احتياطية من المفتاح في مكان آمن.
  • استخدم أسماء جداول وحقول واضحة ووصفية.
  • اختبر الاتصال قبل نشر تطبيقك للعملاء.
  • لا تخزن كلمات المرور كنص عادي — استخدم التشفير دائماً.
Made with Stunning · صُنع بواسطة Stunning