Get started with Firebase SQL Connect on Android

In this quickstart, you will create and deploy a small sample database and access it from an Android app.

Prerequisites

To complete this quickstart, you'll need the following:

  • An environment with the following tools installed:
    • A recent version of Android Studio.
    • The Firebase CLI. If you have NPM installed, run: 
      npm install -g firebase-tools@latest
       Otherwise, see the docs for installation instructions.
  • A Google Account.

Tutorial

Tutorial

1. Create a new Android Studio project

In Android Studio, create a new project with the Empty Activity template.

Name the project Quickstart App with the package name com.example.quickstartapp.

 Android Studio new project dialog

2. Add Firebase to your Android Studio project

Add the Firebase dependencies and the Kotlin serialization plugin to your build.gradle.kts files.

 QuickstartApp/build.gradle.kts 
plugins {
  alias(libs.plugins.android.application) apply false
  alias(libs.plugins.kotlin.compose) apply false

  // Add this line.
  id("com.google.gms.google-services") version "4.4.4" apply false
}
 QuickstartApp/app/build.gradle.kts 
plugins {
  alias(libs.plugins.android.application)
  alias(libs.plugins.kotlin.compose)

  // Add these lines.
  kotlin("plugin.serialization") version libs.versions.kotlin
  id("com.google.gms.google-services")
}

// ...

dependencies {
  // ...

  // Add these lines.
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.11.0")

  implementation(platform("com.google.firebase:firebase-bom:34.14.0"))
  implementation("com.google.firebase:firebase-dataconnect")
}

3. Initialize a Firebase project

Change to the Android Studio project directory and initialize a Firebase project in it.

 
cd ~/QuickstartApp
 
firebase login --reauth
 
firebase init dataconnect

When prompted, choose the following options:

  • Create a new Firebase project.
  • Don't create a schema with Gemini (in this tutorial, you'll use a pre-built example schema).
  • Provision a free trial Cloud SQL instance and database.

Accept the default values for all other prompts.

Next, register your Android app in your Firebase project.

firebase apps:create -a com.example.quickstartapp android android-quickstart
 
firebase apps:sdkconfig android -o app/google-services.json

4. Review the example GraphQL definitions

In SQL Connect, you define all of your database schemas and operations using GraphQL. When you initialized your project, the Firebase CLI created some example definitions to get you started.

 dataconnect/schema/schema.gql (excerpt) 
type Movie @table {
  title: String!
  imageUrl: String!
  genre: String
}

type MovieMetadata @table {
  movie: Movie! @unique
  rating: Float
  releaseYear: Int
  description: String
}
 dataconnect/example/queries.gql (excerpt) 
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

5. Deploy your schemas and operations

Whenever you make changes to your database schemas, queries, or mutations, you must deploy them for your changes to take effect on the database.

 
firebase deploy --only dataconnect

6. Seed the database with sample data

This seed data will give you something to look at when you test the sample app. Note that in this step you are executing arbitrary GraphQL, which is allowed for administrative tasks.

 
firebase dataconnect:execute dataconnect/seed_data.gql

7. Generate an Android client SDK

This command uses your GraphQL definitions to generate an Android client SDK specifically for your database. You use this library in your client app to perform all database operations.

You can generate libraries for multiple platforms, including Swift for iOS, JavaScript for web, and Flutter, by adding definitions to connector.yaml.

 
firebase dataconnect:sdk:generate
 Auto-generated Android SDK (excerpt) 
public interface ExampleConnector : GeneratedConnector<ExampleConnector> {
  override val dataConnect: com.google.firebase.dataconnect.FirebaseDataConnect

  public val listMovies: ListMoviesQuery

  // ...
}

8. Write a sample Android client

Replace the contents of app/src/main/java/com/example/quickstartapp/MainActivity.kt with this simple Android app.

Notice that the app completes the necessary database access using a function from the generated SDK.

 
package com.example.quickstartapp

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import com.example.quickstartapp.ui.theme.QuickstartAppTheme
import com.google.firebase.dataconnect.generated.ExampleConnector
import com.google.firebase.dataconnect.generated.ListMoviesQuery
import com.google.firebase.dataconnect.generated.execute
import com.google.firebase.dataconnect.generated.instance

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContent {
      QuickstartAppTheme() {
        Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
          var movies by remember {
            mutableStateOf(emptyList<ListMoviesQuery.Data.MoviesItem>())
          }
          LaunchedEffect(Unit) {
            // Queries need to be executed in a coroutine context
            try {
              movies = ExampleConnector.instance.listMovies.execute().data.movies
            } catch (e: Exception) {
              // TODO: Handle error, e.g., show a Toast or update a state variable to
              //   display an error message.
            }
          }
          LazyColumn(modifier = Modifier.padding(innerPadding)) {
            items(movies) { movie ->
              Text(text = movie.title)
            }
          }
        }
      }
    }
  }
}

9. Try the app

From Android Studio, run the example app to see it in action.

Next steps

Try the SQL Connect VS Code extension

When developing with SQL Connect, we strongly recommend using the SQL Connect VS Code extension. Even if you don't use Visual Studio Code as your primary development environment, the extension provides several features that make schema and operation development more convenient:

  • A GraphQL language server, providing syntax checking and autocomplete suggestions specific to SQL Connect
  • CodeLens buttons in line with your code that let you read and write data from your schema definition files and execute queries and mutations from your operation definitions.
  • Automatically keep your generated SDKs synchronized with your GraphQL definitions.
  • Simplified local emulator setup.
  • Simplified deployment to production.

Use the SQL Connect emulator for local development

Although this tutorial showed you how to deploy SQL Connect schemas and operations directly to production, you will likely not want to make changes to your production database while you are actively developing your app. Instead, set up the SQL Connect emulator and do your development work against it rather than production. The emulator sets up a local PGlite instance that behaves similarly to a live PostgreSQL instance on Cloud SQL.

Learn how to write schemas and operations for your app

When developing apps with SQL Connect, the design of your schemas and operations is one of the first and most important development tasks you will complete.

  • Gemini in the Firebase console is an AI tool that can generate SQL Connect schemas from a natural language description of your app. This tool can get you started very quickly, especially if you've never worked with relational databases before.
  • Alternatively, you can write database schemas, queries, and mutations directly using GraphQL. Start with the guidance in Design SQL Connect schemas, and then continue to the follow-up pages to learn how to write operations.