SQLite (Kotlin multiplataforma)

A biblioteca androidx.sqlite contém interfaces abstratas com implementações básicas que podem ser usadas para criar bibliotecas que acessam o SQLite. É recomendado usar a biblioteca Room, que fornece uma camada de abstração sobre o SQLite para permitir um acesso mais robusto ao banco de dados, aproveitando toda a capacidade do SQLite.

Configurar dependências

Para configurar o SQLite no seu projeto KMP, adicione as dependências dos artefatos no arquivo build.gradle.kts do módulo:

Observação: o androidx.sqlite oferece suporte ao KMP na versão 2.5.0 ou mais recente.

[versions]
sqlite = "2.5.2"

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

APIs do driver SQLite

Os grupos de bibliotecas androidx.sqlite oferecem APIs de baixo nível para comunicação com a biblioteca SQLite incluída na biblioteca ao usar androidx.sqlite:sqlite-bundled ou na plataforma host, como Android ou iOS, ao usar androidx.sqlite:sqlite-framework. As APIs seguem de perto a funcionalidade principal da API C do SQLite.

Há três interfaces principais:

• SQLiteDriver: é o ponto de entrada para usar o SQLite e é responsável por abrir conexões de banco de dados.
• SQLiteConnection: é a representação do objeto sqlite3.
• SQLiteStatement: é a representação do objeto sqlite3_stmt.

O exemplo a seguir mostra as APIs principais:

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

Semelhante às APIs C do SQLite, o uso comum é:

• Abra uma conexão de banco de dados usando a implementação SQLiteDriver instanciada.
• Preparar uma instrução SQL usando SQLiteConnection.prepare()
• Execute um SQLiteStatement da seguinte maneira:
  1. Se quiser, vincule argumentos usando as funções bind*().
  2. Itere o conjunto de resultados usando a função step().
  3. Leia colunas do conjunto de resultados usando as funções get*().

Atenção: as conexões e instruções de banco de dados são recursos que precisam ser gerenciados. Todas as instruções preparadas precisam ser fechadas quando não forem mais necessárias. Da mesma forma, se uma conexão de banco de dados não for mais necessária, ela deverá ser fechada.

Implementações de drivers

A tabela a seguir resume as implementações de driver disponíveis:

Nome da turma	Artefato	Plataformas compatíveis
AndroidSQLiteDriver	androidx.sqlite:sqlite-framework	Android
NativeSQLiteDriver	androidx.sqlite:sqlite-framework	iOS, Mac e Linux
BundledSQLiteDriver	androidx.sqlite:sqlite-bundled	Android, iOS, Mac, Linux e JVM (computador)

A implementação recomendada é BundledSQLiteDriver, disponível em androidx.sqlite:sqlite-bundled. Ele inclui a biblioteca SQLite compilada da fonte, oferecendo a versão mais atualizada e consistência em todas as plataformas KMP compatíveis.

Driver SQLite e Room

As APIs de driver são úteis para interações de baixo nível com um banco de dados SQLite. Para uma biblioteca rica em recursos que oferece um acesso mais robusto ao SQLite, recomendamos o Room.

Um RoomDatabase depende de um SQLiteDriver para realizar operações de banco de dados, e uma implementação precisa ser configurada usando RoomDatabase.Builder.setDriver(). O Room oferece RoomDatabase.useReaderConnection e RoomDatabase.useWriterConnection para acesso mais direto às conexões gerenciadas de banco de dados.

Migrar para o Kotlin Multiplatform

Todo uso de chamadas SQLite de baixo nível precisa ser migrado para os equivalentes do driver SQLite.

Kotlin Multiplatform

Realizar uma transação usando SQLiteConnection de baixo nível

Observação: é sempre recomendável usar as APIs de transação RoomDatabase, já que elas permitem transações aninhadas e são mais seguras do que as APIs disponíveis em androidx.sqlite.

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

Executar uma consulta sem resultado

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

Executar uma consulta com resultado, mas sem argumentos

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

Executar uma consulta com resultado e argumentos

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

Somente Android

Realizar uma transação usando SupportSQLiteDatabase

Observação: é sempre recomendável usar as APIs de transação RoomDatabase, já que elas permitem transações aninhadas e são mais seguras do que as APIs disponíveis em androidx.sqlite.

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

Executar uma consulta sem resultado

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

Executar uma consulta com resultado, mas sem argumentos

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

Executar uma consulta com resultado e argumentos

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