Room 3.0

  
ספריית Room persistence מספקת שכבת הפשטה מעל SQLite כדי לאפשר גישה חזקה יותר למסד הנתונים, תוך ניצול מלוא העוצמה של SQLite.
העדכון האחרון גרסה יציבה גרסה מועמדת להפצה גרסת בטא גרסת אלפא
‫9 בספטמבר 2026 3.0.3 - - ‎3.1.0-alpha01

הצהרה על יחסי תלות

כדי להוסיף תלות ב-Room3, צריך להוסיף את מאגר Google Maven לפרויקט. מידע נוסף זמין במאמר בנושא מאגר Maven של Google.

אתם יכולים להוסיף את יחסי התלות של הארטיפקטים שאתם צריכים בקובץ build.gradle של האפליקציה או המודול:

Kotlin

dependencies {
    val room_version = "3.0.0"

    implementation("androidx.room3:room3-runtime:$room_version")
    ksp("androidx.room3:room3-compiler:$room_version")
}

Groovy

dependencies {
    def room_version = "3.0.0"

    implementation "androidx.room3:room3-runtime:$room_version"

    ksp "androidx.room3:room3-compiler:$room_version"
}

מידע על השימוש בפלאגין KSP זמין במדריך למתחילים של KSP.

מידע נוסף על יחסי תלות זמין במאמר הוספת יחסי תלות ב-build.

שימוש בפלאגין Room Gradle

אפשר להשתמש ב-Room Gradle Plugin כדי להגדיר אפשרויות עבור Room compiler. התוסף מגדיר את הפרויקט כך שהסכימות שנוצרות (שהן פלט של משימות ההידור ומשמשות להעברות אוטומטיות) מוגדרות בצורה נכונה כדי ליצור בנייה שניתן לשחזר ולשמור במטמון.

כדי להוסיף את הפלאגין, מגדירים את הפלאגין ואת הגרסה שלו בקובץ ה-build של Gradle ברמה העליונה.

מגניב

plugins {
    id 'androidx.room3' version "$room_version" apply false
}

Kotlin

plugins {
    id("androidx.room3") version "$room_version" apply false
}

בקובץ ה-build של Gradle ברמת המודול, מפעילים את הפלאגין ומשתמשים בתוסף room3.

מגניב

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

Kotlin

plugins {
    id("androidx.room3")
}

room3 {
    schemaDirectory("$projectDir/schemas")
}

חובה להגדיר schemaDirectory כשמשתמשים ב-Room Gradle Plugin. הפעולה הזו תגדיר את מהדר Room ואת משימות ההידור השונות ואת הקצוות העורפיים שלו (kotlinc, ‏ KSP) כך שקבצי הסכימה יופקו לתיקיות עם טעמים שונים, לדוגמה schemas/flavorOneDebug/com.package.MyDatabase/1.json. צריך להוסיף את הקבצים האלה למאגר כדי להשתמש בהם לאימות ולהעברות אוטומטיות.

משוב

המשוב שלכם עוזר לנו לשפר את Jetpack. נשמח לדעת אם גיליתם בעיות חדשות או אם יש לכם רעיונות איך לשפר את הספרייה הזו. כדאי לעיין בבעיות הידועות בספרייה הזו לפני שמדווחים על בעיה. כדי להוסיף הצבעה בדיווח על בעיה קיימת, לוחצים על כפתור הכוכב.

יצירת דיווח על בעיה חדשה

מידע נוסף זמין במאמרי העזרה בנושא Issue Tracker.

גרסה 3.1

גרסה ‎3.1.0-alpha01

‫9 בספטמבר 2026

‫androidx.room3:room3-*:3.1.0-alpha01 מופץ. גרסה ‎3.1.0-alpha01 מכילה את השמירות האלה.

שינויים ב-API

  • הוספנו את setConnectionPoolTimeout(timeout: Duration) ל-RoomDatabase.Builder כדי לאפשר הגדרה של הזמן הקצוב לתפוגה של מאגר החיבורים. (I24d07, b/404380974)
  • ההערות הבאות לגבי חדרים כוללות עכשיו את AnnotationTarget.PROPERTY: @ColumnInfo, ‏ @PrimaryKey, ‏ @Relation, ‏ @Embedded, ‏ @Ignore ו-@ColumnTypeConverters. בעקבות השינויים ב-API, חדרים הם 'מבוססי-מאפיינים' במקום 'מבוססי-שדות'. כלומר, עכשיו אפשר להשתמש ב-Room במאפיינים ללא שדות גיבוי כייצוג של עמודות ישויות או עמודות תוצאות של מחלקת נתונים של שאילתות. עדיין צריך להיות למאפיינים האלה getter שניתן לשימוש, וגם setter שניתן לשימוש או שהם צריכים להיות חלק מהבונה הראשי, כדי ש-Room יוכל להשתמש בהם בפונקציות של DAO. (I72058, b/438041176, b/521861812)

תיקוני באגים

  • תוקנה בעיה באינטרנט ובמנהלי התקנים מושעים שבה ביטול של קורוטינה במהלך טרנזקציה עלול לגרום למסד הנתונים ולחיבור להיכנס למצב לא תקין, ולמנוע שימוש נוסף. (If75c0, b/549860940)
  • תמיכה ב-Kotlin object הטמעה AutoMigrationSpec. (Id4077, b/215012591)
  • תוקנה רגרסיה שגרמה ל-Room להציג IllegalMonitorStateException כשמשתמשים בפונקציות של @Transaction wrapper DAO. (I996d9, ‏ b/543285472, ‏ b/553140228)
  • הוספנו תמיכה בהמרה מובנית של סוגי עמודות ל-kotlin.uuid.Uuid ב-Room. (Icca77, ‏ b/525093264)
  • מחולל הקוד של Kotlin ב-Room מדכא עכשיו את OPT_IN_USAGE_ERROR ואת OPT_IN_USAGE במחלקות _Impl שנוצרו, וכך מאפשר ל-DAO ול-Entities להשתמש בסוגים עם הערות @RequiresOptIn (כמו kotlin.uuid.Uuid) בלי לדרוש -opt-in ב-freeCompilerArgs. (I013bf, b/410607888)
  • שאילתות להשעיית חדר ופעולות של מעקב אחר ביטול תוקף יחזירו עכשיו את השגיאה IllegalStateException כשקוראים להן אחרי סגירת מסד הנתונים. (I5755a, b/543076356)
  • תוקן מצב של קיפאון שיכול להתרחש בפונקציות השעיה של @Transaction DAO wrapper שיבצעו החלפת הקשר והוגדר להן AndroidSQLiteDriver. (886ac5, b/543285472)
  • תיקון של println() מיותר במהלך העיבוד. תודה לסימון מרקיז! (b/532893031)
  • תוקנה בעיה שקשורה לשימושים אחרים במסד נתונים, שבהם טרנזקציה של מסד נתונים אחד משולבת עם טרנזקציה של מסד נתונים אחר, וגורמת להתנהגות לא מוגדרת. (b/437068912)

