Migrar de SQLite para Room

A biblioteca de persistência do Room oferece vários benefícios em comparação a usar as APIs SQLite diretamente.

  • Verificação de consultas SQL durante a compilação
  • Anotações de conveniência que minimizam o código boilerplate repetitivo e propenso a erros
  • Caminhos de migração de banco de dados simplificados

Se o app tiver uma implementação do SQLite que não seja o Room, leia esta página para saber como migrar para o Room. Se o Room for a primeira implementação do SQLite no seu app, consulte Salvar dados em um banco de dados local usando o Room para saber mais sobre o uso básico.

Etapas da migração

Siga as etapas abaixo para migrar a implementação do SQLite para Room. Caso a implementação do SQLite use um banco de dados grande ou consultas complexas, é possível migrar gradualmente para o Room. Para mais informações sobre uma estratégia de migração incremental, consulte Migração incremental.

Atualizar dependências

Para usar o Room no app, é necessário incluir as dependências adequadas no arquivo build.gradle do app. Para mais informações sobre as dependências do Room, consulte Configuração.

Atualizar classes de modelo para entidades de dados

O Room usa entidades de dados para representar as tabelas no banco de dados. Cada classe de entidade representa uma tabela e tem propriedades que representam colunas nessa tabela. Siga estas etapas para atualizar as classes de modelo atuais para serem entidades do Room:

  1. Adicione a anotação @Entity à declaração de classe para indicar que essa é uma entidade do Room. Opcionalmente, use a tableName propriedade para indicar que a tabela resultante precisa ter um nome diferente do nome da classe.
  2. Adicione a anotação @PrimaryKey à propriedade da chave primária.
  3. Se alguma das colunas na tabela resultante precisar ter um nome que seja diferente do nome da propriedade correspondente, adicione a anotação à propriedade com @ColumnInfo e defina a propriedade name com o nome da coluna correto.
  4. Se a classe tiver propriedades que você não quer manter no banco de dados, adicione a anotação @Ignore a essas propriedades para indicar que o Room não precisa criar colunas para elas na tabela correspondente.
  5. Se a classe tiver mais de um construtor, indique qual construtor o Room vai usar. Para isso, adicione a anotação @Ignore a todos os outros construtores.

@Entity(tableName = "users")
data class User(
    @PrimaryKey @ColumnInfo(name = "userid") val id: String,
    @ColumnInfo(name = "username") val userName: String?,
    @ColumnInfo(name = "last_update") val date: Date?,
)

Criar DAOs

O Room usa objetos de acesso a dados (DAOs, na sigla em inglês) para definir funções que acessam o banco de dados. Siga as orientações em Como acessar dados usando DAOs do Room para substituir as funções de consulta atuais por DAOs.

Criar uma classe de banco de dados

As implementações do Room usam uma classe de banco de dados para gerenciar uma instância do banco de dados. A classe de banco de dados precisa estender RoomDatabase e referenciar todas as entidades e DAOs definidos.

@Database(entities = [User::class], version = 2)
@ColumnTypeConverters(DateConverter::class)
abstract class UsersDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

Definir um caminho de migração

Como o número da versão do banco de dados está mudando, é necessário definir um Migration objeto para preservar os dados atuais do banco de dados. Se o esquema do banco de dados não mudar, essa migração poderá ficar vazia.

val MIGRATION_1_2 = object : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // Empty implementation, because the schema isn't changing.
    }
}

Para saber mais sobre os caminhos de migração de banco de dados no Room, consulte Migrar seu banco de dados.

Atualizar a instanciação do banco de dados

Depois de definir uma classe de banco de dados e um caminho de migração, você poderá usar Room.databaseBuilder para criar uma instância do banco de dados com o caminho de migração aplicado:

val db =
    Room.databaseBuilder<UsersDatabase>(applicationContext, "database-name")
        .addMigrations(MIGRATION_1_2)
        .build()

Testar a implementação

Teste sua nova implementação do Room:

Migração incremental

Se o app usar um banco de dados grande e complexo, talvez não seja possível migrar para o Room de uma só vez. Como alternativa, é possível começar implementando as entidades de dados e o banco de dados do Room e, mais tarde, migrar as funções de consulta para os DAOs.

Para implementar uma migração incremental, receba um wrapper de compatibilidade SupportSQLiteDatabase usando a função de extensão roomDatabase.getSupportWrapper do artefato androidx.room3:room3-sqlite-wrapper. Esse wrapper permite executar consultas SQL diretas no estilo Android no banco de dados gerenciado pelo Room usando as APIs SQLite do Android:

// Get SupportSQLiteDatabase wrapper
val legacyDb = roomDatabase.getSupportWrapper()
legacyDb.execSQL("INSERT INTO users ...")