Database Inspector: ما هو، كيفية العمل مع SQLite وتصحيح أخطاء Room

ما هو Database Inspector؟

Database Inspector هو أداة من Android Studio لفحص وتصحيح أخطاء قواعد البيانات المحلية في تطبيق الجوال. يتيح عرض جميع قواعد بيانات SQLite التي أنشأها التطبيق، بما في ذلك قواعد Room و SQLiteOpenHelper والمكتبات الخارجية. الأداة متاحة بدءاً من Android Studio 4.1 ويمكن تشغيلها عبر Android Profiler أو مباشرة من قائمة View.

الغرض والإمكانيات

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

متى تستخدم Database Inspector

الأداة لا غنى عنها في السيناريوهات التي تحتاج فيها إلى التحقق من صحة تخزين البيانات بعد إجراء عملية: تسجيل المستخدم، المزامنة مع الخادم، تخزين القوائم مؤقتاً. بدلاً من كتابة واجهة اختبار، يتم عرض نسخة قاعدة البيانات عبر Database Inspector. كما تُستخدم الأداة بنشاط لتصحيح أخطاء ترحيل Room — يمكنك رؤية هيكل الجدول الفعلي بعد كل تحديث للهيكل.

كيف يعمل Database Inspector

Database Inspector يتصل بعملية تطبيق Android عبر Android Profiler Service. يكتشف جميع اتصالات SQLite المفتوحة في التطبيق ويعرضها في اللوحة الجانبية. يلزم وجود إصدار Debug من التطبيق مع API Level 26 (Android 8.0) فأعلى.

الهيكلية وآلية العمل

عند التشغيل، يقوم Database Inspector بإنشاء نفق ADB بين التطبيق على الجهاز و IDE على الكمبيوتر. يتم بث ملفات قاعدة بيانات SQLite WAL (Write-Ahead Logging) عبر هذا النفق لعرض المحتويات. تُرسل أوامر SQL مباشرة إلى محرك SQLite الخاص بالتطبيق عبر دعم Database Inspector في Room و SQLiteDatabase. تكتشف الأداة تلقائياً عندما يفتح التطبيق قاعدة بيانات وتضيفها إلى القائمة التي يتم فحصها.

متطلبات البيئة

لكي يعمل Database Inspector بشكل صحيح، تحتاج إلى: Android Studio 4.1+، جهاز أو محاكٍ بـ API Level 26+، وإصدار Debug من التطبيق. بالنسبة لـ Room، يلزم أيضاً مكتبة room-runtime الإصدار 2.2+. إذا تم إنشاء قاعدة البيانات بوضع WAL، وهو المعيار لـ Room 2.2+، يمكن للأداة قراءة البيانات دون حظر التطبيق الرئيسي.

// مثال لقاعدة بيانات Room مدعومة من Database Inspector
@Database(
    entities = [User::class, Order::class],
    version = 2,
    autoMigrations = [AutoMigration(from = 1, to = 2)]
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
    abstract fun orderDao(): OrderDao
}

الميزات الرئيسية لـ Database Inspector

يوفر Database Inspector مجموعة كاملة من الوظائف للعمل مع البيانات المحلية: من عرض هيكل الجداول إلى تنفيذ استعلامات SQL المعقدة وتحرير السجلات.

عرض الجداول والهيكل

تعرض اللوحة اليسرى جميع قواعد البيانات والجداول. عند تحديد جدول، يتم عرض محتوياته في شبكة مع أعمدة: تظهر جميع حقول السجل كأعمدة، كل صف هو سجل منفصل. يُعرض هيكل الجدول (الاسم، النوع، القيود) في الأعلى. للمفاتيح الخارجية، تظهر العلاقات بين الجداول.

تنفيذ استعلامات SQL

علامة التبويب Query تتيح تنفيذ أوامر SQL عشوائية مباشرة على قاعدة البيانات المحددة. يتم دعم SELECT و INSERT و UPDATE و DELETE و CREATE INDEX و JOIN وأي مشغلات SQLite أخرى. تُعرض النتائج بتنسيق جدولي أسفل محرر الاستعلامات. يُحتفظ بسجل الاستعلامات خلال الجلسة.

تحرير السجلات

يمكن تحرير خلايا الجدول مباشرة — فقط انقر على قيمة وأدخل قيمة جديدة. يتم تطبيق التغييرات فوراً على التطبيق قيد التشغيل. هذا مفيد بشكل خاص لاختبار الحالات الحدودية: تعيين null في حقل إلزامي، استبدال ID بآخر غير موجود، التحقق من معالجة السلاسل الطويلة. جميع التغييرات تُثبت في الوقت الفعلي.

تصحيح أخطاء Room باستخدام Database Inspector