גרסה 3.0

גרסה 3.0.3

‫9 בספטמבר 2026

‫androidx.room3:room3-*:3.0.3 מופץ. גרסה 3.0.3 מכילה את השמירות האלה.

תיקוני באגים

  • תוקנה רגרסיה שגרמה ל-Room להציג IllegalMonitorStateException כשמשתמשים בפונקציות של @Transaction wrapper DAO. (I996d9, ‏ b/543285472, ‏ b/553140228)
  • תוקנה בעיה באינטרנט ובמנהלי התקנים מושעים שבה ביטול של קורוטינה במהלך טרנזקציה עלול לגרום למסד הנתונים ולחיבור להיכנס למצב לא תקין, ולמנוע שימוש נוסף. (If75c0, b/549860940)

גרסה 3.0.2

‫26 באוגוסט 2026

‫androidx.room3:room3-*:3.0.2 מופץ. גרסה 3.0.2 מכילה את השמירות האלה.

תיקוני באגים

  • שאילתות להשעיית חדר ופעולות של מעקב אחר ביטול תוקף יחזירו עכשיו את השגיאה IllegalStateException כשקוראים להן אחרי סגירת מסד הנתונים. (I5755a, b/543076356)
  • תוקן מצב של קיפאון שיכול להתרחש בפונקציות השעיה של @Transaction DAO wrapper שיבצעו החלפת הקשר והוגדר להן AndroidSQLiteDriver. (886ac5, b/543285472)

גרסה 3.0.1

‫29 ביולי 2026

‫androidx.room3:room3-*:3.0.1 מופץ. גרסה 3.0.1 מכילה את השמירות האלה.

תיקוני באגים

  • תיקון של println() מיותר במהלך העיבוד. תודה לסימון מרקיז! (b/532893031)
  • תוקנה בעיה שקשורה לשימושים אחרים במסד נתונים, שבהם טרנזקציה של מסד נתונים אחד משולבת עם טרנזקציה של מסד נתונים אחר, וגורמת להתנהגות לא מוגדרת. (b/437068912)

גרסה 3.0.0

‫1 ביולי 2026

‫androidx.room3:room3-*:3.0.0 מופץ. גרסה 3.0.0 מכילה את השמירות האלה.

התכונות העיקריות בגרסה 3.0.0:

‫Room 3.0 (חבילה androidx.room3) הוא עדכון גרסה משמעותי של חבילת Room 2.x (androidx.room) שמתמקד ב-Kotlin Multiplatform‏ (KMP).

ממשקי ה-API העיקריים של ההערות נשארו ללא שינוי, וגם הרכיבים העיקריים:

  • מחלקה מופשטת שמרחיבה את androidx.room3.RoomDatabase ומסומנת באנוטציה @Database היא נקודת הכניסה למעבד האנוטציות של Room.
  • בהצהרה על מסד הנתונים יש מחלקה אחת או יותר של נתונים שמתארות את סכימת מסד הנתונים ומסומנות בהערה @Entity.
  • פעולות במסד נתונים מוגדרות בהצהרות @Dao שמכילות פונקציות שאילתה שהצהרות ה-SQL שלהן מוגדרות באמצעות ההערה @Query.
  • בזמן הריצה, אפשר לקבל את ההטמעה של מסד הנתונים באמצעות RoomDatabase.Builder, שמשמש גם להגדרת מסד הנתונים.

רוב התיעוד במדריך שמירת נתונים במסד נתונים מקומי באמצעות Room עדיין רלוונטי ל-Room 3.0.

אלה ההבדלים העיקריים בין גרסה 2.x של Room לגרסאות החדשות יותר:

  • חבילה חדשה, androidx.room3.
  • ממשקי SupportSQLite API לא נתמכים יותר, אלא אם אתם משתמשים ב-androidx.room3:room3-sqlite-wrapper.
  • כל הפעולות במסד הנתונים מבוססות עכשיו על ממשקי Coroutine API.
  • יצירת קוד ב-Kotlin בלבד.
  • נדרש Kotlin Symbol Processing ‏ (KSP).

בנוסף לשינויים שעלולים לשבור את התאימות לאחור, גרסה Room 3.0 כוללת פונקציונליות חדשה בהשוואה לגרסה 2.x:

  • תמיכה ב-JS וב-WasmJS
  • סוגי החזרה של DAO בהתאמה אישית
  • תמיכה ב-FTS5 באמצעות הערה @Fts5
  • תמיכה בערך ברירת מחדל של פרמטר ב-Kotlin
  • מאפיין PrimaryKey.algorihtm כדי לציין את האלגוריתם ליצירת המפתח הראשי
  • אפשרות ליצור טבלאות 'WITHOUT ROWID'
  • עמודה עם קשר מורכב עם @Relation

חבילה חדשה

כדי למנוע בעיות תאימות עם הטמעות קיימות של Room 2.x ועם ספריות עם יחסי תלות טרנזיטיביים ב-Room (לדוגמה, WorkManager),‏ Room 3.0 נמצא בחבילה חדשה, מה שאומר שיש לו גם מזהי ארטיפקט וקבוצת Maven חדשים. לדוגמה, androidx.room:room-runtime הפך ל-androidx.room3:room3-runtime, ושיעורים כמו androidx.room.RoomDatabase נמצאים עכשיו בכתובת androidx.room3.RoomDatabase.

