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

يستخدم قالب حسنات Cloudflare D1، وهي قاعدة بيانات SQLite تعمل مع Cloudflare. لكل تطبيق قاعدته الخاصة.

قاعدتك أو قاعدة من حسنات

• في حسابك على Cloudflare: أنشئ القاعدة بنفسك بالخطوات أدناه. يناسبك هذا إن كنت تنشر التطبيق من حسابك.
• في حساب حسنات: إن كان تطبيقك سيعمل في حساب حسنات على Cloudflare، فاطلب «قاعدة بيانات» من لوحة المنصة. ينشئها مسؤول الخدمات ويرسل لك اسمها ومعرّفها في ملاحظة الطلب. الاسم والمعرّف ليسا سرّين، ولا ترسل أي سرّ في الطلب. اتفق معه في الطلب نفسه على من يطبّق تغييرات المخطّط على القاعدة.

قاعدة hasanat-db المشتركة خاصة بـ hasanat.dev وهذه المنصة، ومخطّطها في مستودع hasanat. لا تستخدمها لتطبيق مشروعك.

الإعداد في القالب

1. أنشئ القاعدة. يطبع الأمر معرّفها database_id:

   npx wrangler d1 create your-app-db

2. أضف الربط إلى wrangler.toml:

   [[d1_databases]]
   binding = "DB"
   database_name = "your-app-db"
   database_id = "paste-your-database-id-here"

3. عدّل schema.sql بما يحتاجه تطبيقك.

4. ضع اسم قاعدتك مكان YOUR_DB_NAME في أمري db:migrate:local وdb:migrate:prod في package.json، ثم طبّق المخطّط على القاعدة المحلية:

   npm run db:migrate:local

   الأمر npm run db:migrate:prod يطبّقه على قاعدة الإنتاج. لا تشغّله قبل مراجعة التغيير.

تغييرات المخطّط بعد الإطلاق

ملف schema.sql الواحد يكفي في البداية. حين يصبح للقاعدة بيانات حقيقية، احفظ كل تغيير في ملف ترحيل مستقل، ليبقى تاريخ التغييرات واضحًا:

npx wrangler d1 migrations create your-app-db add-items
npx wrangler d1 migrations apply your-app-db --local
npx wrangler d1 migrations apply your-app-db --remote

الاستخدام في الكود

import { getDB, queryAll, queryOne, execute } from "@/lib/db";

const db = getDB(Astro.locals);

const items = await queryAll(db, "SELECT * FROM items WHERE status = ?", "active");
const item = await queryOne(db, "SELECT * FROM items WHERE id = ?", id);
await execute(db, "INSERT INTO items (title_ar, created_by) VALUES (?, ?)", title, user.id);

يستخدم القالب Astro 5، فيقرأ الربط من Astro.locals.runtime.env. في Astro 6 وما بعده أُزيل Astro.locals.runtime، فاستورد env من cloudflare:workers واستخدم env.DB.

اصطلاحات المخطّط

• أعمدة ثنائية اللغة لكل نص يظهر للمستخدم: title_ar وtitle_en.
• التواريخ نصًّا بالقيمة الافتراضية datetime('now').
• قيود CHECK لحقول الحالة.
• created_by نصًّا، ويحمل معرّف المستخدم من تسجيل الدخول.
• فهارس على الأعمدة التي تصفّي بها أو ترتّب بها كثيرًا.

الأمان

• استخدم الاستعلامات ذات المعاملات دائمًا، ولا تدمج مدخلات المستخدم في نص SQL.
• تحقّق من المدخلات بـ zod قبل الكتابة.
• تأكّد من تسجيل الدخول قبل أي كتابة، ولا تُرجع إلا البيانات التي يحق للمستخدم رؤيتها.
• لا تضع في الاختبارات أو البيانات التجريبية أسماء أو أرقامًا حقيقية.

// صحيح: استعلام بمعاملات
await db.prepare("SELECT * FROM items WHERE id = ?").bind(id).all();

// خطأ: عرضة لحقن SQL
await db.prepare(`SELECT * FROM items WHERE id = ${id}`).all();

الحدود

بحسب توثيق Cloudflare، تتيح الخطة المجانية 5 ملايين صف مقروء و100 ألف صف مكتوب يوميًا، و5 غيغابايت تخزينًا للحساب، و500 ميغابايت للقاعدة الواحدة، و10 قواعد للحساب. راجع الصفحة الرسمية لأحدث الأرقام.