حفظ البيانات باستخدام SQLite

يُعدّ حفظ البيانات في قاعدة بيانات مثاليًا للبيانات المتكررة أو المنظَّمة، مثل معلومات الاتصال. تفترض هذه الصفحة أنّك على دراية بقواعد بيانات SQL بشكل عام، وتساعدك في بدء استخدام قواعد بيانات SQLite على Android. تتوفّر واجهات برمجة التطبيقات التي ستحتاج إليها لاستخدام قاعدة بيانات على Android في حزمة android.database.sqlite.

تنبيه: على الرغم من أنّ واجهات برمجة التطبيقات هذه فعّالة، إلا أنّها منخفضة المستوى إلى حدٍّ ما وتتطلّب قدرًا كبيرًا من الوقت والجهد لاستخدامها:

  • لا يتم التحقّق من طلبات البحث الأولية في SQL في وقت التجميع. ومع تغيُّر الرسم البياني للبيانات، عليك تعديل طلبات البحث المتأثرة في SQL يدويًا. ويمكن أن تستغرق هذه العملية وقتًا طويلاً وتكون عرضة للأخطاء.
  • تحتاج إلى استخدام الكثير من الرموز البرمجية النموذجية للتحويل بين طلبات البحث بلغة SQL وعناصر البيانات.

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

تحديد مخطط وعقد

أحد المبادئ الرئيسية لقواعد بيانات SQL هو المخطط: إعلان رسمي لكيفية تنظيم قاعدة البيانات. ينعكس المخطط في عبارات SQL التي تستخدمها لإنشاء قاعدة بياناتك. قد يكون من المفيد إنشاء صف مرافق، يُعرف باسم صف العقد، والذي يحدّد بشكل صريح تخطيط المخطط بطريقة منهجية وذاتية التوثيق.

الصف المرافق هو حاوية للثوابت التي تحدد أسماء معرّفات الموارد المنتظمة (URI) والجداول والأعمدة. يتيح لك الصف المرافق استخدام الثوابت نفسها في جميع الصفوف الأخرى في الحزمة نفسها. يتيح لك ذلك تغيير اسم العمود في مكان واحد ونشره في جميع أنحاء التعليمات البرمجية.

من الطرق الجيدة لتنظيم صف مرافق وضع التعريفات العامة لقاعدة البيانات بأكملها في المستوى الجذري للصف. ثم أنشئ فئة داخلية لكل جدول. تعدّد كل فئة داخلية أعمدة الجدول المقابل.

ملاحظة: من خلال تنفيذ واجهة BaseColumns، يمكن للفئة الداخلية أن تكتسب حقل مفتاح أساسي باسم _ID تتوقّع بعض فئات Android، مثل CursorAdapter، أن يكون لديها. هذا ليس مطلوبًا، ولكن يمكن أن يساعد قاعدة البيانات الخاصة بك على العمل بشكل متناغم مع إطار عمل Android.

على سبيل المثال، يحدّد العقد التالي اسم الجدول وأسماء الأعمدة لجدول واحد يمثّل خلاصة RSS:

Kotlin

object FeedReaderContract {
    // Table contents are grouped together in an anonymous object.
    object FeedEntry : BaseColumns {
        const val TABLE_NAME = "entry"
        const val COLUMN_NAME_TITLE = "title"
        const val COLUMN_NAME_SUBTITLE = "subtitle"
    }
}

Java

public final class FeedReaderContract {
    // To prevent someone from accidentally instantiating the contract class,
    // make the constructor private.
    private FeedReaderContract() {}

    /* Inner class that defines the table contents */
    public static class FeedEntry implements BaseColumns {
        public static final String TABLE_NAME = "entry";
        public static final String COLUMN_NAME_TITLE = "title";
        public static final String COLUMN_NAME_SUBTITLE = "subtitle";
    }
}

إنشاء قاعدة بيانات باستخدام مساعد SQL

بعد تحديد شكل قاعدة البيانات، عليك تنفيذ طرق لإنشاء قاعدة البيانات والجداول والحفاظ عليها. في ما يلي بعض العبارات النموذجية التي تنشئ جدولاً وتحذفه:

Kotlin

private const val SQL_CREATE_ENTRIES =
        "CREATE TABLE ${FeedEntry.TABLE_NAME} (" +
                "${BaseColumns._ID} INTEGER PRIMARY KEY," +
                "${FeedEntry.COLUMN_NAME_TITLE} TEXT," +
                "${FeedEntry.COLUMN_NAME_SUBTITLE} TEXT)"

private const val SQL_DELETE_ENTRIES = "DROP TABLE IF EXISTS ${FeedEntry.TABLE_NAME}"

Java