אין ממשקי API של SupportSQLite

גרסה 3.0 של Room נתמכת באופן מלא על ידי ממשקי ה-API של SQLiteDriver, ולא כוללת יותר הפניות לסוגים של SupportSQLite כמו SupportSQLiteDatabase או לסוגים של Android כמו Cursor. זהו השינוי המשמעותי ביותר בין גרסה 3.0 לגרסה 2.x של Room, מאז שממשקי ה-API של RoomDatabase שהיו זהים ל-SupportSQLiteDatabase, יחד עם ה-API לקבלת SupportSQLiteOpenHelper, הוסרו. עכשיו SQLiteDriver נדרש כדי ליצור RoomDatabase.

לדוגמה, ממשקי API לפעולות ישירות במסד נתונים מוחלפים במקבילות של מנהלי התקנים:

// Room 2.x
roomDatabase.runInTransaction { ... }

// Room 3.x
roomDatabase.withWriteTransaction { ... }

// Room 2.x
roomDatabase.query("SELECT * FROM Song").use { cursor -> ... }

// Room 3.x
roomDatabase.useReaderConnection { connection ->
  connection.usePrepared("SELECT * FROM Song") { stmt -> ... }
}

ממשקי Callback API שהיה להם ארגומנט SupportSQLiteDatabase הוחלפו גם הם בממשקי API מקבילים עם ארגומנט SQLiteConnection. אלה פונקציות קריאה חוזרת להעברות כמו Migration.onMigrate() ו-AutoMigrationSpec.onPostMigrate(), ופונקציות קריאה חוזרת למסדי נתונים כמו RoomDatabase.Callback.onCreate(), ‏ RoomDatabase.Callback.onOpen() וכו'.

אם נעשה שימוש ב-Room בפרויקט KMP, ההעברה לגרסה 3.0 פשוטה יותר כי היא כוללת בעיקר עדכון של הפניות לייבוא. אחרת, אותה אסטרטגיית העברה מ-Room ב-Android בלבד ל-KMP חלה. אפשר לעיין במדריך להעברה של Room KMP.

SupportSQLite Wrapper

ב-Room 3.x נשמרת העטיפה SupportSQLite שנוצרה ב-2.x כדי להקל על העברות, והיא ממוקמת עכשיו בארטיפקט חדש androidx.room3:room3-sqlite-wrapper. ‫Compatibility API מאפשר לכם להמיר RoomDatabase ל-SupportSQLiteDatabase. אפשר להחליף קריאות של roomDatabase.openHelper.writableDatabase בקריאות של roomDatabase.getSupportWrapper().

‫Kotlin and Coroutines First

כדי לשפר את הספרייה, גרסה 3.0 של Room יוצרת רק קוד Kotlin והיא רק מעבד סמלים של Kotlin‏ (KSP). בהשוואה ל-Room 2.x, אין יצירה של קוד Java, ואי אפשר יותר להגדיר מעבד אנוטציות (Annotation processor) באמצעות KAPT או JavaAP ב-Room 3.0. שימו לב ש-KSP יכול לעבד מקורות Java, והקומפיילר של Room ייצור קוד למסד נתונים, לישויות או ל-DAO שמצהירים על המקור שלהם ב-Java. מומלץ להשתמש בפרויקט מרובה מודולים שבו השימוש ב-Room מרוכז, ואפשר להחיל את Kotlin Gradle Plugin ו-KSP בלי להשפיע על שאר בסיס הקוד.

ב-Room 3.0 נדרש גם שימוש בקורוטינות, ובאופן ספציפי, פונקציות DAO צריכות להיות פונקציות השעיה, אלא אם הן מחזירות סוג תגובתי, כמו Flow או סוג החזרה של DAO בהתאמה אישית. ממשקי API של Room לביצוע פעולות במסד נתונים הם גם פונקציות השהיה, כמו RoomDatabase.useReaderConnection ו-RoomDatabase.useWriterConnection.

בניגוד ל-Room 2.x, אי אפשר יותר להגדיר RoomDatabase עם Executor, אלא אפשר לספק CoroutineContext יחד עם dispatcher באמצעות ה-builder של מסד הנתונים.

InvalidationTracker ממשקי ה-API בגרסה 3.0 של Room הם Flow,‏ InvalidationTracker.Observer מוסר יחד עם ממשקי ה-API הרלוונטיים שלו addObserver ו-removeObserver. המנגנון להגיב לפעולות במסד הנתונים הוא באמצעות Coroutine Flows שאפשר ליצור דרך createFlow() API ב-InvalidationTracker.

דוגמה לשימוש:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
    return db.invalidationTracker.createFlow("Artist").map { _ ->
        val artists = artistsDao.getAllArtists()
        val tours = tourService.fetchStates(artists.map { it.id })
        associateTours(artists, tours, from, to)
    }
}

תמיכה באינטרנט

בגרסה Room 3.0 נוספו JavaScript ו-WasmJs כיעדים של KMP. בנוסף לפרסום של ממשקי SQLiteDriver (androidx.sqlite:sqlite) שמטרגטים גם JavaScript ו-WasmJs, ולדרייבר חדש WebWorkerSQLiteDriver שנמצא בארטיפקט החדש androidx.sqlite:sqlite-web, אפשר להשתמש ב-Room בקוד משותף שמטרגט את כל הפלטפורמות העיקריות של KMP.

בגלל האופי האסינכרוני של פלטפורמות האינטרנט, ממשקי Room API שקיבלו את הארגומנט SQLiteStatement הם עכשיו פונקציות השהיה. דוגמאות לפונקציות האלה הן Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() ועוד. בממשקי ה-API של מנהלי ההתקנים, ממשקי ה-API האסינכרוניים נפוצים בכל הפלטפורמות, וממשקי ה-API הסינכרוניים נפוצים ביעדים שאינם באינטרנט. לכן, פרויקט שלא מטרגט את האינטרנט יכול להמשיך להשתמש בממשקי ה-API הסינכרוניים (SQLiteDriver.open(),‏ SQLiteConnection.prepare() ו-SQLiteStatement.step()) בקוד משותף. בינתיים, בפרויקט שמטרגט רק אתרים צריך להשתמש בממשקי ה-API האסינכרוניים (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() ו-SQLiteStatement.stepAsync()).

