feat: support for specifying databaseId (#698)

lynnfield · Reedyuk · nbransby · web-flow · commit b484a6a642fa · 2025-08-19T21:31:38.000+03:00
This commit adds support for specifying the databaseId when creating a FirebaseFirestore instance.

This allows users to connect to a specific database within their Firebase project.

The `firestore` function now accepts an optional `databaseId` parameter. If not provided, it defaults to the default database for the project.

Additionally, the `NativeFirebaseFirestoreWrapper` now stores the databaseId and uses it when initializing the Firestore instance.

Co-authored-by: Andrew Reed &lt;andrew_reed@hotmail.com&gt;
Co-authored-by: Nicholas Bransby-Williams &lt;nbransby@gmail.com&gt;
diff --git a/firebase-firestore/api/android/firebase-firestore.api b/firebase-firestore/api/android/firebase-firestore.api
@@ -730,7 +730,8 @@ public final class dev/gitlive/firebase/firestore/_encodersKt {
 }
 
 public final class dev/gitlive/firebase/firestore/android {
-	public static final fun firestore (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;
+	public static final fun firestore (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;Ljava/lang/String;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;
+	public static synthetic fun firestore$default (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;Ljava/lang/String;ILjava/lang/Object;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;
 	public static final fun firestoreSettings (Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;Lkotlin/jvm/functions/Function1;)Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;
 	public static synthetic fun firestoreSettings$default (Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;
 	public static final fun getAndroid (Ldev/gitlive/firebase/firestore/CollectionReference;)Lcom/google/firebase/firestore/CollectionReference;
diff --git a/firebase-firestore/api/jvm/firebase-firestore.api b/firebase-firestore/api/jvm/firebase-firestore.api
@@ -730,7 +730,8 @@ public final class dev/gitlive/firebase/firestore/_encodersKt {
 }
 
 public final class dev/gitlive/firebase/firestore/android {
-	public static final fun firestore (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;
+	public static final fun firestore (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;Ljava/lang/String;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;
+	public static synthetic fun firestore$default (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;Ljava/lang/String;ILjava/lang/Object;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;
 	public static final fun firestoreSettings (Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;Lkotlin/jvm/functions/Function1;)Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;
 	public static synthetic fun firestoreSettings$default (Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;
 	public static final fun getAndroid (Ldev/gitlive/firebase/firestore/CollectionReference;)Lcom/google/firebase/firestore/CollectionReference;
diff --git a/firebase-firestore/src/androidMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt b/firebase-firestore/src/androidMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt
@@ -36,7 +36,8 @@ public val FirebaseFirestore.android: AndroidFirebaseFirestore get() = AndroidFi
 public actual val Firebase.firestore: FirebaseFirestore get() =
     FirebaseFirestore(AndroidFirebaseFirestore.getInstance())
 
-public actual fun Firebase.firestore(app: FirebaseApp): FirebaseFirestore = FirebaseFirestore(AndroidFirebaseFirestore.getInstance(app.android))
+public actual fun Firebase.firestore(app: FirebaseApp, databaseId: String?): FirebaseFirestore =
+    FirebaseFirestore(databaseId?.let { AndroidFirebaseFirestore.getInstance(app.android, databaseId) } ?: AndroidFirebaseFirestore.getInstance(app.android))
 
 public val LocalCacheSettings.android: AndroidLocalCacheSettings get() = when (this) {
     is LocalCacheSettings.Persistent -> androidPersistentCacheSettings {
diff --git a/firebase-firestore/src/androidMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt b/firebase-firestore/src/androidMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt
@@ -8,7 +8,7 @@ import dev.gitlive.firebase.firestore.android
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.tasks.await
 
-internal actual class NativeFirebaseFirestoreWrapper actual constructor(actual val native: NativeFirebaseFirestore) {
+internal actual class NativeFirebaseFirestoreWrapper actual constructor(actual val native: NativeFirebaseFirestore, actual val databaseId: String?) {
 
     actual fun collection(collectionPath: String) = native.collection(collectionPath)
 
diff --git a/firebase-firestore/src/commonMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt b/firebase-firestore/src/commonMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt
@@ -32,7 +32,7 @@ import kotlin.jvm.JvmName
 public expect val Firebase.firestore: FirebaseFirestore
 
 /** Returns the [FirebaseFirestore] instance of a given [FirebaseApp]. */
-public expect fun Firebase.firestore(app: FirebaseApp): FirebaseFirestore
+public expect fun Firebase.firestore(app: FirebaseApp, databaseId: String? = null): FirebaseFirestore
 
 internal expect class NativeFirebaseFirestore
 
diff --git a/firebase-firestore/src/commonMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt b/firebase-firestore/src/commonMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt
@@ -7,8 +7,9 @@ import dev.gitlive.firebase.firestore.NativeQuery
 import dev.gitlive.firebase.firestore.NativeTransaction
 import dev.gitlive.firebase.firestore.NativeWriteBatch
 
-internal expect class NativeFirebaseFirestoreWrapper internal constructor(native: NativeFirebaseFirestore) {
+internal expect class NativeFirebaseFirestoreWrapper internal constructor(native: NativeFirebaseFirestore, databaseId: String? = null) {
     val native: NativeFirebaseFirestore
+    val databaseId: String?
 
     fun collection(collectionPath: String): NativeCollectionReference
     fun collectionGroup(collectionId: String): NativeQuery
diff --git a/firebase-firestore/src/iosMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt b/firebase-firestore/src/iosMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt
@@ -25,8 +25,8 @@ public val FirebaseFirestore.ios: FIRFirestore get() = FIRFirestore.firestore()
 public actual val Firebase.firestore: FirebaseFirestore get() =
     FirebaseFirestore(FIRFirestore.firestore())
 
-public actual fun Firebase.firestore(app: FirebaseApp): FirebaseFirestore = FirebaseFirestore(
-    FIRFirestore.firestoreForApp(app.ios as objcnames.classes.FIRApp),
+public actual fun Firebase.firestore(app: FirebaseApp, databaseId: String?): FirebaseFirestore = FirebaseFirestore(
+    databaseId?.let { FIRFirestore.firestoreForApp(app.ios as objcnames.classes.FIRApp, it) } ?: FIRFirestore.firestoreForApp(app.ios as objcnames.classes.FIRApp),
 )
 
 public val LocalCacheSettings.ios: FIRLocalCacheSettingsProtocol get() = when (this) {
diff --git a/firebase-firestore/src/iosMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt b/firebase-firestore/src/iosMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt
@@ -9,7 +9,7 @@ import dev.gitlive.firebase.firestore.awaitResult
 import kotlinx.coroutines.runBlocking
 
 @Suppress("UNCHECKED_CAST")
-internal actual class NativeFirebaseFirestoreWrapper internal actual constructor(actual val native: NativeFirebaseFirestore) {
+internal actual class NativeFirebaseFirestoreWrapper internal actual constructor(actual val native: NativeFirebaseFirestore, actual val databaseId: String?) {
 
     actual fun collection(collectionPath: String) = native.collectionWithPath(collectionPath)
 
diff --git a/firebase-firestore/src/jsMain/kotlin/dev/gitlive/firebase/firestore/externals/firestore.kt b/firebase-firestore/src/jsMain/kotlin/dev/gitlive/firebase/firestore/externals/firestore.kt
@@ -81,7 +81,7 @@ public external fun getDocsFromCache(query: Query): Promise<QuerySnapshot>
 
 public external fun getDocsFromServer(query: Query): Promise<QuerySnapshot>
 
-public external fun getFirestore(app: FirebaseApp? = definedExternally): Firestore
+public external fun getFirestore(app: FirebaseApp? = definedExternally, databaseId: String? = definedExternally): Firestore
 
 public external fun increment(n: Int): FieldValue
 
diff --git a/firebase-firestore/src/jsMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt b/firebase-firestore/src/jsMain/kotlin/dev/gitlive/firebase/firestore/firestore.kt
@@ -33,9 +33,10 @@ import dev.gitlive.firebase.firestore.externals.WriteBatch as JsWriteBatch
 import dev.gitlive.firebase.firestore.externals.documentId as jsDocumentId
 
 public actual val Firebase.firestore: FirebaseFirestore get() =
-    rethrow { FirebaseFirestore(NativeFirebaseFirestoreWrapper(getApp())) }
+    rethrow { FirebaseFirestore(NativeFirebaseFirestoreWrapper(getApp(), null)) }
 
-public actual fun Firebase.firestore(app: FirebaseApp): FirebaseFirestore = rethrow { FirebaseFirestore(NativeFirebaseFirestoreWrapper(app.js)) }
+public actual fun Firebase.firestore(app: FirebaseApp, databaseId: String?): FirebaseFirestore =
+    rethrow { FirebaseFirestore(NativeFirebaseFirestoreWrapper(app.js, databaseId)) }
 
 internal actual data class NativeFirebaseFirestore(val js: JsFirestore)
 
diff --git a/firebase-firestore/src/jsMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt b/firebase-firestore/src/jsMain/kotlin/dev/gitlive/firebase/firestore/internal/NativeFirebaseFirestoreWrapper.kt
@@ -23,27 +23,30 @@ import kotlinx.coroutines.promise
 
 internal actual class NativeFirebaseFirestoreWrapper internal constructor(
     private val createNative: NativeFirebaseFirestoreWrapper.(FirebaseFirestoreSettings?) -> NativeFirebaseFirestore,
+    actual val databaseId: String?,
 ) {
 
-    internal actual constructor(native: NativeFirebaseFirestore) : this(
+    internal actual constructor(native: NativeFirebaseFirestore, databaseId: String?) : this(
         { settings ->
             settings?.let {
-                NativeFirebaseFirestore(initializeFirestore(native.js.app, settings))
+                NativeFirebaseFirestore(initializeFirestore(native.js.app, settings, databaseId))
             } ?: native
         },
+        databaseId,
     )
-    internal constructor(app: FirebaseApp) : this(
+    internal constructor(app: FirebaseApp, databaseId: String?) : this(
         { settings ->
             NativeFirebaseFirestore(
                 settings?.let {
-                    initializeFirestore(app, it.js).also {
+                    initializeFirestore(app, it.js, databaseId).also {
                         emulatorSettings?.run {
                             connectFirestoreEmulator(it, host, port)
                         }
                     }
-                } ?: getFirestore(app),
+                } ?: getFirestore(app, databaseId),
             )
         },
+        databaseId,
     )
 
     private data class EmulatorSettings(val host: String, val port: Int)

Original file line number	Diff line number	Diff line change
`@@ -730,7 +730,8 @@ public final class dev/gitlive/firebase/firestore/_encodersKt {`
`730`	`730`	`}`
`731`	`731`
`732`	`732`	`public final class dev/gitlive/firebase/firestore/android {`
`733`		`- public static final fun firestore (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;`
	`733`	`+ public static final fun firestore (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;Ljava/lang/String;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;`
	`734`	`+ public static synthetic fun firestore$default (Ldev/gitlive/firebase/Firebase;Ldev/gitlive/firebase/FirebaseApp;Ljava/lang/String;ILjava/lang/Object;)Ldev/gitlive/firebase/firestore/FirebaseFirestore;`
`734`	`735`	`public static final fun firestoreSettings (Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;Lkotlin/jvm/functions/Function1;)Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;`
`735`	`736`	`public static synthetic fun firestoreSettings$default (Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Ldev/gitlive/firebase/firestore/FirebaseFirestoreSettings;`
`736`	`737`	`public static final fun getAndroid (Ldev/gitlive/firebase/firestore/CollectionReference;)Lcom/google/firebase/firestore/CollectionReference;`
Original file line number	Diff line number	Diff line change
`@@ -25,8 +25,8 @@ public val FirebaseFirestore.ios: FIRFirestore get() = FIRFirestore.firestore()`
`25`	`25`	`public actual val Firebase.firestore: FirebaseFirestore get() =`
`26`	`26`	`FirebaseFirestore(FIRFirestore.firestore())`
`27`	`27`
`28`		`-public actual fun Firebase.firestore(app: FirebaseApp): FirebaseFirestore = FirebaseFirestore(`
`29`		`- FIRFirestore.firestoreForApp(app.ios as objcnames.classes.FIRApp),`
	`28`	`+public actual fun Firebase.firestore(app: FirebaseApp, databaseId: String?): FirebaseFirestore = FirebaseFirestore(`
	`29`	`+ databaseId?.let { FIRFirestore.firestoreForApp(app.ios as objcnames.classes.FIRApp, it) } ?: FIRFirestore.firestoreForApp(app.ios as objcnames.classes.FIRApp),`
`30`	`30`	`)`
`31`	`31`
`32`	`32`	`public val LocalCacheSettings.ios: FIRLocalCacheSettingsProtocol get() = when (this) {`