private static final String SQL_CREATE_ENTRIES =
    "CREATE TABLE " + FeedEntry.TABLE_NAME + " (" +
    FeedEntry._ID + " INTEGER PRIMARY KEY," +
    FeedEntry.COLUMN_NAME_TITLE + " TEXT," +
    FeedEntry.COLUMN_NAME_SUBTITLE + " TEXT)";

private static final String SQL_DELETE_ENTRIES =
    "DROP TABLE IF EXISTS " + FeedEntry.TABLE_NAME;

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

تحتوي الفئة SQLiteOpenHelper على مجموعة مفيدة من واجهات برمجة التطبيقات لإدارة قاعدة البيانات. عند استخدام هذه الفئة للحصول على مراجع لقاعدة البيانات، ينفّذ النظام العمليات التي يُحتمل أن تكون طويلة الأمد لإنشاء قاعدة البيانات وتعديلها فقط عند الحاجة وليس أثناء بدء تشغيل التطبيق. ما عليك سوى الاتصال بالرقم getWritableDatabase() أو getReadableDatabase().

ملاحظة: نظرًا لأنّ هذه العمليات قد تستغرق وقتًا طويلاً، يُرجى التأكّد من استدعاء getWritableDatabase() أو getReadableDatabase() في سلسلة مهام في الخلفية. لمزيد من المعلومات، يُرجى الاطّلاع على المعالجة المتعدّدة في Android.

لاستخدام SQLiteOpenHelper، أنشئ فئة فرعية تلغي طريقتَي رد الاتصال onCreate() وonUpgrade(). قد تحتاج أيضًا إلى تنفيذ الطريقتين onDowngrade() أو onOpen()، ولكنّهما غير مطلوبتين.

على سبيل المثال، إليك طريقة تنفيذ SQLiteOpenHelper التي تستخدم بعض الأوامر الموضّحة أعلاه:

Kotlin

class FeedReaderDbHelper(context: Context) : SQLiteOpenHelper(context, DATABASE_NAME, null, DATABASE_VERSION) {
    override fun onCreate(db: SQLiteDatabase) {
        db.execSQL(SQL_CREATE_ENTRIES)
    }
    override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) {
        // This database is only a cache for online data, so its upgrade policy is
        // to simply to discard the data and start over
        db.execSQL(SQL_DELETE_ENTRIES)
        onCreate(db)
    }
    override fun onDowngrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) {
        onUpgrade(db, oldVersion, newVersion)
    }
    companion object {
        // If you change the database schema, you must increment the database version.
        const val DATABASE_VERSION = 1
        const val DATABASE_NAME = "FeedReader.db"
    }
}

Java

public class FeedReaderDbHelper extends SQLiteOpenHelper {
    // If you change the database schema, you must increment the database version.
    public static final int DATABASE_VERSION = 1;
    public static final String DATABASE_NAME = "FeedReader.db";

    public FeedReaderDbHelper(Context context) {
        super(context, DATABASE_NAME, null, DATABASE_VERSION);
    }
    public void onCreate(SQLiteDatabase db) {
        db.execSQL(SQL_CREATE_ENTRIES);
    }
    public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
        // This database is only a cache for online data, so its upgrade policy is
        // to simply to discard the data and start over
        db.execSQL(SQL_DELETE_ENTRIES);
        onCreate(db);
    }
    public void onDowngrade(SQLiteDatabase db, int oldVersion, int newVersion) {
        onUpgrade(db, oldVersion, newVersion);
    }
}

للوصول إلى قاعدة البيانات، عليك إنشاء مثيل للفئة الفرعية من SQLiteOpenHelper:

Kotlin

val dbHelper = FeedReaderDbHelper(context)

Java

FeedReaderDbHelper dbHelper = new FeedReaderDbHelper(getContext());

إدخال المعلومات في قاعدة بيانات

يمكنك إدراج البيانات في قاعدة البيانات من خلال تمرير كائن ContentValues إلى طريقة insert():

Kotlin

// Gets the data repository in write mode
val db = dbHelper.writableDatabase

// Create a new map of values, where column names are the keys
val values = ContentValues().apply {
    put(FeedEntry.COLUMN_NAME_TITLE, title)
    put(FeedEntry.COLUMN_NAME_SUBTITLE, subtitle)
}

// Insert the new row, returning the primary key value of the new row
val newRowId = db?.insert(FeedEntry.TABLE_NAME, null, values)

Java

// Gets the data repository in write mode
SQLiteDatabase db = dbHelper.getWritableDatabase();

// Create a new map of values, where column names are the keys
ContentValues values = new ContentValues();
values.put(FeedEntry.COLUMN_NAME_TITLE, title);
values.put(FeedEntry.COLUMN_NAME_SUBTITLE, subtitle);

// Insert the new row, returning the primary key value of the new row
long newRowId = db.insert(FeedEntry.TABLE_NAME, null, values);