כדי להקל על השימוש, חבילת androidx.sqlite הוסיפה גם פונקציות להשהיית הרחבות עם השמות הסינכרוניים של ממשקי ה-API שצוינו (בתוספת SQLiteConnection.executeSQL). מומלץ להשתמש בממשקי ה-API האלה כשהפרויקט מיועד לפלטפורמות אינטרנט ולפלטפורמות אחרות, כי ממשקי ה-API הם הצהרות של expected / actual שיקראו לגרסה הנכונה על סמך הפלטפורמות. אלה ממשקי ה-API שזמן הריצה של Room משתמש בהם, והם מאפשרים שימוש במנהל התקן בקוד משותף לכל הפלטפורמות הנתמכות.

דוגמה לשימוש:

import androidx.sqlite.executeSQL
import androidx.sqlite.step

roomDatabase.useWriterConnection { connection ->
    val deletedSongs = connection.usePrepared(
        "SELECT count(*) FROM Song"
    ) { stmt ->
        stmt.step()
        stmt.getLong(0)
    }
    connection.executeSQL("DELETE FROM Song")
    deletedSongs
}

‫WebWorkerSQLiteDriver הוא הטמעה של SQLiteDriver שמתקשר עם Web Worker כדי לבצע פעולות במסד הנתונים מחוץ לשרשור הראשי, ומאפשר לאחסן את מסד הנתונים במערכת הקבצים הפרטית של המקור (OPFS). כדי ליצור מופע של ה-driver, צריך worker שמטמיע פרוטוקול תקשורת פשוט. הפרוטוקול מתואר ב-WebWorkerSQLiteDriver KDoc.

בשלב הזה, WebWorkerSQLiteDriver לא מגיע עם worker שמוגדר כברירת מחדל ומיישם את פרוטוקול התקשורת, אבל לדוגמה, בבסיס הקוד של androidx יש יישום של worker שאפשר להשתמש בו בפרויקט. הוא משתמש ב-WASM של SQLite ומאחסן את מסד הנתונים ב-OPFS. ה-Worker לדוגמה מתפרסם כחבילת NPM מקומית, ובזכות התמיכה של Kotlin בהסתמכויות על NPM, אפשר ליצור מודול KMP קטן שישמש את ה-Worker.

אפשר לעיין בפרויקט GitHub הבא כדי לראות איך משתמשים ב-web worker מקומי ל-Room.

אחרי שמגדירים את העובד בפרויקט, ההגדרה של Room for the Web דומה להגדרה בפלטפורמות אחרות:

fun createDatabase(): MusicDatabase {
    return Room.databaseBuilder<MusicDatabase>("music.db")
        .setDriver(WebWorkerSQLiteDriver(createWorker()))
        .build()
}

fun createWorker() =
    Worker(js("""new URL("sqlite-web-worker/worker.js", import.meta.url)"""))

יכול להיות שגרסה עתידית של Web driver תכיל worker שפורסם ב-NPM כברירת מחדל, וכך תהליך ההגדרה של האינטרנט יהיה פשוט יותר.

סוגי החזרה של DAO בהתאמה אישית

שילובים שונים של סוגי החזרה של DAO, כמו אלה של RxJava ו-Paging, עברו שינוי לשימוש ב-API חדש ב-Room 3.0 שנקרא DAO return type converters (ממירים של סוגי החזרה של DAO). פונקציית המרה של סוג החזרה של DAO ‏ (@DaoReturnTypeConverter) מאפשרת להמיר את התוצאה של פונקציית DAO לסוג מותאם אישית שהוגדר על ידי הפונקציה עם ההערה. הפונקציות האלה מאפשרות להשתתף בקוד שנוצר ב-Room, שממיר תוצאות של שאילתות לאובייקטים של נתונים. צריך לרשום מחלקות שמכילות המרות של סוגי החזרה של DAO באמצעות ההערות @DaoReturnTypeConverters בהצהרות @Database או @Dao.

לדוגמה, כדי ששאילתת DAO תחזיר PagingSource, צריך לרשום את מחלקת ההמרה שנמצאת ב-androidx.room3:room3-paging:

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song)
    fun getSongsPaginated(): PagingSource<Int, Song>
}

השילובים הקיימים הועברו לממירים של סוג ההחזרה של DAO:

סוג הערך שמוחזר מחלקה של משתמשים שביצעו המרה פריט מידע שנוצר בתהליך פיתוח (Artifact)
PagingSource PagingSourceDaoReturnTypeConverter androidx.room3:room3-paging
Observable, ‏ Flowable, ‏ Completable, ‏ Single, ‏ Maybe RxDaoReturnTypeConverters androidx.room3:room3-rxjava3
ListenableFuture GuavaDaoReturnTypeConverter androidx.room3:room3-guava
LiveData LiveDataDaoReturnTypeConverter androidx.room3:room3-livedata

בדומה לממירים של סוגי עמודות, אפשר להגדיר ממירים של סוגי החזרה של DAO באמצעות האפליקציה. לדוגמה, אפליקציה יכולה להצהיר על @DaoReturnTypeConverter לסוג האינטרנט kotlin.js.Promise.

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

לאחר מכן, הכלי להמרה שלמעלה מאפשר לפונקציות של שאילתות DAO להחזיר Promise:

@Dao
@DaoReturnTypeConverters(PromiseDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song")
    fun getAllSongs(): Promise<List<Song>>
}

