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 pour les artefacts dans le fichier build.gradle.kts de votre module :

[versions]
sqlite = "2.7.0"

[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 incluse dans la bibliothèque lorsque vous utilisez androidx.sqlite:sqlite-bundled ou dans la plate-forme hôte, telle qu'Android ou iOS lorsque vous utilisez androidx.sqlite:sqlite-framework. Les API suivent de près la fonctionnalité principale de l'API C de SQLite.

Il existe trois interfaces principales :

• SQLiteDriver: point d'entrée de SQLite, utilisé pour ouvrir des connexions à la base de données.
• SQLiteConnection: représente l'objet sqlite3.
• SQLiteStatement: représente l'objet sqlite3_stmt.

L'exemple suivant présente les API principales :

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 de 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 une SQLiteStatement en procédant comme suit :
   1. Facultatif : liez les arguments à l'aide des fonctions bind*.
   2. Parcourez 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 pilote

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

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 une cohérence 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 offre un accès plus robuste à SQLite, nous vous recommandons Room.

Une RoomDatabase s'appuie sur un SQLiteDriver pour effectuer des opérations de base de données, et vous devez configurer une implémentation à l'aide de RoomDatabase.Builder.setDriver. Room provides RoomDatabase.useReaderConnection and RoomDatabase.useWriterConnection for more direct access to the managed database connections.

Migrer vers Kotlin Multiplatform

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

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

val connection: SQLiteConnection = ...
connection.execSQL("ALTER TABLE ...")

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

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

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

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

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

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