يتمتع Database Inspector بتكامل عميق مع Room، مما يجعله لا غنى عنه عند تطوير التطبيقات بهذه المكتبة. بالإضافة إلى الوظائف القياسية، يوفر المفتش إمكانيات خاصة بـ Room.

عرض استعلامات DAO

لقواعد بيانات Room، يعرض Database Inspector استعلامات SQL المُنشأة لكل طريقة DAO. يتيح لك ذلك التحقق من أن Room يُنشئ SQL صحيحاً، خاصة للاستعلامات المعقدة مع JOIN و @Relation و @Transaction. إذا نفذ Room استعلاماً غير فعال (مثل N+1 استعلام بدلاً من JOIN واحد)، يظهر ذلك فوراً في سجل استعلامات Database Inspector.

تصحيح أخطاء الترحيل

عند تحديث هيكل Room باستخدام AutoMigration أو الترحيل اليدوي، يُظهر Database Inspector هيكل الجدول الفعلي بعد الترحيل. فقط افتح المفتش بعد تشغيل التطبيق وتحقق من أن جميع الأعمدة والفهارس والمفاتيح الخارجية قد أُنشئت بشكل صحيح. إذا فشل الترحيل مع خطأ، لن تفتح قاعدة البيانات — ستظهر الأداة آخر إصدار متاح.

التحقق من Relations و Embedded

يسمح Room بدمج البيانات من جداول متعددة عبر @Relation و @Embedded. يساعد Database Inspector في التحقق بصرياً من صحة العلاقات من خلال عرض بيانات الجداول المرتبطة جنباً إلى جنب. لكل مفتاح خارجي، يمكنك الانتقال إلى الجدول المرتبط بنقرة واحدة.

// كيان مع Relation للتحقق عبر Database Inspector
@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Int,
    val name: String
)

data class UserWithOrders(
    @Embedded val user: User,
    @Relation(parentColumn = "id", entityColumn = "user_id")
    val orders: List<Order>
)

سيناريوهات الاستخدام العملي لـ Database Inspector

يحل Database Inspector مهام تطوير محددة تنشأ عند العمل مع تخزين البيانات المحلي. دعنا نلقي نظرة على حالات الاستخدام الأكثر شيوعاً للأداة في العمل اليومي.

التحقق من تخزين البيانات مؤقتاً

غالباً ما يخزن التطبيق استجابات API مؤقتاً في قاعدة بيانات محلية. يتيح لك Database Inspector التحقق من صحة التخزين المؤقت: بعد المزامنة، يمكنك رؤية السجلات الفعلية في جدول التخزين المؤقت. إذا لم تظهر البيانات — المشكلة في كود الحفظ. إذا ظهرت نسخ مكررة — المشكلة في منطق upsert.

تصحيح أخطاء إدراج البيانات

عندما لا تحفظ طريقة DAO البيانات ولكنها لا ترمي استثناءً، يُظهر Database Inspector الحالة الفعلية للجدول. الأسباب النموذجية: تعارض المفتاح الأساسي (إعداد OnConflictStrategy)، نوع بيانات غير صحيح في عمود، انتهاك قيد NOT NULL أو انتهاك المفتاح الخارجي. يسمح المفتش برؤية مجموعة تغييرات قاعدة البيانات قبل العملية وبعدها. مقارنة لقطات البيانات قبل وبعد استدعاء DAO هي إحدى أكثر الطرق فعالية لتصحيح أخطاء المعاملات والتحقق من صحة منطق الأعمال للتطبيق أثناء عمليات الكتابة المعقدة.

إعادة هيكلة مخطط قاعدة البيانات

عند تغيير هيكل الجداول — إضافة أعمدة، إعادة تسمية الحقول، تقسيم الجداول — يساعد Database Inspector في التحقق من نتيجة الترحيل. فقط قم بتشغيل التطبيق بالإصدار الجديد من قاعدة البيانات وتحقق من أن جميع البيانات قد نُقلت بشكل صحيح إلى الهيكل الجديد. إذا فُقدت البيانات بعد الترحيل، يمكنك استعادتها من نسخة احتياطية محفوظة قبل إعادة الهيكلة. هذا السيناريو مهم بشكل خاص عند الانتقال من SQLiteOpenHelper إلى Room أو عند تغيير هيكل الجداول الموجودة في إصدار جديد من التطبيق.

مراقبة أداء الاستعلامات

يمكن استخدام Database Inspector أيضاً لتقييم أداء استعلامات SQL. من خلال تنفيذ SELECT عبر علامة التبويب Query وقياس وقت الاستجابة، يمكنك تحديد الاستعلامات التي تفتقر إلى الفهارس. يسجل Room تلقائياً الاستعلامات البطيئة في Logcat مع علامة SLOW SQL، ويسمح لك Database Inspector بتنفيذ EXPLAIN QUERY PLAN فوراً لتحليل خطة التنفيذ.