Как настроить SQLite для KMP

Библиотека androidx.sqlite содержит абстрактные интерфейсы и базовые реализации, которые можно использовать для создания собственных библиотек, обращающихся к SQLite. Рекомендуем использовать библиотеку Room, которая предоставляет уровень абстракции для SQLite, обеспечивая более надежный доступ к базе данных и позволяя использовать все возможности SQLite.

Настройте зависимости

Чтобы настроить SQLite в проекте KMP, добавьте зависимости для артефактов в файл build.gradle.kts модуля:

[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" }

SQLite Driver API

Группы библиотек androidx.sqlite предлагают низкоуровневые API для взаимодействия с библиотекой SQLite, которая включена в библиотеку при использовании androidx.sqlite:sqlite-bundled или в хост-платформу, например Android или iOS, при использовании androidx.sqlite:sqlite-framework. API тесно связаны с основными функциями SQLite C API.

Существует три основных интерфейса:

  • SQLiteDriver – точка входа в SQLite, используемая для открытия подключений к базе данных.
  • SQLiteConnection – объект sqlite3.
  • SQLiteStatement – объект sqlite3_stmt.

В примере ниже показаны основные API.

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()
}

Как и в случае с SQLite C API, стандартный шаблон использования состоит из следующих шагов:

  1. Откройте подключение к базе данных, используя экземпляр реализации SQLiteDriver.
  2. Подготовьте инструкцию SQL с помощью SQLiteConnection.prepare.
  3. Чтобы выполнить SQLiteStatement, сделайте следующее:
    1. При необходимости свяжите аргументы с помощью функций bind*.
    2. Выполните итерацию по набору результатов с помощью функции step.
    3. Прочитайте столбцы из набора результатов с помощью функций get*.

Реализации драйверов

В таблице ниже перечислены доступные реализации драйверов.

Название класса

Объект

Поддерживаемые платформы

AndroidSQLiteDriver androidx.sqlite:sqlite-framework

Android

NativeSQLiteDriver androidx.sqlite:sqlite-framework

iOS, macOS и Linux

BundledSQLiteDriver androidx.sqlite:sqlite-bundled

Android, iOS, Mac, Linux и JVM (компьютеры)

WebWorkerSQLiteDriver androidx.sqlite:sqlite-web

JavaScript и WebAssembly (WasmJS)

Рекомендуется использовать BundledSQLiteDriver, доступный в androidx.sqlite:sqlite-bundled. Он включает библиотеку SQLite, скомпилированную из исходного кода, предлагающую самую актуальную версию и согласованность на всех поддерживаемых платформах KMP.

Драйвер SQLite и библиотека Room

API драйвера полезны для низкоуровневого взаимодействия с базой данных SQLite. Для более надежного доступа к SQLite рекомендуем использовать библиотеку Room.

Для выполнения операций с базой данных RoomDatabase использует SQLiteDriver. Вам нужно настроить реализацию с помощью RoomDatabase.Builder.setDriver. Библиотека Room предоставляет аннотации RoomDatabase.useReaderConnection и RoomDatabase.useWriterConnection для более прямого доступа к управляемым подключениям к базе данных.

Переход на Kotlin Multiplatform

Вам необходимо перенести все низкоуровневые компоненты Support SQLite API, например интерфейс SupportSQLiteDatabase, в эквивалентные компоненты SQLite Driver.

Kotlin Multiplatform

Выполнить транзакцию с помощью низкоуровневого SQLiteConnection

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")
}

Выполнить запрос без результата

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

Выполнить запрос с результатом, но без аргументов

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)
    }
}

Выполнить запрос с результатом и аргументами

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

Выполните транзакцию с помощью SupportSQLiteDatabase

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
  }
}