שמירת נתונים באמצעות SQLite

שמירת נתונים במסד נתונים היא אידיאלית לנתונים חוזרים או מובנים, כמו פרטים ליצירת קשר. ההנחה בדף הזה היא שאתם מכירים מסדי נתונים של SQL באופן כללי, והוא עוזר לכם להתחיל לעבוד עם מסדי נתונים של SQLite ב-Android. ממשקי ה-API שצריך כדי להשתמש במסד נתונים ב-Android זמינים בחבילה android.database.sqlite.

זהירות: למרות שממשקי ה-API האלה הם חזקים, הם ברמה נמוכה יחסית ודורשים הרבה זמן ומאמץ כדי להשתמש בהם:

  • אין אימות של שאילתות SQL גולמיות בזמן הקימפול. כשהתרשים של הנתונים משתנה, צריך לעדכן ידנית את שאילתות ה-SQL שמושפעות מהשינוי. התהליך הזה יכול להיות ארוך ומועד לשגיאות.
  • צריך להשתמש בהרבה קוד שחוזר על עצמו (boilerplate) כדי להמיר בין שאילתות SQL לאובייקטים של נתונים.

לכן, אנחנו ממליצים מאוד להשתמש בספריית Room persistence כשכבת הפשטה לגישה למידע במסדי הנתונים של SQLite באפליקציה.

הגדרת סכימה וחוזה

אחד העקרונות החשובים של מסדי נתונים ב-SQL הוא הסכימה: הצהרה רשמית על האופן שבו מסד הנתונים מאורגן. הסכימה משתקפת בהצהרות ה-SQL שבהן אתם משתמשים כדי ליצור את מסד הנתונים. כדאי ליצור מחלקה נלווית, שנקראת מחלקה של ערכים קבועים (contract), שמציינת באופן מפורש את פריסת הסכימה בצורה שיטתית ומתועדת.

מחלקה של ערכים קבועים היא מאגר של קבועים שמגדירים שמות של מזהי 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 מכילה קבוצה שימושית של ממשקי API לניהול מסד הנתונים. כשמשתמשים במחלקה הזו כדי לקבל הפניות למסד הנתונים, המערכת מבצעת את הפעולות הממושכות שעלולות להימשך זמן רב של יצירה ועדכון של מסד הנתונים רק כשצריך, ולא במהלך הפעלת האפליקציה. כל מה שצריך לעשות הוא להתקשר למספר getWritableDatabase() או getReadableDatabase().

הערה: מכיוון שהן יכולות לפעול לאורך זמן, הקפידו להפעיל את getWritableDatabase() או את getReadableDatabase() בשרשור ברקע. מידע נוסף זמין במאמר Threading on 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 ל-method‏ 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. אם מציינים את הערך null, כמו בדוגמת הקוד הזו, ה-framework לא מוסיף שורה כשאין ערכים.

השיטה insert() מחזירה את המזהה של השורה החדשה שנוצרה, או את הערך ‎-1 אם הייתה שגיאה בהוספת הנתונים. זה יכול לקרות אם יש התנגשות עם נתונים קיימים במסד הנתונים.

לקרוא מידע ממסד נתונים

כדי לקרוא ממסד נתונים, משתמשים ב-method‏ 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(). בכל אחת משיטות אחזור הנתונים, צריך להעביר את מיקום האינדקס של העמודה הרצויה, שאפשר לקבל על ידי קריאה ל-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();

מחיקת מידע ממסד נתונים

כדי למחוק שורות מטבלה, צריך לספק קריטריונים לבחירה שמזהים את השורות ב-method‏ delete(). המנגנון פועל באותו אופן כמו הארגומנטים של הבחירה ב-method‏ 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() מציין את מספר השורות שנמחקו ממסד הנתונים.

עדכון מסד נתונים

כדי לשנות קבוצת משנה של ערכים במסד הנתונים, משתמשים ב-method 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();
}

ניפוי באגים במסד הנתונים

‫Android SDK כולל כלי מעטפת של sqlite3 שמאפשר לעיין בתוכן של טבלאות, להריץ פקודות SQL ולבצע פונקציות שימושיות אחרות במסדי נתונים של SQLite. מידע נוסף זמין במאמר איך מנפיקים פקודות מעטפת.