יש כמה דרישות לגבי פונקציית @DaoReturnTypeConverter, למשל מספר הפרמטרים והסוגים שלהם. הפרמטרים האפשריים הם:

  • ‫db: RoomDatabase: (אופציונלי) מספק גישה למופע RoomDatabase instance, שיכול להיות שימושי לביצוע פעולות נוספות במסד הנתונים או לגישה להיקף של שגרת המשך (coroutine).
  • ‫tableNames: Array<String>: (אופציונלי) מכיל את הטבלאות שאליהן ניגשת השאילתה. שימושי לתמיכה בסוגים שניתנים לצפייה או תגובתיים בשילוב עם InvalidationTracker.createFlow() API של Room.
  • ‫rawQuery: RoomRawQuery: (אופציונלי) מכיל בזמן הריצה מופע של השאילתה, שמאפשר טרנספורמציות כמו האסטרטגיה LIMIT / OFFSET שהוטמעה על ידי PagingSourceDaoReturnTypeConverter.
  • ‫executeAndConvert: suspend () -> T: (חובה) הפונקציה ש-Room יצר, שתבצע את השאילתה ותנתח את התוצאה שלה לאובייקטים של נתונים.

מידע נוסף על הדרישות ליצירת ממיר מסוג החזרה של DAO זמין ב-KDoc בנושא @DaoReturnTypeConverterAPI.

גרסה ‎3.0.0-rc01

‫17 ביוני 2026

‫androidx.room3:room3-*:3.0.0-rc01 מופץ. גרסה ‎3.0.0-rc01 מכילה את השמירות האלה.

תכונות חדשות

  • הוספנו תמיכה בפרמטרים עם ערכי ברירת מחדל במחלקות נתונים שמשמשות בתוצאות של שאילתות DAO. מאפיין שמייצג עמודה ומהווה חלק מבונה עם ערך ברירת מחדל ייחשב כאופציונלי, ולא תהיה דרישה לעמודה בתוצאה. (34279a, b/70762008, b/193531601)

שינויים ב-API

  • משנים את השם של @TypeConverter ל-@ColumnTypeConverter כדי להבחין טוב יותר בהיקף ההמרה וכדי ליצור סימטריה עם @DaoReturnTypeConverter. (I24420, b/438041176)
  • הוספנו API לסוגי החזרה של DAO מותאמים אישית שסופקו @ProvidedDaoReturnTypeConveter. (I2a8ad, ‏ b/517485682)
  • נוסף המאפיין PrimaryKey.algorihtm כדי לציין את האלגוריתם ליצירת המפתח הראשי כשPrimaryKey.autoGenerate מוגדר כ-true. (I57944, ‏ b/70053837)

גרסה ‎3.0.0-alpha06

‫3 ביוני 2026

‫androidx.room3:room3-*:3.0.0-alpha06 מופץ. גרסה ‎3.0.0-alpha06 מכילה את השמירות האלה.

שינויים ב-API

  • מוסיפים מאפיין הערה חדש ב-@Entity בשם withoutRowId, שאם הוא מוגדר כ-true, יוצר את טבלת הגיבוי של SQLite באמצעות האפשרות WITHOUT ROWID. (Idb48e, ‏ b/472790803)

גרסה ‎3.0.0-alpha05

‫19 במאי 2026

‫androidx.room3:room3-*:3.0.0-alpha05 מופץ. גרסה ‎3.0.0-alpha05 מכילה את השמירות האלה.

שינויים ב-API

  • העדכונים @Relation ו-@Junction כך שהמאפיינים parentColumns ו-entityColumns הם מערך של שמות עמודות שישמשו כמפתחות לפתרון קשרים, וכך יתמכו במפתחות קשר מורכבים. ‫(I92196, ‏ b/64247765)

גרסה ‎3.0.0-alpha04

‫6 במאי 2026

‫androidx.room3:room3-*:3.0.0-alpha04 מופץ. גרסה ‎3.0.0-alpha04 מכילה את השמירות האלה.

שינויים ב-API

  • הוספת ממשקי API להגדרת מאגר החיבורים של החדר. אפשר להשתמש בפונקציות ליצירת setSingleConnectionPool() ו-setMultipleConnectionPool() כדי לשלוט בכמות המקסימלית של חיבורים ש-Room תפתח למסד הנתונים. ‫(I9700d, ‏ b/438041176, ‏ b/432820350)
  • הסרת החדר DatabaseConfiguration מ-API ציבורי, כי לא הייתה הפניה להגדרה הזו באף API ציבורי אחר. (I5f1e9, ‏ b/438041176)

תיקוני באגים

  • כדי להימנע מבעיות של 'מסד נתונים נעול' שמתעוררות ב-OPFS (b/496255935), צריך להגביל את יעדי האינטרנט לשימוש במאגר חיבורים יחיד.
  • ניסיון לתקן (שוב) שגיאה מסוג 'השיטה גדולה מדי' שמתרחשת בגלל ש-Room יוצר onValidateSchema גדול מדי. הפונקציה מחולקת לפי מספר ההצהרות, אבל המדידה לא מדויקת. אם השגיאה הזו עדיין מופיעה, אפשר לשנות את מספר ההצהרות ש-Room יספור לצורך פיצול באמצעות האפשרות room.validationSplitSize של מעבד אנוטציות (Annotation processor). ערך ברירת המחדל הוא כרגע 300 הצהרות, לכן אם הבעיה עדיין קיימת, צריך להשתמש במספר נמוך יותר (b/493708172).

גרסה ‎3.0.0-alpha03

‫8 באפריל 2026

‫androidx.room3:room3-*:3.0.0-alpha03 מופץ. גרסה ‎3.0.0-alpha03 מכילה את השמירות האלה.

שינויים ב-API

  • כדי למנוע אזהרת Lint כשמתבצעת הפניה לקונסטרוקטור בהצהרה @Database, צריך להגדיר את הקונסטרוקטור ללא ארגומנטים של RoomDatabase כציבורי. (I9bac2, ‏ b/494722261)
  • מוסיפים גרסה של Room.inMemoryDatabaseBuilder ושל Room.databaseBuilder שלא מקבלת הקשר של Android. הצורך בהקשר פחת מאוד ב-Room 3.0, ולכן הפיכת הערך הזה לאופציונלי ב-Builder מאפשרת ליצור מסדי נתונים בזיכרון בקוד משותף בקלות רבה יותר. (I5d502, b/438041176)