الوسيطة الأولى لـ insert() هي اسم الجدول.

تخبر الوسيطة الثانية إطار العمل بما يجب فعله في حالة أن ContentValues فارغ (أي أنك لم put أي قيم). إذا حددت اسم عمود، فسيقوم إطار العمل بإدراج صف وتعيين قيمة هذا العمود على فارغ. إذا حدّدت null، كما هو الحال في عينة التعليمات البرمجية هذه، لن يُدرج إطار العمل صفًا في حال عدم توفّر قيم.

تعرض طرق insert() معرّف الصف الذي تم إنشاؤه حديثًا، أو ستعرض -1 إذا كان هناك خطأ في إدخال البيانات. يمكن أن يحدث هذا إذا كان لديك تعارض مع البيانات الموجودة مسبقًا في قاعدة البيانات.

قراءة المعلومات من قاعدة بيانات

للقراءة من قاعدة بيانات، استخدِم طريقة query()، مع تمرير معايير الاختيار والأعمدة التي تريدها. تجمع هذه الطريقة بين عناصر insert() وupdate()، باستثناء قائمة الأعمدة التي تحدّد البيانات التي تريد جلبها ("الإسقاط")، بدلاً من البيانات المطلوب إدراجها. يتم عرض نتائج طلب البحث في عنصر Cursor.

Kotlin

val db = dbHelper.readableDatabase

// Define a projection that specifies which columns from the database
// you will actually use after this query.
val projection = arrayOf(BaseColumns._ID, FeedEntry.COLUMN_NAME_TITLE, FeedEntry.COLUMN_NAME_SUBTITLE)

// Filter results WHERE "title" = 'My Title'
val selection = "${FeedEntry.COLUMN_NAME_TITLE} = ?"
val selectionArgs = arrayOf("My Title")

// How you want the results sorted in the resulting Cursor
val sortOrder = "${FeedEntry.COLUMN_NAME_SUBTITLE} DESC"

val cursor = db.query(
        FeedEntry.TABLE_NAME,   // The table to query
        projection,             // The array of columns to return (pass null to get all)
        selection,              // The columns for the WHERE clause
        selectionArgs,          // The values for the WHERE clause
        null,                   // don't group the rows
        null,                   // don't filter by row groups
        sortOrder               // The sort order
)

Java

SQLiteDatabase db = dbHelper.getReadableDatabase();

// Define a projection that specifies which columns from the database
// you will actually use after this query.
String[] projection = {
    BaseColumns._ID,
    FeedEntry.COLUMN_NAME_TITLE,
    FeedEntry.COLUMN_NAME_SUBTITLE
    };

// Filter results WHERE "title" = 'My Title'
String selection = FeedEntry.COLUMN_NAME_TITLE + " = ?";
String[] selectionArgs = { "My Title" };

// How you want the results sorted in the resulting Cursor
String sortOrder =
    FeedEntry.COLUMN_NAME_SUBTITLE + " DESC";

Cursor cursor = db.query(
    FeedEntry.TABLE_NAME,   // The table to query
    projection,             // The array of columns to return (pass null to get all)
    selection,              // The columns for the WHERE clause
    selectionArgs,          // The values for the WHERE clause
    null,                   // don't group the rows
    null,                   // don't filter by row groups
    sortOrder               // The sort order
    );

يتم دمج الوسيطتَين الثالثة والرابعة (selection وselectionArgs) لإنشاء عبارة WHERE. بما أنّ الوسيطات يتم توفيرها بشكل منفصل عن طلب البحث، يتم إلغاء ترميزها قبل دمجها. وهذا يجعل عبارات الاختيار محصنة ضد حقن SQL. لمزيد من التفاصيل حول جميع الوسيطات، يُرجى الاطّلاع على مرجع query().

للاطّلاع على صف في المؤشر، استخدِم إحدى طرق نقل Cursor، والتي يجب استدعاؤها دائمًا قبل البدء في قراءة القيم. بما أنّ المؤشر يبدأ من الموضع -1، يؤدي استدعاء moveToNext() إلى وضع "موضع القراءة" على الإدخال الأول في النتائج ويعرض ما إذا كان المؤشر قد تجاوز الإدخال الأخير في مجموعة النتائج أم لا. بالنسبة إلى كل صف، يمكنك قراءة قيمة عمود من خلال استدعاء إحدى طرق الحصول على Cursor، مثل getString() أو getLong(). بالنسبة إلى كل طريقة من طرق GET، عليك تمرير موضع فهرس العمود الذي تريده، والذي يمكنك الحصول عليه من خلال استدعاء getColumnIndex() أو getColumnIndexOrThrow(). عند الانتهاء من تكرار النتائج، يمكنك استدعاء close() على المؤشر لتحرير موارده. على سبيل المثال، يوضّح ما يلي كيفية الحصول على جميع أرقام تعريف العناصر المخزّنة في مؤشر وإضافتها إلى قائمة:

