A biblioteca de persistência do Room oferece uma camada de abstração sobre o SQLite para permitir um acesso mais robusto ao banco de dados, aproveitando toda a capacidade do SQLite. Esta página se concentra no uso do Room em projetos do Kotlin Multiplatform (KMP). Para mais informações sobre como usar o Room, consulte Salvar dados em um banco de dados local usando o Room ou nossos exemplos oficiais.
Configurar dependências
Para configurar o Room no seu projeto do KMP, adicione as dependências dos artefatos no
arquivo build.gradle.kts do módulo do KMP.
Defina as dependências no arquivo libs.versions.toml:
[versions]
room3 = "3.1.0-alpha03"
sqlite = "2.7.1"
ksp = "<kotlinCompatibleKspVersion>"
[libraries]
androidx-sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "sqlite" }
androidx-room3-runtime = { module = "androidx.room3:room3-runtime", version.ref = "room3" }
androidx-room3-compiler = { module = "androidx.room3:room3-compiler", version.ref = "room3" }
# Optional SQLite Wrapper
androidx-room3-sqlite-wrapper = { module = "androidx.room3:room3-sqlite-wrapper", version.ref = "room3" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
androidx-room3 = { id = "androidx.room3", version.ref = "room3" }
Adicione o plug-in do Gradle para Room para configurar os esquemas do Room e o plug-in da KSP.
plugins {
alias(libs.plugins.ksp)
alias(libs.plugins.androidx.room3)
}
Adicione a dependência de ambiente de execução do Room e a biblioteca SQLite incluída:
commonMain.dependencies {
implementation(libs.androidx.room3.runtime)
implementation(libs.androidx.sqlite.bundled)
}
// Optional when using Room SQLite Wrapper
androidMain.dependencies {
implementation(libs.androidx.room3.sqlite.wrapper)
}
Adicione as dependências do KSP ao bloco root dependencies. É necessário adicionar
todos os destinos que o app usa. Para mais informações, consulte KSP com
Kotlin Multiplatform.
dependencies {
add("kspAndroid", libs.androidx.room3.compiler)
add("kspIosSimulatorArm64", libs.androidx.room3.compiler)
add("kspIosX64", libs.androidx.room3.compiler)
add("kspIosArm64", libs.androidx.room3.compiler)
// Add any other platform target you use in your project, for example kspDesktop
}
Defina o diretório do esquema do Room. Para mais informações, consulte Definir o local do esquema usando o plug-in do Gradle para Room.
room {
schemaDirectory("$projectDir/schemas")
}
Definir classes de banco de dados
Você precisa criar uma classe de banco de dados anotada com @Database, além de DAOs
e entidades dentro do conjunto de origem comum do módulo compartilhado do KMP. Colocar
essas classes em fontes comuns permite que elas sejam compartilhadas em todas as plataformas
de destino.
// shared/src/commonMain/kotlin/Database.kt @Database(entities = [TodoEntity::class], version = 1) @ConstructedBy(AppDatabaseConstructor::class) abstract class AppDatabase : RoomDatabase() { abstract fun getDao(): TodoDao } // The Room compiler generates the `actual` implementations. @Suppress("KotlinNoActualForExpect") expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase> { override fun initialize(): AppDatabase }
Quando você declara um objeto expect com a
interface RoomDatabaseConstructor, o compilador do Room gera as implementações
actual. O Android Studio pode emitir o seguinte aviso, que pode ser
suprimido com @Suppress("KotlinNoActualForExpect"):
Expected object 'AppDatabaseConstructor' has no actual declaration in module`
Em seguida, defina uma nova interface DAO ou mova uma que já existe para
commonMain:
// shared/src/commonMain/kotlin/TodoDao.kt @Dao interface TodoDao { @Insert suspend fun insert(item: TodoEntity) @Query("SELECT count(*) FROM TodoEntity") suspend fun count(): Int @Query("SELECT * FROM TodoEntity") fun getAllAsFlow(): Flow<List<TodoEntity>> }
Defina ou mova suas entidades para commonMain:
// shared/src/commonMain/kotlin/TodoEntity.kt @Entity data class TodoEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val title: String, val content: String )
Criar builders de banco de dados específicos para cada plataforma
É necessário definir um builder de banco de dados para instanciar o Room em cada plataforma. Essa é a única parte da API que você precisa definir em conjuntos de origem específicos da plataforma, devido a diferenças nas APIs do sistema de arquivos.
Android
No Android, geralmente você recebe o local do banco de dados usando a
API Context.getDatabasePath. Para criar a instância do banco de dados, especifique um
Context e o caminho do banco de dados.
// shared/src/androidMain/kotlin/Database.android.kt fun getDatabaseBuilder(context: Context): RoomDatabase.Builder<AppDatabase> { val appContext = context.applicationContext val dbFile = appContext.getDatabasePath("my_room.db") return Room.databaseBuilder<AppDatabase>( context = appContext, name = dbFile.absolutePath ) }
iOS
Para criar a instância do banco de dados no iOS, forneça um caminho de banco de dados usando o
NSFileManager, geralmente localizado no NSDocumentDirectory.
// shared/src/iosMain/kotlin/Database.ios.kt fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> { val dbFilePath = documentDirectory() + "/my_room.db" return Room.databaseBuilder<AppDatabase>( name = dbFilePath, ) } @OptIn(ExperimentalForeignApi::class) private fun documentDirectory(): String { val documentDirectory = NSFileManager.defaultManager.URLForDirectory( directory = NSDocumentDirectory, inDomain = NSUserDomainMask, appropriateForURL = null, create = false, error = null, ) return requireNotNull(documentDirectory?.path) }
JVM para computador
Para criar a instância do banco de dados, forneça um caminho de banco de dados usando as APIs Java ou Kotlin.
// shared/src/jvmMain/kotlin/Database.desktop.kt
fun getDatabaseBuilder(): RoomDatabase.Builder<AppDatabase> {
val dbFile = File(System.getProperty("java.io.tmpdir"), "my_room.db")
return Room.databaseBuilder<AppDatabase>(
name = dbFile.absolutePath,
)
}
Instanciar o banco de dados
Depois de receber o RoomDatabase.Builder de um dos construtores
específicos da plataforma, você pode configurar o restante do banco de dados do Room no código comum,
além da instanciação real do banco de dados.
// shared/src/commonMain/kotlin/Database.kt fun getRoomDatabase( builder: RoomDatabase.Builder<AppDatabase> ): AppDatabase { return builder .setDriver(BundledSQLiteDriver()) .setQueryCoroutineContext(Dispatchers.IO) .build() }
Selecione um driver SQLite
O snippet de código anterior chama a função de builder setDriver para definir qual
driver SQLite o banco de dados do Room precisa usar. Esses drivers variam de acordo com a
plataforma de destino. Os snippets de código anteriores usam o BundledSQLiteDriver.
É o driver recomendado que inclui o SQLite compilado da origem, que
fornece a versão mais consistente e atualizada do SQLite em todas as
plataformas.
Se você quiser usar o SQLite fornecido pelo SO, use a API setDriver nos
conjuntos de origem específicos da plataforma que especificam um driver específico da plataforma. Consulte
Implementações de driver para ver descrições das implementações de driver
disponíveis. Você pode usar uma das seguintes opções:
AndroidSQLiteDriveremandroidMainNativeSQLiteDriveremiosMain
Para usar o NativeSQLiteDriver, é necessário fornecer uma opção de vinculador -lsqlite3 para
que o app iOS seja vinculado dinamicamente ao SQLite do sistema.
// shared/build.gradle.kts
kotlin {
listOf(
iosX64(),
iosArm64(),
iosSimulatorArm64()
).forEach { iosTarget ->
iosTarget.binaries.framework {
baseName = "TodoApp"
isStatic = true
// Required when using NativeSQLiteDriver
linkerOpts.add("-lsqlite3")
}
}
}
Definir um contexto de corrotina
Um objeto RoomDatabase no Android pode ser configurado com executores de aplicativos compartilhados usando RoomDatabase.Builder.setQueryExecutor para realizar operações de banco de dados.
Como os executores não são compatíveis com o KMP, a API setQueryExecutor do Room não está
disponível em commonMain. Em vez disso, o objeto RoomDatabase precisa ser
configurado com um CoroutineContext, que pode ser definido usando
RoomDatabase.Builder.setCoroutineContext. Se você não definir um contexto, o
objeto RoomDatabase será padronizado como Dispatchers.IO.
Minificação e ofuscação
Se o projeto for minificado ou ofuscado, inclua a seguinte regra do ProGuard para que o Room possa encontrar a implementação gerada da definição do banco de dados:
-keep class * extends androidx.room3.RoomDatabase { <init>(); }
Migrar para o Kotlin Multiplatform
O Room foi desenvolvido originalmente como uma biblioteca do Android e depois migrado para o KMP com foco na compatibilidade de APIs. A versão do Room para KMP é um pouco diferente entre as plataformas e da versão específica para Android. Essas diferenças estão listadas e descritas a seguir.
Migrar do SQLite de suporte para o driver do SQLite
Todos os usos de SupportSQLiteDatabase e outras APIs em
androidx.sqlite.db precisam ser refatorados com as APIs do driver do SQLite,
porque as APIs em androidx.sqlite.db são exclusivas do Android (observe o
pacote diferente do pacote KMP).
Para garantir a compatibilidade com versões anteriores, e desde que o RoomDatabase esteja configurado
com um SupportSQLiteOpenHelper.Factory (por exemplo, nenhum SQLiteDriver está
definido), o Room se comporta no "modo de compatibilidade", em que as APIs Support SQLite e
SQLite Driver funcionam como esperado. Isso permite migrações incrementais para que
você não precise converter todos os usos do Support SQLite em driver do SQLite em uma
única mudança.
Usar o wrapper SQLite do Room
O artefato androidx.room3:room3-sqlite-wrapper fornece APIs para conectar
SQLiteDriver e SupportSQLiteDatabase durante a migração.
Para receber um SupportSQLiteDatabase de um RoomDatabase configurado com um
SQLiteDriver, use a nova função de extensão
RoomDatabase.getSupportWrapper. Esse wrapper de compatibilidade ajuda a manter
os usos atuais de SupportSQLiteDatabase, que você geralmente recebe de
RoomDatabase.openHelper.writableDatabase, ao adotar SQLiteDriver,
especialmente para bases de código com usos extensivos da API SupportSQLite que querem
usar BundledSQLiteDriver.
Converter subclasses de migração
As subclasses de migrações precisam ser migradas para as contrapartes do driver do SQLite:
Kotlin Multiplatform
Subclasses de migração
object Migration_1_2 : Migration(1, 2) { override suspend fun migrate(connection: SQLiteConnection) { // ... } }
Subclasses de especificação de migração automática
class AutoMigrationSpec_1_2 : AutoMigrationSpec { override suspend fun onPostMigrate(connection: SQLiteConnection) { // ... } }
Somente para Android
Subclasses de migração
object Migration_1_2 : Migration(1, 2) {
override fun migrate(db: SupportSQLiteDatabase) {
// …
}
}
Subclasses de especificação de migração automática
class AutoMigrationSpec_1_2 : AutoMigrationSpec {
override fun onPostMigrate(db: SupportSQLiteDatabase) {
// …
}
}
Converter callback do banco de dados
Os callbacks do banco de dados precisam ser migrados para os equivalentes do driver do SQLite:
Kotlin Multiplatform
object MyRoomCallback : RoomDatabase.Callback() { override suspend fun onCreate(connection: SQLiteConnection) { // ... } override suspend fun onDestructiveMigration(connection: SQLiteConnection) { // ... } override suspend fun onOpen(connection: SQLiteConnection) { // ... } }
Somente para Android
object MyRoomCallback : RoomDatabase.Callback() {
override fun onCreate(db: SupportSQLiteDatabase) {
// …
}
override fun onDestructiveMigration(db: SupportSQLiteDatabase) {
// …
}
override fun onOpen(db: SupportSQLiteDatabase) {
// …
}
}
Converter funções DAO de @RawQuery
As funções anotadas com @RawQuery que são compiladas para plataformas que não são Android
precisam declarar um parâmetro do tipo RoomRawQuery em vez de
SupportSQLiteQuery.
Kotlin Multiplatform
Definir a consulta bruta
@Dao interface TodoDao { @RawQuery suspend fun getTodos(query: RoomRawQuery): List<TodoEntity> }
Um RoomRawQuery pode ser usado para criar uma consulta no ambiente de execução:
suspend fun AppDatabase.getTodosWithLowercaseTitle(title: String): List<TodoEntity> { val query = RoomRawQuery( sql = "SELECT * FROM TodoEntity WHERE title = ?", onBindStatement = { it.bindText(1, title.lowercase()) } ) return getDao().getTodos(query) }
Somente para Android
Definir a consulta bruta
@Dao
interface TodoDao {
@RawQuery
suspend fun getTodos(query: SupportSQLiteQuery): List<TodoEntity>
}
Um SimpleSQLiteQuery pode ser usado para criar uma consulta no ambiente de execução:
suspend fun AndroidOnlyDao.getTodosWithLowercaseTitle(title: String): List<TodoEntity> {
val query = SimpleSQLiteQuery(
query = "SELECT * FROM TodoEntity WHERE title = ?",
bindArgs = arrayOf(title.lowercase())
)
return getTodos(query)
}
Converter funções de bloqueio do DAO
O Room se beneficia da biblioteca assíncrona kotlinx.coroutines,
que o Kotlin oferece para várias plataformas. Para uma funcionalidade ideal, as funções suspend
são aplicadas para DAOs compilados em um projeto KMP, com exceção de
DAOs implementados em androidMain para manter a compatibilidade com versões anteriores da
base de código atual. Ao usar o Room para KMP, todas as funções de DAO compiladas para
plataformas que não são Android precisam ser funções suspend.
Kotlin Multiplatform
Como suspender consultas
@Query("SELECT * FROM Todo") suspend fun getAllTodos(): List<Todo>
Suspender transações
@Transaction suspend fun transaction() { // ... }
Somente para Android
Consultas de bloqueio
@Query("SELECT * FROM Todo")
fun getAllTodos(): List<Todo>
Transações de bloqueio
@Transaction
fun blockingTransaction() { … }
Converter tipos reativos em Flow
Nem todas as funções do DAO precisam ser de suspensão. As funções DAO que retornam
tipos reativos, como LiveData ou Flowable do RxJava, não podem ser convertidas
em funções de suspensão. No entanto, alguns tipos, como LiveData, não são compatíveis com KMP. As funções DAO com tipos de retorno reativos precisam ser migradas para
fluxos de corrotina.
Kotlin Multiplatform
Tipos reativos Flows
@Query("SELECT * FROM Todo") fun getTodosFlow(): Flow<List<Todo>>
Somente para Android
Tipos reativos, como LiveData ou Flowable do RxJava
@Query("SELECT * FROM Todo")
fun getTodosLiveData(): LiveData<List<Todo>>
Converter APIs de transação
As APIs de transação de banco de dados para o Room KMP podem diferenciar entre transações de gravação
(useWriterConnection) e leitura (useReaderConnection).
Kotlin Multiplatform
val database: RoomDatabase = getRoomDatabase(builder) database.useWriterConnection { transactor -> transactor.immediateTransaction { // perform database operations in transaction. } }
Somente para Android
val database: RoomDatabase = …
database.withTransaction {
// perform database operations in transaction
}
Transações de gravação
Use transações de gravação para garantir que várias consultas gravem dados de forma atômica,
para que os leitores possam acessar os dados de forma consistente. Para isso, use
useWriterConnection com qualquer um dos três tipos de transação:
immediateTransaction: no modo de registro prévio de escrita (WAL, na sigla em inglês) (padrão), esse tipo de transação adquire um bloqueio quando é iniciado, mas os leitores podem continuar lendo. Essa é a opção preferida para a maioria dos casos.deferredTransaction: a transação não vai adquirir um bloqueio até a primeira instrução de gravação. Use esse tipo de transação como uma otimização quando não tiver certeza se uma operação de gravação será necessária dentro da transação. Por exemplo, se você iniciar uma transação para excluir músicas de uma playlist usando apenas o nome dela, e a playlist não existir, nenhuma operação de gravação (exclusão) será necessária.exclusiveTransaction: esse modo se comporta de maneira idêntica aimmediateTransactionno modo WAL. Em outros modos de registro, ele impede que outras conexões de banco de dados leiam o banco de dados enquanto a transação está em andamento.
Transações de leitura
Use transações de leitura para ler o banco de dados de forma consistente várias vezes. Por
exemplo, quando você tem duas ou mais consultas separadas e não usa uma cláusula
JOIN. Somente transações adiadas são permitidas em conexões de leitor. Tentar
iniciar uma transação imediata ou exclusiva em uma conexão de leitor vai gerar
uma exceção, já que elas são consideradas operações de "gravação".
val database: RoomDatabase = getRoomDatabase(builder) database.useReaderConnection { transactor -> transactor.deferredTransaction { // perform database operations in transaction. } }
Indisponível no Kotlin Multiplatform
Algumas das APIs que estavam disponíveis para Android não estão disponíveis no Kotlin Multiplatform.
Chamada de retorno de consulta
As APIs a seguir para configurar callbacks de consulta não estão disponíveis em comum e, portanto, não estão disponíveis em plataformas que não sejam o Android.
RoomDatabase.Builder.setQueryCallbackRoomDatabase.QueryCallback
Banco de dados de fechamento automático
A API para ativar o fechamento automático após um tempo limite,
RoomDatabase.Builder.setAutoCloseTimeout, está disponível apenas no Android.
Banco de dados pré-empacotado
As APIs a seguir para criar um RoomDatabase usando um banco de dados atual (um
banco de dados pré-empacotado) não estão disponíveis em comum e, portanto, não estão disponíveis em
plataformas que não sejam o Android:
RoomDatabase.Builder.createFromAssetRoomDatabase.Builder.createFromFileRoomDatabase.Builder.createFromInputStreamRoomDatabase.PrepackagedDatabaseCallback
Invalidação de várias instâncias
A API para ativar a invalidação de várias instâncias,
RoomDatabase.Builder.enableMultiInstanceInvalidation, está disponível apenas no
Android e não está disponível em plataformas comuns ou outras.
Recomendados para você
- Observação: o texto do link aparece quando o JavaScript está desativado.
- Codelab: Migrar apps atuais para o KMP do Room
- Codelab: Começar a usar o KMP
- Salvar dados no banco de dados local com o Room