Configurer SQLite pour KMP

La bibliothèque androidx.sqlite contient des interfaces abstraites ainsi que des implémentations de base permettant de créer vos propres bibliothèques utilisant SQLite. Vous pouvez envisager d'utiliser la bibliothèque Room, qui fournit une couche d'abstraction sur SQLite, permettant un accès plus robuste à la base de données tout en exploitant toute la puissance de SQLite.

Configurer des dépendances

Pour configurer SQLite dans votre projet KMP, ajoutez les dépendances des artefacts dans le fichier build.gradle.kts de votre module :

[versions]
sqlite = "2.7.1"

[libraries]
# The SQLite Driver interfaces
androidx-sqlite = { module = "androidx.sqlite:sqlite", version.ref = "sqlite" }

# The bundled SQLite driver implementation
androidx-sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "sqlite" }

[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

API de pilote SQLite

Les groupes de bibliothèques androidx.sqlite proposent des API de bas niveau pour communiquer avec la bibliothèque SQLite, soit incluse dans la bibliothèque lors de l'utilisation de androidx.sqlite:sqlite-bundled, soit dans la plate-forme hôte, comme Android ou iOS lors de l'utilisation de androidx.sqlite:sqlite-framework. Les API suivent de près les fonctionnalités de base de l'API C SQLite.

Il existe trois interfaces principales :

L'exemple suivant présente les API de base :

fun main() {
    val databaseConnection = BundledSQLiteDriver().open("todos.db")
    databaseConnection.execSQL(
        "CREATE TABLE IF NOT EXISTS Todo (id INTEGER PRIMARY KEY, content TEXT)"
    )
    databaseConnection.prepare(
        "INSERT OR IGNORE INTO Todo (id, content) VALUES (? ,?)"
    ).use { stmt ->
        stmt.bindInt(index = 1, value = 1)
        stmt.bindText(index = 2, value = "Try Room in the KMP project.")
        stmt.step()
    }
    databaseConnection.prepare("SELECT content FROM Todo").use { stmt ->
        while (stmt.step()) {
            println("Action item: ${stmt.getText(0)}")
        }
    }
    databaseConnection.close()
}

Comme pour les API C SQLite, le modèle d'utilisation courant comprend les étapes suivantes :

  1. Ouvrez une connexion à la base de données à l'aide de l'implémentation SQLiteDriver instanciée.
  2. Préparez une instruction SQL à l'aide de SQLiteConnection.prepare.
  3. Exécutez un SQLiteStatement en procédant comme suit :
    1. Facultatif : liez les arguments à l'aide des fonctions bind*.
    2. Effectuez une itération sur l'ensemble de résultats à l'aide de la fonction step.
    3. Lisez les colonnes de l'ensemble de résultats à l'aide des fonctions get*.

Implémentations de pilotes

Le tableau suivant récapitule les implémentations de pilotes disponibles :

Nom de la classe

Artefact

Plates-formes compatibles

AndroidSQLiteDriver androidx.sqlite:sqlite-framework

Android

NativeSQLiteDriver androidx.sqlite:sqlite-framework

iOS, Mac et Linux

BundledSQLiteDriver androidx.sqlite:sqlite-bundled

Android, iOS, Mac, Linux et JVM (ordinateur)

WebWorkerSQLiteDriver androidx.sqlite:sqlite-web

JavaScript et WebAssembly (WasmJS)

L'implémentation recommandée est BundledSQLiteDriver, disponible dans androidx.sqlite:sqlite-bundled. Elle inclut la bibliothèque SQLite compilée à partir de la source, offrant la version la plus récente et la plus cohérente sur toutes les plates-formes KMP compatibles.

Pilote SQLite et Room

Les API de pilote sont utiles pour les interactions de bas niveau avec une base de données SQLite. Pour une bibliothèque riche en fonctionnalités qui fournit un accès plus robuste à SQLite, nous vous recommandons Room.

Un RoomDatabase s'appuie sur un SQLiteDriver pour effectuer des opérations de base de données. Vous devez configurer une implémentation à l'aide de RoomDatabase.Builder.setDriver. Room fournit RoomDatabase.useReaderConnection et RoomDatabase.useWriterConnection pour un accès plus direct aux connexions de base de données gérées.

Migrer vers Kotlin Multiplatform

Vous devez migrer toute utilisation des composants de l'API SQLite Support de bas niveau, tels que l'interface SupportSQLiteDatabase, vers les composants du pilote SQLite équivalents.

Multiplateforme Kotlin

Effectuer une transaction à l'aide de SQLiteConnection de bas niveau

val connection: SQLiteConnection = BundledSQLiteDriver().open("todos.db")
connection.execSQL("BEGIN IMMEDIATE TRANSACTION")
try {
    // perform database operations in transaction.
    connection.execSQL("END TRANSACTION")
} catch (t: Throwable) {
    connection.execSQL("ROLLBACK TRANSACTION")
}

Exécuter une requête sans résultat

val connection: SQLiteConnection = BundledSQLiteDriver().open("todos.db")
connection.execSQL("ALTER TABLE ...")

Exécuter une requête avec un résultat, mais sans argument

val connection: SQLiteConnection = BundledSQLiteDriver().open("todos.db")
connection.prepare("SELECT * FROM Pet").use { statement ->
    while (statement.step()) {
        // read columns.
        statement.getInt(0)
        statement.getText(1)
    }
}

Exécuter une requête avec un résultat et des arguments

connection.prepare("SELECT * FROM Pet WHERE id = ?").use { statement ->
    statement.bindInt(1, id)
    if (statement.step()) {
        // row found, read columns.
    } else {
        // row not found.
    }
}

Android uniquement

Effectuer une transaction à l'aide de SupportSQLiteDatabase

val database: SupportSQLiteDatabase = ...
database.beginTransaction()
try {
  // perform database operations in transaction
  database.setTransactionSuccessful()
} finally {
  database.endTransaction()
}

Exécuter une requête sans résultat

val database: SupportSQLiteDatabase = ...
database.execSQL("ALTER TABLE ...")

Exécuter une requête avec un résultat, mais sans argument

val database: SupportSQLiteDatabase = ...
database.query("SELECT * FROM Pet").use { cursor ->
  while (cursor.moveToNext()) {
    // read columns
    cursor.getInt(0)
    cursor.getString(1)
  }
}

Exécuter une requête avec un résultat et des arguments

database.query("SELECT * FROM Pet WHERE id = ?", id).use { cursor ->
  if (cursor.moveToNext()) {
    // row found, read columns
  } else {
    // row not found
  }
}