Kotlin

val itemIds = mutableListOf<Long>()
with(cursor) {
    while (moveToNext()) {
        val itemId = getLong(getColumnIndexOrThrow(BaseColumns._ID))
        itemIds.add(itemId)
    }
}
cursor.close()

Java

List itemIds = new ArrayList<>();
while(cursor.moveToNext()) {
  long itemId = cursor.getLong(
      cursor.getColumnIndexOrThrow(FeedEntry._ID));
  itemIds.add(itemId);
}
cursor.close();

حذف المعلومات من قاعدة بيانات

لحذف صفوف من جدول، عليك تقديم معايير اختيار تحدّد الصفوف لطريقة delete(). تعمل الآلية بالطريقة نفسها التي تعمل بها وسيطات الاختيار في طريقة query(). ويقسّم مواصفات التحديد إلى عبارة تحديد ووسيطات تحديد. تحدّد عبارة العمود الأعمدة التي يجب البحث فيها، وتتيح لك أيضًا دمج اختبارات الأعمدة. الوسيطات هي قيم يتم اختبارها مقابل القيم المرتبطة بالبند. بما أنّ النتيجة لا تتم معالجتها بالطريقة نفسها التي تتم بها معالجة عبارة SQL العادية، فهي محصّنة ضد هجمات حقن SQL.

Kotlin

// Define 'where' part of query.
val selection = "${FeedEntry.COLUMN_NAME_TITLE} LIKE ?"
// Specify arguments in placeholder order.
val selectionArgs = arrayOf("MyTitle")
// Issue SQL statement.
val deletedRows = db.delete(FeedEntry.TABLE_NAME, selection, selectionArgs)

Java

// Define 'where' part of query.
String selection = FeedEntry.COLUMN_NAME_TITLE + " LIKE ?";
// Specify arguments in placeholder order.
String[] selectionArgs = { "MyTitle" };
// Issue SQL statement.
int deletedRows = db.delete(FeedEntry.TABLE_NAME, selection, selectionArgs);

تشير القيمة الناتجة عن طريقة delete() إلى عدد الصفوف التي تم حذفها من قاعدة البيانات.

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

عندما تحتاج إلى تعديل مجموعة فرعية من قيم قاعدة البيانات، استخدِم الطريقة update().

يجمع تعديل الجدول بين بنية ContentValues في insert() وبنية WHERE في delete().

Kotlin

val db = dbHelper.writableDatabase

// New value for one column
val title = "MyNewTitle"
val values = ContentValues().apply {
    put(FeedEntry.COLUMN_NAME_TITLE, title)
}

// Which row to update, based on the title
val selection = "${FeedEntry.COLUMN_NAME_TITLE} LIKE ?"
val selectionArgs = arrayOf("MyOldTitle")
val count = db.update(
        FeedEntry.TABLE_NAME,
        values,
        selection,
        selectionArgs)

Java

SQLiteDatabase db = dbHelper.getWritableDatabase();

// New value for one column
String title = "MyNewTitle";
ContentValues values = new ContentValues();
values.put(FeedEntry.COLUMN_NAME_TITLE, title);

// Which row to update, based on the title
String selection = FeedEntry.COLUMN_NAME_TITLE + " LIKE ?";
String[] selectionArgs = { "MyOldTitle" };

int count = db.update(
    FeedReaderDbHelper.FeedEntry.TABLE_NAME,
    values,
    selection,
    selectionArgs);

القيمة المعروضة من طريقة update() هي عدد الصفوف المتأثرة في قاعدة البيانات.

جارٍ الاحتفاظ باتصال قاعدة البيانات

بما أنّ getWritableDatabase() وgetReadableDatabase() مكلفان عند إغلاق قاعدة البيانات، يجب ترك اتصال قاعدة البيانات مفتوحًا طالما أنّك بحاجة إلى الوصول إليه. عادةً، من الأفضل إغلاق قاعدة البيانات في onDestroy() من النشاط الذي يتم استدعاؤه.

Kotlin

override fun onDestroy() {
    dbHelper.close()
    super.onDestroy()
}

Java

@Override
protected void onDestroy() {
    dbHelper.close();
    super.onDestroy();
}

تصحيح أخطاء قاعدة البيانات

تتضمّن حزمة تطوير البرامج (SDK) لنظام التشغيل Android أداة واجهة أوامر sqlite3 تتيح لك تصفُّح محتوى الجداول وتنفيذ أوامر SQL وتنفيذ وظائف أخرى مفيدة في قواعد بيانات SQLite. لمزيد من المعلومات، يُرجى الاطّلاع على كيفية إصدار أوامر shell.