Database Inspector: چیست، چگونه با SQLite کار کنیم و Room را اشکال‌زدایی کنیم

Database Inspector چیست؟

Database Inspector — ابزاری در Android Studio برای بازرسی و اشکال‌زدایی پایگاه‌های داده محلی در برنامه موبایل است. این ابزار امکان مشاهده تمام پایگاه‌های داده SQLite ایجاد شده توسط برنامه، از جمله پایگاه‌های Room، SQLiteOpenHelper و کتابخانه‌های شخص ثالث را فراهم می‌کند. این ابزار از Android Studio 4.1 در دسترس است و از طریق Android Profiler یا مستقیماً از منوی View راه‌اندازی می‌شود.

هدف و قابلیت‌ها

وظیفه اصلی Database Inspector تجسم داده‌ها در فرآیند توسعه است. به جای خروجی محتوای پایگاه داده در log یا نوشتن صفحه جداگانه برای مشاهده داده‌ها، توسعه‌دهنده می‌تواند Database Inspector را باز کند و بلافاصله تمام جداول، طرح و محتوای آنها را ببیند. این ابزار هم از پایگاه‌های داده رابطه‌ای SQLite و هم Room با Auto-Migration پشتیبانی می‌کند.

چه زمانی از Database Inspector استفاده کنیم

این ابزار در سناریوهایی که نیاز به بررسی صحت ذخیره‌سازی داده‌ها پس از انجام عملیات است ضروری است: ثبت‌نام کاربر، همگام‌سازی با سرور، کش کردن لیست‌ها. به جای نوشتن UI آزمایشی، dump پایگاه داده از طریق Database Inspector مشاهده می‌شود. همچنین این ابزار به طور فعال برای اشکال‌زدایی مهاجرت‌های Room استفاده می‌شود — می‌توان پس از هر به‌روزرسانی طرح، طرح فعلی جداول را مشاهده کرد.

Database Inspector چگونه کار می‌کند

Database Inspector به فرآیند برنامه Android از طریق Android Profiler Service متصل می‌شود. این ابزار تمام اتصالات باز SQLite در برنامه را شناسایی می‌کند و آنها را در پنل کناری نمایش می‌دهد. برای کار نیاز به بیلد Debug برنامه با API Level 26 (Android 8.0) و بالاتر است.

معماری و مکانیسم کار

هنگام راه‌اندازی Database Inspector یک تونل ADB بین برنامه روی دستگاه و IDE روی رایانه ایجاد می‌کند. فایل‌های WAL (Write-Ahead Logging) پایگاه داده SQLite از طریق این تونل برای نمایش محتوا منتقل می‌شوند. دستورات 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 با ID ناموجود، بررسی پردازش رشته‌های طولانی. تمام تغییرات در زمان واقعی ثبت می‌شوند.

اشکال‌زدایی Room با Database Inspector

Database Inspector یکپارچگی عمیقی با Room دارد که آن را در توسعه برنامه‌ها با این کتابخانه ضروری می‌کند. علاوه بر عملکرد استاندارد، بازرس قابلیت‌های خاص Room را فراهم می‌کند.

مشاهده کوئری‌های DAO

برای پایگاه‌های Room، Database Inspector کوئری‌های SQL تولید شده را برای هر متد DAO نشان می‌دهد. این امکان اطمینان از تولید SQL صحیح توسط Room را فراهم می‌کند، به ویژه برای کوئری‌های پیچیده با JOIN، @Relation و @Transaction. اگر Room کوئری ناکارآمدی اجرا کند (مثلاً N+1 کوئری به جای یک JOIN)، بلافاصله در log کوئری‌های Database Inspector قابل مشاهده است.

اشکال‌زدایی مهاجرت‌ها

هنگام به‌روزرسانی طرح Room با AutoMigration یا مهاجرت‌های دستی، Database Inspector ساختار فعلی جداول را پس از مهاجرت نشان می‌دهد. کافیست پس از راه‌اندازی برنامه بازرس را باز کنید و بررسی کنید که تمام ستون‌ها، ایندکس‌ها و کلیدهای خارجی به درستی ایجاد شده‌اند. اگر مهاجرت با خطا مواجه شده باشد، پایگاه داده باز نخواهد شد — ابزار آخرین نسخه موجود را نشان می‌دهد.

بررسی Relations و Embedded

Room امکان ترکیب داده‌ها از چندین جدول را از طریق @Relation و @Embedded فراهم می‌کند. Database Inspector با نمایش داده‌های جداول مرتبط در کنار هم به بررسی بصری صحت ارتباطات کمک می‌کند. برای هر کلید خارجی می‌توان با یک کلیک به جدول مرتبط رفت.

// Entity با 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 وضعیت فعلی جدول را نشان می‌دهد. دلایل معمول: تضاد Primary Key (تنظیم OnConflictStrategy)، نوع داده نادرست در ستون، نقض محدودیت‌های NOT NULL یا Foreign Key violation. بازرس امکان مشاهده changeset پایگاه داده قبل و بعد از عملیات را فراهم می‌کند. مقایسه تصاویر لحظه‌ای داده‌ها قبل و بعد از فراخوانی DAO — یکی از مؤثرترین روش‌های اشکال‌زدایی خطاهای تراکنشی و بررسی صحت منطق تجاری برنامه در عملیات‌های پیچیده نوشتن است.

بازآرایی طرح پایگاه داده

هنگام تغییر طرح جداول — افزودن ستون‌ها، تغییر نام فیلدها، تقسیم جداول — Database Inspector به بررسی نتیجه مهاجرت کمک می‌کند. کافیست برنامه را با نسخه جدید پایگاه داده راه‌اندازی کرده و مطمئن شوید تمام داده‌ها به درستی به ساختار جدید منتقل شده‌اند. اگر پس از مهاجرت داده‌ها ناپدید شدند، می‌توان آنها را از dump ذخیره شده قبل از بازآرایی بازیابی کرد. این سناریو به ویژه هنگام مهاجرت از SQLiteOpenHelper به Room یا هنگام تغییر ساختار جداول موجود در نسخه جدید برنامه مهم است.

نظارت بر عملکرد کوئری‌ها

Database Inspector همچنین می‌تواند برای ارزیابی عملکرد کوئری‌های SQL استفاده شود. با اجرای SELECT از طریق زبانه Query و اندازه‌گیری زمان پاسخ، می‌توان کوئری‌هایی را که ایندکس ندارند شناسایی کرد. Room به طور خودکار کوئری‌های کند را در Logcat با برچسب SLOW SQL ثبت می‌کند و Database Inspector امکان اجرای فوری EXPLAIN QUERY PLAN برای تحلیل plan اجرا را فراهم می‌کند.