Room: Was es ist, ORM-Bibliothek und Arbeiten mit SQLite

Was ist die Room ORM-Bibliothek?

Room ist eine ORM-Bibliothek aus Android Jetpack, die von Google entwickelt wurde, um die Arbeit mit lokalen SQLite-Datenbanken auf der Android-Plattform zu vereinfachen. Sie bietet Annotationen zur Beschreibung des Datenschemas und generiert automatisch DAO-Schnittstellenimplementierungen zur Compile-Zeit. Im Gegensatz zur direkten Verwendung von SQLiteOpenHelper befreit Room den Entwickler von der Notwendigkeit, eine erhebliche Menge an Boilerplate-Code zum Erstellen, Öffnen und Verwalten von Datenbankverbindungen zu schreiben.

Die Bibliothek wurde auf der Google I/O 2017 als Teil der Android-Architekturkomponenten vorgestellt. Seitdem ist Room zum De-facto-Standard für die lokale Datenspeicherung geworden und hat Lösungen wie GreenDAO und Realm für Android an Popularität übertroffen. Laut Google wird die Bibliothek in mehr als 60% der im Google Play veröffentlichten Anwendungen verwendet, die mit lokalen Daten auf dem Gerät arbeiten.

Das Hauptmerkmal ist die SQL-Abfragevalidierung zur Compile-Zeit mithilfe eines Annotationprozessors. Wenn ein Entwickler einen Fehler in einem SQL-Befehl macht, beispielsweise einen nicht vorhandenen Spaltennamen angibt, schlägt der Build vor der Installation der Anwendung mit einem Fehler fehl. Dies unterscheidet sich grundlegend vom SQLiteOpenHelper-Ansatz, bei dem solche Fehler erst zur Laufzeit, oft in der Produktion, erkannt werden.

TypeConverters für nicht standardisierte Typen

SQLite unterstützt nur fünf Datentypen: TEXT, INTEGER, REAL, BLOB und NULL. In Java und Kotlin werden jedoch komplexe Typen verwendet: Date, List, Enum und benutzerdefinierte Objekte. Zu ihrer Speicherung bietet Room den TypeConverters-Mechanismus — statische Methoden, die einen komplexen Typ in einen für SQLite verständlichen primitiven Typ konvertieren. Beispielsweise wird ein Date-Objekt in Long (Timestamp) und List<String> über Gson oder Moshi in einen JSON-String konvertiert.

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

val db = Room
    .databaseBuilder(context, AppDatabase::class.java, "app-db")
    .build()

Um einen Konverter zu deklarieren, fügen Sie einfach die @TypeConverter-Annotation zu einer statischen Methode hinzu und geben Sie die Konverterklasse in der @TypeConverters-Annotation auf Datenbankebene an. Room wendet den Konverter automatisch beim Lesen und Schreiben des entsprechenden Typs in jeder SQL-Abfrage an, ohne manuell Konvertierungsmethoden aufrufen zu müssen.

Room-Architektur: Drei Schlüsselkomponenten

Room besteht aus drei Hauptkomponenten: Entity, DAO und Database. Jede übernimmt eine streng definierte Rolle und wird mit der entsprechenden Annotation versehen. Zusammen bilden sie eine vollständige Datenzugriffsschicht, die die Geschäftslogik der Anwendung von den Implementierungsdetails von SQLite isoliert.

Entity — Datenbanktabelle

Entity ist eine Datenklasse, die die Struktur einer Tabelle in der Datenbank beschreibt. Jedes Feld der Klasse entspricht einer Tabellenspalte, und jede Zeile in der Datenbank entspricht einer Instanz der Klasse. Die @Entity-Annotation teilt Room mit, dass die Klasse eine Tabelle ist. Das Feld mit der @PrimaryKey-Annotation definiert den Primärschlüssel, der autoinkrementierend oder zusammengesetzt sein kann. @ForeignKey wird für Beziehungen zwischen Tabellen verwendet und gewährleistet die Datenintegrität auf Datenbankebene.

@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,
    @ColumnInfo(name = "full_name")
    val name: String,
    val age: Int,
    val email: String
)

DAO — Datenoperationen

DAO (Data Access Object) ist eine Schnittstelle oder abstrakte Klasse, die Operationen zum Arbeiten mit Daten deklariert: Einfügen, Lesen, Aktualisieren und Löschen. Jede Operation wird mit @Insert, @Query, @Update oder @Delete annotiert. Room generiert automatisch die Implementierung dieser Schnittstelle zur Compile-Zeit. Die @Query-Annotation ist besonders wertvoll — sie akzeptiert eine SQL-Abfrage als String und validiert ihre Korrektheit zur Build-Zeit.