תיקוני באגים

  • תוקנה שגיאה מסוג 'הקוד גדול מדי' בקוד שנוצר ב-JVM וב-Android, כשהגוף של הפונקציה onValidateSchema היה גדול מדי (b/493708172).

גרסה ‎3.0.0-alpha02

‫25 במרץ 2026

‫androidx.room3:room3-*:3.0.0-alpha02 מופץ. גרסה ‎3.0.0-alpha02 מכילה את השמירות האלה.

תכונות חדשות

  • תמיכה ב-FTS5: נוספה תמיכה ב-FTS5 ל-Room באמצעות ההערה @Fts5. העדכון כולל קבועים חדשים ל-tokenizers של FTS5 ‏ (TOKENIZER_ASCII ו-TOKENIZER_TRIGRAM) וסוג enum לאפשרות FTS ‏ 'detail' ‏ (FULL,‏ COLUMN ו-NONE). (I90934,‏ b/146824830)
  • יעדים להעברת דפים בחדר: נוספו היעדים js,‏ wasmJs,‏ tvOS ו-watchOS אל room3-paging. (Icffd3, ‏ b/432783733)

שינויים ב-API

  • Multi-platform clearAllTables(): Commonized clearAllTables(), making it available across all platforms. היא גם הומרה לפונקציה suspend. (I434ae, ‏ b/322846465)
  • העברה הרסנית: נוסף ערך ברירת מחדל לפרמטר dropAllTables בממשקי ה-API של fallbackToDestructiveMigration. (Ica88b, b/438041176)

  • שינויים ניסיוניים ב-API:

    1. העברנו את @ExperimentalRoomApi אל room-common כדי לאפשר סימון של ממשקי API מבוססי-הערות כניסיוניים.

    2. נוסף RoomWarning ניסיוני כדי לבטל את הדרישה ל-@ConstructedBy בהצהרה של מסד נתונים של Room. במקרה כזה, לא ייווצר DatabaseConstructor, ותצטרכו לספק הטמעה של הגדרות היצרן דרך DatabaseBuilder. (If5443)

תיקוני באגים

  • מקור הדפדוף: בוצע עדכון של PagingSourceDaoReturnTypeConverter כדי לציין בצורה נכונה שפונקציית ההמרה שלו מיועדת לשאילתות READ. (I3b067, b/139872302)

גרסה ‎3.0.0-alpha01

‫11 במרץ 2026

‫androidx.room3:room3-*:3.0.0-alpha01 מופץ.

‫Room 3.0 (חבילה androidx.room3) הוא עדכון גרסה משמעותי של חבילת Room 2.x (androidx.room) שמתמקד ב-Kotlin Multiplatform‏ (KMP).

ממשקי ה-API העיקריים של ההערות נשארו ללא שינוי, וגם הרכיבים העיקריים:

  • מחלקה מופשטת שמרחיבה את androidx.room3.RoomDatabase ומסומנת באנוטציה @Database היא נקודת הכניסה למעבד האנוטציות של Room.
  • בהצהרה על מסד הנתונים יש מחלקה אחת או יותר של נתונים שמתארות את סכימת מסד הנתונים ומסומנות בהערה @Entity.
  • פעולות במסד נתונים מוגדרות בהצהרות @Dao שמכילות פונקציות שאילתה שהצהרות ה-SQL שלהן מוגדרות באמצעות ההערה @Query.
  • בזמן הריצה, אפשר לקבל את ההטמעה של מסד הנתונים באמצעות RoomDatabase.Builder, שמשמש גם להגדרת מסד הנתונים.

רוב התיעוד במדריך שמירת נתונים במסד נתונים מקומי באמצעות Room עדיין רלוונטי ל-Room 3.0.

אלה ההבדלים העיקריים בין גרסה 2.x של Room לגרסאות החדשות יותר:

  • חבילה חדשה, androidx.room3.
  • ממשקי SupportSQLite API לא נתמכים יותר, אלא אם אתם משתמשים ב-androidx.room3:room3-sqlite-wrapper.
  • כל הפעולות במסד הנתונים מבוססות עכשיו על ממשקי Coroutine API.
  • יצירת קוד ב-Kotlin בלבד.
  • נדרש Kotlin Symbol Processing ‏ (KSP).

בנוסף לשינויים שעלולים לשבור את התאימות לאחור, גרסה Room 3.0 כוללת פונקציונליות חדשה בהשוואה לגרסה 2.x:

  • תמיכה ב-JS וב-WasmJS
  • סוגי החזרה של DAO בהתאמה אישית

חבילה חדשה

כדי למנוע בעיות תאימות עם הטמעות קיימות של Room 2.x ועם ספריות עם יחסי תלות טרנזיטיביים ב-Room (לדוגמה, WorkManager),‏ Room 3.0 נמצא בחבילה חדשה, מה שאומר שיש לו גם מזהי ארטיפקט וקבוצת Maven חדשים. לדוגמה, androidx.room:room-runtime הפך ל-androidx.room3:room3-runtime, ושיעורים כמו androidx.room.RoomDatabase נמצאים עכשיו בכתובת androidx.room3.RoomDatabase.

אין ממשקי API של SupportSQLite

גרסה 3.0 של Room נתמכת באופן מלא על ידי ממשקי ה-API של SQLiteDriver, ולא כוללת יותר הפניות לסוגים של SupportSQLite כמו SupportSQLiteDatabase או לסוגים של Android כמו Cursor. זהו השינוי המשמעותי ביותר בין גרסה 3.0 לגרסה 2.x של Room, מאז שממשקי ה-API של RoomDatabase שהיו זהים ל-SupportSQLiteDatabase, יחד עם ה-API לקבלת SupportSQLiteOpenHelper, הוסרו. עכשיו SQLiteDriver נדרש כדי ליצור RoomDatabase.

לדוגמה, ממשקי API לפעולות ישירות במסד נתונים מוחלפים במקבילות של מנהלי התקנים:

// Room 2.x
roomDatabase.runInTransaction { ... }

// Room 3.x
roomDatabase.withWriteTransaction { ... }

