FirebaseDataConnect
interface FirebaseDataConnect : AutoCloseable
Firebase Data Connect is Firebase's first relational database solution for app developers to build mobile and web applications using a fully managed PostgreSQL database powered by Cloud SQL.
See https://firebase.google.com/products/data-connect for full details about the Firebase Data Connect product.
GraphQL Schema and Operation Definition
The database schema and operations to query and mutate the data are authored in GraphQL and uploaded to the server. Then, the queries and mutations can be executed by name, providing variables along with the name to control their behavior. For example, a mutation that inserts a row into a "people" table could be named "InsertPerson" and require a variable for the person's name and a variable for the person's age. Similarly, a query to retrieve a row from the "person" table by its ID could be named "GetPersonById" and require a variable for the person's ID.
Usage with the Generated SDK
FirebaseDataConnect is the entry point to the Firebase Data Connect API; however, it is mostly intended to be an implementation detail for the code generated by Firebase's tools, which provide a type-safe API for running the queries and mutations. The generated classes and functions are colloquially referred to as the "generated SDK" and will encapsulate the API defined in this package. Applications are generally recommended to use the "generated SDK" rather than using this API directly to enjoy the benefits of a type-safe API.
Obtaining Instances
To obtain an instance of FirebaseDataConnect call FirebaseDataConnect.Companion.getInstance. If desired, when done with it, release the resources of the instance by calling FirebaseDataConnect.close. To connect to the Data Connect Emulator (rather than the production Data Connect service) call FirebaseDataConnect.useEmulator. To create QueryRef and MutationRef instances for running queries and mutations, call FirebaseDataConnect.query and FirebaseDataConnect.mutation, respectively. To enable debug logging, which is especially useful when reporting issues to Google, set FirebaseDataConnect.Companion.logLevel to LogLevel.DEBUG .
Integration with Kotlin Coroutines and Serialization
The Firebase Data Connect API is designed as a Kotlin-only API, and integrates tightly with Kotlin Coroutines and Kotlin Serialization. Applications should ensure that they depend on these two official Kotlin extension libraries and enable the Kotlin serialization Gradle plugin.
All blocking operations are exposed as suspend functions, which can be safely called from the main thread. Any blocking and/or CPU-intensive operations are moved off of the calling thread to a background dispatcher.
Data sent to the Data Connect server is serialized and data received from the Data Connect server is deserialized using Kotlin's Serialization framework. Applications will typically enable the official Kotlin Serialization Gradle plugin to automatically generate the serializers and deserializers for classes annotated with @Serializable. Of course, applications are free to write the serializers by hand as well.
Safe for Concurrent Use
All methods and properties of FirebaseDataConnect are thread-safe and may be safely called and/or accessed concurrently from multiple threads and/or coroutines.
Not Stable for Inheritance
The FirebaseDataConnect interface is not stable for inheritance in third-party libraries, as new methods might be added to this interface or contracts of the existing methods can be changed.
Summary
Nested types |
|---|
|
Indicates where the usages of this object are coming from. |
interface FirebaseDataConnect.MutationRefOptionsBuilder<Data : Any?, Variables : Any?>Options that can be specified when creating a |
interface FirebaseDataConnect.QueryRefOptionsBuilder<Data : Any?, Variables : Any?>Options that can be specified when creating a |
Public functions |
|
|---|---|
Unit |
close()Releases the resources of this object and removes the instance from the instance cache maintained by |
operator Boolean |
Compares this object with another object for equality, using the |
Int |
hashCode()Calculates and returns the hash code for this object. |
MutationRef<Data, Variables> |
<Data : Any?, Variables : Any?> mutation(Creates and returns a |
QueryRef<Data, Variables> |
<Data : Any?, Variables : Any?> query(Creates and returns a |
suspend Unit |
A version of |
String |
toString()Returns a string representation of this object, useful for debugging. |
Unit |
useEmulator(host: String, port: Int)Configure this |
Public properties |
|
|---|---|
FirebaseApp |
The |
ConnectorConfig |
The configuration of the Data Connect "connector" used to connect to the Data Connect service. |
DataConnectSettings |
The settings of this |
Public functions
close
fun close(): Unit
Releases the resources of this object and removes the instance from the instance cache maintained by FirebaseDataConnect.Companion.getInstance.
This method returns immediately, possibly before in-flight queries and mutations are completed. Any future attempts to execute queries or mutations returned from query or mutation will immediately fail. To wait for the in-flight queries and mutations to complete, call suspendingClose instead.
It is safe to call this method multiple times. On subsequent invocations, if the previous closing attempt failed then it will be re-tried.
After this method returns, calling FirebaseDataConnect.Companion.getInstance with the same app and config will return a new instance, rather than returning this instance.
| See also | |
|---|---|
suspendingClose |
equals
operator fun equals(other: Any?): Boolean
Compares this object with another object for equality, using the === operator.
The implementation of this method simply uses referential equality. That is, two instances of FirebaseDataConnect compare equal using this method if, and only if, they refer to the same object, as determined by the === operator. Notably, this makes it suitable for instances of FirebaseDataConnect to be used as keys in a java.util.WeakHashMap in order to store supplementary information about the FirebaseDataConnect instance.
| Parameters | |
|---|---|
other: Any? |
The object to compare to this for equality. |
| Returns | |
|---|---|
Boolean |
|
hashCode
fun hashCode(): Int
Calculates and returns the hash code for this object.
See equals for the special guarantees of referential equality that make instances of this class suitable for usage as keys in a hash map.
| Returns | |
|---|---|
Int |
the hash code for this object. |
mutation
fun <Data : Any?, Variables : Any?> mutation(
operationName: String,
variables: Variables,
dataDeserializer: DeserializationStrategy<Data>,
variablesSerializer: SerializationStrategy<Variables>,
optionsBuilder: (FirebaseDataConnect.MutationRefOptionsBuilder<Data, Variables>.() -> Unit)? = null
): MutationRef<Data, Variables>
Creates and returns a MutationRef for running the specified mutation.
| Parameters | |
|---|---|
operationName: String |
The value for |
variables: Variables |
The value for |
dataDeserializer: DeserializationStrategy<Data> |
The value for |
variablesSerializer: SerializationStrategy<Variables> |
The value for |
optionsBuilder: (FirebaseDataConnect.MutationRefOptionsBuilder<Data, Variables>.() -> Unit)? = null |
A method that will be called to provide optional information when creating the |
query
fun <Data : Any?, Variables : Any?> query(
operationName: String,
variables: Variables,
dataDeserializer: DeserializationStrategy<Data>,
variablesSerializer: SerializationStrategy<Variables>,
optionsBuilder: (FirebaseDataConnect.QueryRefOptionsBuilder<Data, Variables>.() -> Unit)? = null
): QueryRef<Data, Variables>
Creates and returns a QueryRef for running the specified query.
| Parameters | |
|---|---|
operationName: String |
The value for |
variables: Variables |
The value for |
dataDeserializer: DeserializationStrategy<Data> |
The value for |
variablesSerializer: SerializationStrategy<Variables> |
The value for |
optionsBuilder: (FirebaseDataConnect.QueryRefOptionsBuilder<Data, Variables>.() -> Unit)? = null |
A method that will be called to provide optional information when creating the |
suspendingClose
suspend fun suspendingClose(): Unit
A version of close that has the same semantics, but suspends until the asynchronous work is complete.
If the asynchronous work fails, then the exception from the asynchronous work is rethrown by this method.
Using this method in tests may be useful to ensure that this object is fully shut down after each test case. This is especially true if tests create FirebaseDataConnect in rapid succession which could starve resources if they are all active simultaneously. In those cases, it may be a good idea to call suspendingClose instead of close to ensure that each instance is fully shut down before a new one is created. In normal production applications, where instances of FirebaseDataConnect are created infrequently, calling close should be sufficient, and avoids having to create a CoroutineScope just to close the object.
| See also | |
|---|---|
close |
toString
fun toString(): String
Returns a string representation of this object, useful for debugging.
The string representation is not guaranteed to be stable and may change without notice at any time. Therefore, the only recommended usage of the returned string is debugging and/or logging. Namely, parsing the returned string or storing the returned string in non-volatile storage should generally be avoided in order to be robust in case that the string representation changes.
| Returns | |
|---|---|
String |
a string representation of this object, which includes the class name and the values of all public properties. |
useEmulator
fun useEmulator(host: String = "10.0.2.2", port: Int = 9399): Unit
Configure this FirebaseDataConnect object to connect to the Data Connect Emulator.
This method is typically called immediately after creation of the FirebaseDataConnect object and must be called before any queries or mutations are executed. An exception will be thrown if called after a query or mutation has been executed. Calling this method causes the values in DataConnectSettings.host and DataConnectSettings.sslEnabled to be ignored.
To start the Data Connect emulator from the command line, first install Firebase Tools as documented at https://firebase.google.com/docs/emulator-suite/install_and_configure then run firebase emulators:start --only auth,dataconnect. Enabling the "auth" emulator is only needed if using com.google.firebase.auth.FirebaseAuth to authenticate users. You may also need to specify --project <projectId> if the Firebase tools are unable to auto-detect the project ID.
| Parameters | |
|---|---|
host: String = "10.0.2.2" |
The host name or IP address of the Data Connect emulator to which to connect. The default value, 10.0.2.2, is a magic IP address that the Android Emulator aliases to the host computer's equivalent of |
port: Int = 9399 |
The TCP port of the Data Connect emulator to which to connect. The default value is the default port used |
Public properties
app
val app: FirebaseApp
The FirebaseApp instance with which this object is associated.
The FirebaseApp object is used for things such as determining the project ID of the Firebase project and the configuration of FirebaseAuth.
| See also | |
|---|---|
getInstance |
config
val config: ConnectorConfig
The configuration of the Data Connect "connector" used to connect to the Data Connect service.
| See also | |
|---|---|
getInstance |
settings
val settings: DataConnectSettings
The settings of this FirebaseDataConnect object, that affect how it behaves.
| See also | |
|---|---|
getInstance |