@Dao
interface UserDao {
    @Insert
    suspend fun insert(user: User): Long

    @Query("SELECT * FROM users WHERE id = :userId")
    suspend fun getUserById(userId: Int): User?

    @Query("SELECT * FROM users")
    fun getAllUsers(): Flow<List<User>>

    @Delete
    suspend fun delete(user: User)
}

Database — Einstiegspunkt

Database ist eine abstrakte Klasse, die RoomDatabase erweitert und als Einstiegspunkt in die Datenbank dient. Sie enthält eine Liste aller Entities und bietet abstrakte Methoden zum Abrufen von DAOs. Die Klasse wird mit @Database annotiert, das die Schema-Version und die Liste der Entitäten angibt. Die Datenbankinstanz wird über Room.databaseBuilder mit dem Anwendungskontext, dem Dateinamen und der Database-Klasse erstellt.

Wie Room intern mit SQLite arbeitet

Room ersetzt SQLite nicht, sondern arbeitet als Abstraktionsschicht darüber. Die interne Architektur umfasst einen Annotationprozessor, Codegenerator und Verbindungspool. Zur Compile-Zeit analysiert der Annotationprozessor die Entity-, DAO- und Database-Klassen und generiert dann Implementierungsklassen mit dem Suffix _Impl. Alle generierten Klassen werden im Build-Paket abgelegt und sind für den Entwickler nicht direkt sichtbar.

Die Codegenerierung zur Compile-Zeit ist der zentrale Mechanismus von Room. Für jede DAO-Schnittstelle wird eine Klasse mit der vollständigen Implementierung aller annotierten Methoden generiert. SQL-Abfragen aus der @Query-Annotation werden auf Korrektheit validiert: Der Prozessor gleicht Spaltennamen mit Entity-Feldern ab und überprüft die SQL-Syntax. Wenn ein Fehler gefunden wird, wird der Build mit einer klaren Nachricht unterbrochen. Dies ist bei der Verwendung von rohem SQLiteOpenHelper nicht möglich, wo Fehler erst zur Laufzeit auftreten.

Codegenerierung zur Compile-Zeit

Der Generierungsprozess umfasst drei Phasen. Erste — Schema-Validierung: Der Prozessor prüft, ob alle in @Database aufgelisteten Klassen gültige Entities sind. Zweite — DAO-Rumpfgenerierung: Für jede Methode wird eine Implementierung unter Verwendung des internen RoomSQLiteQuery-Objekts erstellt, das vorbereitete Abfragen ausführt. Dritte — Generierung der Database_Impl-Klasse, die die Datenbankerstellung und -öffnung sowie die Initialisierung aller DAO-Objekte übernimmt.

class UserDao_Impl(private val __db: RoomDatabase) : UserDao {
    private val __insertionAdapter = __db
        .createInsertionAdapter(User::class, 0)

    override suspend fun insert(user: User): Long {
        __db.assertNotSuspendingTransaction()
        return __db.runInTransaction {
            __insertionAdapter.insertAndReturnId(user)
        }
    }
}

Room erstellt keinen separaten Thread-Pool für Datenbankoperationen. Standardmäßig werden Abfragen im aufrufenden Thread mit einer Einschränkung ausgeführt: Lesen und Schreiben blockieren den Thread. Für asynchrone Arbeit integriert sich Room mit Kotlin-Koroutinen über Suspend-Funktionen, mit LiveData über Rückgabewerte und mit Flow über reaktive Wrapper. Dies gibt dem Entwickler die Flexibilität, die architektonische Lösung für eine bestimmte Aufgabe zu wählen.

Beispiel für die Verwendung von Room in einer Android-Anwendung

Betrachten wir ein praktisches Beispiel für die Erstellung einer Notizanwendung mit Room. Die Anwendung enthält eine Note-Tabelle mit den Feldern id, title, content und timestamp. Benutzer können Notizen hinzufügen, anzeigen und löschen. Für asynchrone Operationen werden Koroutinen verwendet.

Gradle-Abhängigkeiten einrichten

Um Room in ein Android-Projekt zu integrieren, fügen Sie Abhängigkeiten zur build.gradle-Datei auf Modulebene hinzu. Room erfordert drei Komponenten: die Laufzeitbibliothek, den kapt-Annotationprozessor und optionale Koroutinenunterstützung. Die Bibliotheksversion wird zur einfachen Aktualisierung in einer room_version-Variable angegeben. Ab Room 2.4.0 wird KSP als Alternative zu kapt mit schnelleren Build-Geschwindigkeiten unterstützt.