// Room 2.x
roomDatabase.query("SELECT * FROM Song").use { cursor -> ... }

// Room 3.x
roomDatabase.useReaderConnection { connection ->
  connection.usePrepared("SELECT * FROM Song") { stmt -> ... }
}

ממשקי Callback API שהיה להם ארגומנט SupportSQLiteDatabase הוחלפו גם הם בממשקי API מקבילים עם ארגומנט SQLiteConnection. אלה פונקציות קריאה חוזרת להעברות כמו Migration.onMigrate() ו-AutoMigrationSpec.onPostMigrate(), ופונקציות קריאה חוזרת למסדי נתונים כמו RoomDatabase.Callback.onCreate(), ‏ RoomDatabase.Callback.onOpen() וכו'.

אם נעשה שימוש ב-Room בפרויקט KMP, ההעברה לגרסה 3.0 פשוטה יותר כי היא כוללת בעיקר עדכון של הפניות לייבוא. אחרת, אותה אסטרטגיית העברה מ-Room ב-Android בלבד ל-KMP חלה. אפשר לעיין במדריך להעברה של Room KMP.

SupportSQLite Wrapper

ב-Room 3.x נשמרת העטיפה SupportSQLite שנוצרה ב-2.x כדי להקל על העברות, והיא ממוקמת עכשיו בארטיפקט חדש androidx.room3:room3-sqlite-wrapper. ‫Compatibility API מאפשר לכם להמיר RoomDatabase ל-SupportSQLiteDatabase. אפשר להחליף קריאות של roomDatabase.openHelper.writableDatabase בקריאות של roomDatabase.getSupportWrapper().

‫Kotlin and Coroutines First

כדי לשפר את הספרייה, גרסה 3.0 של Room יוצרת רק קוד Kotlin והיא רק מעבד סמלים של Kotlin‏ (KSP). בהשוואה ל-Room 2.x, אין יצירה של קוד Java, ואי אפשר יותר להגדיר מעבד אנוטציות (Annotation processor) באמצעות KAPT או JavaAP ב-Room 3.0. שימו לב ש-KSP יכול לעבד מקורות Java, והקומפיילר של Room ייצור קוד למסד נתונים, לישויות או ל-DAO שמצהירים על המקור שלהם ב-Java. מומלץ להשתמש בפרויקט מרובה מודולים שבו השימוש ב-Room מרוכז, ואפשר להחיל את Kotlin Gradle Plugin ו-KSP בלי להשפיע על שאר בסיס הקוד.

ב-Room 3.0 נדרש גם שימוש בקורוטינות, ובאופן ספציפי, פונקציות DAO צריכות להיות פונקציות השעיה, אלא אם הן מחזירות סוג תגובתי, כמו Flow או סוג החזרה של DAO בהתאמה אישית. ממשקי API של Room לביצוע פעולות במסד נתונים הם גם פונקציות השהיה, כמו RoomDatabase.useReaderConnection ו-RoomDatabase.useWriterConnection.

בניגוד ל-Room 2.x, אי אפשר יותר להגדיר RoomDatabase עם Executor, אלא אפשר לספק CoroutineContext יחד עם dispatcher באמצעות ה-builder של מסד הנתונים.

InvalidationTracker ממשקי ה-API בגרסה 3.0 של Room הם Flow,‏ InvalidationTracker.Observer מוסר יחד עם ממשקי ה-API הרלוונטיים שלו addObserver ו-removeObserver. המנגנון להגיב לפעולות במסד הנתונים הוא באמצעות Coroutine Flows שאפשר ליצור דרך createFlow() API ב-InvalidationTracker.

דוגמה לשימוש:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
    return db.invalidationTracker.createFlow("Artist").map { _ ->
        val artists = artistsDao.getAllArtists()
        val tours = tourService.fetchStates(artists.map { it.id })
        associateTours(artists, tours, from, to)
    }
}

תמיכה באינטרנט

בגרסה Room 3.0 נוספו JavaScript ו-WasmJs כיעדים של KMP. בנוסף לפרסום של ממשקי SQLiteDriver (androidx.sqlite:sqlite) שמטרגטים גם JavaScript ו-WasmJs, ולדרייבר חדש WebWorkerSQLiteDriver שנמצא בארטיפקט החדש androidx.sqlite:sqlite-web, אפשר להשתמש ב-Room בקוד משותף שמטרגט את כל הפלטפורמות העיקריות של KMP.

בגלל האופי האסינכרוני של פלטפורמות האינטרנט, ממשקי Room API שקיבלו את הארגומנט SQLiteStatement הם עכשיו פונקציות השהיה. דוגמאות לפונקציות האלה הן Migration.onMigrate(), RoomDatabase.Callback.onCreate(), PooledConnection.usePrepared() ועוד. בממשקי ה-API של מנהלי ההתקנים, ממשקי ה-API האסינכרוניים נפוצים בכל הפלטפורמות, וממשקי ה-API הסינכרוניים נפוצים ביעדים שאינם באינטרנט. לכן, פרויקט שלא מטרגט את האינטרנט יכול להמשיך להשתמש בממשקי ה-API הסינכרוניים (SQLiteDriver.open(),‏ SQLiteConnection.prepare() ו-SQLiteStatement.step()) בקוד משותף. בינתיים, בפרויקט שמטרגט רק אתרים צריך להשתמש בממשקי ה-API האסינכרוניים (SQLiteDriver.openAsync(), SQLiteConnection.prepareAsync() ו-SQLiteStatement.stepAsync()).

כדי להקל על השימוש, חבילת androidx.sqlite הוסיפה גם פונקציות להשהיית הרחבות עם השמות הסינכרוניים של ממשקי ה-API שצוינו (בתוספת SQLiteConnection.executeSQL). מומלץ להשתמש בממשקי ה-API האלה כשהפרויקט מיועד לפלטפורמות אינטרנט ולפלטפורמות אחרות, כי ממשקי ה-API הם הצהרות של expected / actual שיקראו לגרסה הנכונה על סמך הפלטפורמות. אלה ממשקי ה-API שזמן הריצה של Room משתמש בהם, והם מאפשרים שימוש במנהל התקן בקוד משותף לכל הפלטפורמות הנתמכות.

דוגמה לשימוש:

import androidx.sqlite.executeSQL
import androidx.sqlite.step

roomDatabase.useWriterConnection { connection ->
    val deletedSongs = connection.usePrepared(
        "SELECT count(*) FROM Song"
    ) { stmt ->
        stmt.step()
        stmt.getLong(0)
    }
    connection.executeSQL("DELETE FROM Song")
    deletedSongs
}

‫WebWorkerSQLiteDriver הוא הטמעה של SQLiteDriver שמתקשר עם Web Worker כדי לבצע פעולות במסד הנתונים מחוץ לשרשור הראשי, ומאפשר לאחסן את מסד הנתונים במערכת הקבצים הפרטית של המקור (OPFS). כדי ליצור מופע של ה-driver, צריך worker שמטמיע פרוטוקול תקשורת פשוט. הפרוטוקול מתואר ב-WebWorkerSQLiteDriver KDoc.

בשלב הזה, WebWorkerSQLiteDriver לא מגיע עם worker שמוגדר כברירת מחדל ומיישם את פרוטוקול התקשורת, אבל לדוגמה, בבסיס הקוד של androidx יש יישום של worker שאפשר להשתמש בו בפרויקט. הוא משתמש ב-WASM של SQLite ומאחסן את מסד הנתונים ב-OPFS. ה-Worker לדוגמה מתפרסם כחבילת NPM מקומית, ובזכות התמיכה של Kotlin בהסתמכויות על NPM, אפשר ליצור מודול KMP קטן שישמש את ה-Worker.

אפשר לראות את הפרויקט הזה ב-GitHub שמדגים את השימוש ב-web worker מקומי ל-Room.

אחרי שמגדירים את העובד בפרויקט, ההגדרה של Room for the Web דומה להגדרה בפלטפורמות אחרות:

fun createDatabase(): MusicDatabase {
    return Room.databaseBuilder<MusicDatabase>("music.db")
        .setDriver(WebWorkerSQLiteDriver(createWorker()))
        .build()
}

fun createWorker() =
    Worker(js("""new URL("sqlite-web-worker/worker.js", import.meta.url)"""))

יכול להיות שגרסה עתידית של Web driver תכיל worker שפורסם ב-NPM כברירת מחדל, וכך תהליך ההגדרה של האינטרנט יהיה פשוט יותר.

סוגי החזרה של DAO בהתאמה אישית

שילובים שונים של סוגי החזרה של DAO, כמו אלה של RxJava ו-Paging, עברו שינוי לשימוש ב-API חדש ב-Room 3.0 שנקרא DAO return type converters (ממירים של סוגי החזרה של DAO). פונקציית המרה של סוג החזרה של DAO ‏ (@DaoReturnTypeConverter) מאפשרת להמיר את התוצאה של פונקציית DAO לסוג מותאם אישית שהוגדר על ידי הפונקציה עם ההערה. הפונקציות האלה מאפשרות להשתתף בקוד שנוצר ב-Room, שממיר תוצאות של שאילתות לאובייקטים של נתונים. צריך לרשום מחלקות שמכילות המרות של סוגי החזרה של DAO באמצעות ההערות @DaoReturnTypeConverters בהצהרות @Database או @Dao.

לדוגמה, כדי ששאילתת DAO תחזיר PagingSource, צריך לרשום את מחלקת ההמרה שנמצאת ב-androidx.room3:room3-paging:

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song)
    fun getSongsPaginated(): PagingSource<Int, Song>
}

השילובים הקיימים הועברו לממירים של סוג ההחזרה של DAO:

סוג הערך שמוחזר מחלקה של משתמשים שביצעו המרה פריט מידע שנוצר בתהליך פיתוח (Artifact)
PagingSource PagingSourceDaoReturnTypeConverter androidx.room3:room3-paging
Observable, ‏ Flowable, ‏ Completable, ‏ Single, ‏ Maybe RxDaoReturnTypeConverters androidx.room3:room3-rxjava3
ListenableFuture GuavaDaoReturnTypeConverter androidx.room3:room3-guava
LiveData LiveDataDaoReturnTypeConverter androidx.room3:room3-livedata

בדומה לממירים של סוגי עמודות, אפשר להגדיר ממירים של סוגי החזרה של DAO באמצעות האפליקציה. לדוגמה, אפליקציה יכולה להצהיר על @DaoReturnTypeConverter לסוג האינטרנט kotlin.js.Promise.

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

לאחר מכן, הכלי להמרה שלמעלה מאפשר לפונקציות של שאילתות DAO להחזיר Promise:

@Dao
@DaoReturnTypeConverters(PromiseDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song")
    fun getAllSongs(): Promise<List<Song>>
}

יש כמה דרישות לגבי פונקציית @DaoReturnTypeConverter, למשל מספר הפרמטרים והסוגים שלהם. הפרמטרים האפשריים הם:

  • ‫db: RoomDatabase: (אופציונלי) מספק גישה למופע RoomDatabase instance, שיכול להיות שימושי לביצוע פעולות נוספות במסד הנתונים או לגישה להיקף של שגרת המשך (coroutine).
  • ‫tableNames: Array<String>: (אופציונלי) מכיל את הטבלאות שאליהן ניגשת השאילתה. שימושי לתמיכה בסוגים שניתנים לצפייה או תגובתיים בשילוב עם InvalidationTracker.createFlow() API של Room.
  • ‫rawQuery: RoomRawQuery: (אופציונלי) מכיל בזמן הריצה מופע של השאילתה, שמאפשר טרנספורמציות כמו האסטרטגיה LIMIT / OFFSET שהוטמעה על ידי PagingSourceDaoReturnTypeConverter.
  • ‫executeAndConvert: suspend () -> T: (חובה) הפונקציה ש-Room יצר, שתבצע את השאילתה ותנתח את התוצאה שלה לאובייקטים של נתונים.

מידע נוסף על הדרישות ליצירת ממיר מסוג החזרה של DAO זמין ב-KDoc בנושא @DaoReturnTypeConverterAPI.