dependencies {
    def room_version = "2.6.1"
    implementation "androidx.room:room-runtime:$room_version"
    kapt "androidx.room:room-compiler:$room_version"
    implementation "androidx.room:room-ktx:$room_version"
    // Optional: Tests
    testImplementation "androidx.room:room-testing:$room_version"
}

Nach dem Einrichten der Abhängigkeiten erstellen Sie drei Dateien: die Note-Entity, das NoteDao-Interface und die AppDatabase-Klasse. Die Note-Entity enthält Felder mit @PrimaryKey- und @ColumnInfo-Annotationen. Das DAO bietet Methoden zum Einfügen, Abrufen der Liste und Löschen. Die Database verbindet die Entity und das DAO über die @Database-Annotation.

@Entity(tableName = "notes")
data class Note(
    @PrimaryKey(autoGenerate = true)
    val id: Int = 0,
    val title: String,
    val content: String,
    @ColumnInfo(name = "created_at")
    val timestamp: Long = System.currentTimeMillis()
)

@Dao
interface NoteDao {
    @Insert
    suspend fun insert(note: Note)

    @Query("SELECT * FROM notes ORDER BY created_at DESC")
    fun getAllNotes(): Flow<List<Note>>

    @Delete
    suspend fun delete(note: Note)
}

Die AppDatabase-Datei wird als abstrakte Klasse deklariert, die RoomDatabase erweitert. Die @Database-Annotation gibt alle Entities für die aktuelle Version und die Schema-Versionsnummer an. Zum Abrufen einer Instanz wird das Singleton-Muster über die build-Methode von Room.databaseBuilder mit dem Anwendungskontext verwendet. Das Zwischenspeichern der Datenbankinstanz verhindert mehrfache Erstellungen, die zu Speicherlecks führen könnten.

Datenbankmigrationen in Room

Migrationen in Room sind ein Mechanismus zum Ändern des Datenbankschemas bei einer Aktualisierung der Anwendung ohne Verlust vorhandener Daten. Wenn ein Benutzer eine neue Version mit geänderten Entities installiert, erkennt Room die Versionsabweichung und führt die angegebenen Migrationsschritte aus. Ohne eine Migration wird die Datenbank gelöscht und neu erstellt, was zum Verlust aller vom Benutzer gespeicherten Daten führt.

Eine Migration wird durch die Migration-Klasse beschrieben, die die Start- und Endversion der Datenbank übernimmt. Innerhalb der migrate-Methode wird eine SQL-Abfrage ALTER TABLE oder CREATE TABLE ausgeführt, um das Schema zu ändern. Room kann Schemaänderungen nicht automatisch erkennen — der Entwickler muss für jede Entity-Änderung manuell eine Migration schreiben. Ab Room 2.4.0 ist die experimentelle autoMigrations-Funktion zur automatischen Migrationsgenerierung verfügbar.

Automatische Migrationen mit autoMigrations

Die autoMigrations-Funktion ermöglicht es Room, Migrationen automatisch basierend auf Unterschieden zwischen Entity-Versionen zu generieren. Zur Verwendung fügen Sie einfach die @AutoMigration-Annotation zu @Database hinzu und aktivieren den Schema-Export nach JSON. Room vergleicht die Schemata benachbarter Versionen und generiert die erforderlichen ALTER-Abfragen. Allerdings unterstützt autoMigrations nur abwärtskompatible Änderungen: Hinzufügen von Spalten, Erstellen von Indizes und Ändern von Typen mit kompatiblen Transformationen.

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL(
            "ALTER TABLE users ADD COLUMN phone TEXT"
        )
    }
}

val db = Room
    .databaseBuilder(context, AppDatabase::class.java, "app-db")
    .addMigrations(MIGRATION_1_2)
    .build()

Für komplexe Änderungen wie das Umbenennen von Spalten oder das Zusammenführen von Tabellen ist eine manuelle Migration mit Zwischentabellen erforderlich. Ein typisches Szenario: Erstellen Sie eine temporäre Tabelle mit dem alten Schema, kopieren Sie Daten mit Transformationen von der alten in die neue Tabelle, löschen Sie die alte Tabelle und benennen Sie die temporäre um. Room garantiert, dass alle Migrationen in einer einzigen Transaktion ausgeführt werden, und bei einem Fehler werden die Änderungen vollständig zurückgesetzt.