Get started with Firebase Data Connect

Note: Firebase Data Connect is launching to Public Preview in a few days.

In this quickstart, you will learn how to build Firebase Data Connect in your application.

Note: Follow this quickstart guide if you want to add Data Connect to one of your Firebase projects on the Blaze plan, create a Data Connect service, and provision a Cloud SQL database for your prototyping. If you'd rather use the Spark plan and prototype locally with an emulator and local database, try the local development get started.

• Add Firebase Data Connect to your Firebase project.
• Set up a development environment including a Visual Studio Code extension to work with a production instance.
• Then we will show you how to:
  • Create a schema for a movie review app and deploy to production.
  • Define queries and mutations for your schema.
  • Generate strongly typed SDKs and use them in your app
  • Deploy your final schema, query and data to production.

Prerequisites

To use this quickstart in your local environment, you'll need the following.

• Linux, macOS, or Windows
• Visual Studio Code

Connect to your Firebase project

1. If you haven't already, create a Firebase project.
   1. In the Firebase console, click Add project, then follow the on-screen instructions.
2. Navigate to the Data Connect section of the Firebase console and follow the product setup workflow.

3. Upgrade your project to the Blaze plan. This lets you create a Cloud SQL for PostgreSQL instance.

   Note: Though you set up billing in your Blaze upgrade, you won't be charged for usage of Data Connect or the default Cloud SQL for PostgreSQL configuration during the preview.

4. Select a location for your CloudSQL for PostgreSQL database.

5. Note the project, service and database names and IDs for confirmation later.

6. Follow the remaining setup flow then click Done.

   Note: It may take up to 15 minutes to finish provisioning your Cloud SQL for PostgreSQL instance. You can confirm the Data Connect setup flow, including database provisioning, is complete using the Google Cloud console.

Choose and set up a development environment

Data Connect supports two development experiences for prototyping:

• If you're a Kotlin Android, iOS or web developer, you can use VS Code development to design and test schemas and operations locally while connecting to your Cloud SQL for PostgreSQL instance.
• If you're a web developer, you can use IDX Development to develop in an IDX workspace using a pre-configured IDX template with PostgreSQL, VS Code extension with Data Connect emulator, and quickstart client code set up for you. You'll find more information at the Project IDX site.

This quickstart focuses on the VS Code extension development flow. To continue:

1. Create a new directory for your local project.
2. Open VS Code in the new directory.

3. Install the Firebase Data Connect extension from the Visual Studio Code Marketplace.

   Note: The extension includes the marketplace GraphQL Syntax Highlighting extension. Other GraphQL extensions you install may conflict with GraphQL support bundled in the Firebase Data Connect extension.

Set up your local project

Note: If you are not using IDX, follow the steps in this section.

Install the CLI, following the normal instructions. If you have npm already installed, run the following command:

npm install -g firebase-tools

Note: If you're using an existing CLI installation, make sure that you update to the latest version.

Set up your project directory

To set up your local project, initialize your project directory.

In the VS Code left-hand panel, click the Firebase icon to open the Firebase VS Code extension UI.

1. Click the Sign in with Google button.
2. Click the Connect a Firebase project button and select the project you created earlier in the console.
3. Click the Run firebase init button.
4. If your project is on the Blaze plan, when prompted "Would you like to configure your backend resources now?", answer "Yes".

5. When prompted "Would you like to configure generated SDKs now?", answer "No".

   Note: The tooling automatically configures SDKs for you if it detects directories containing client source code. If you don't have any client code in your project directory, answer "No". We will show you how to configure your SDKs and use them to write client code for your app in a later section.

6. Click the Start emulators button.

   Note: In the integrated Terminal, verify that your configured emulators start up. Once they are running, you should see your extension UI update with emulator details.

Create a schema

In your Firebase project directory, in the /dataconnect/schema/schema.gql file, start defining a GraphQL schema that includes movies.

Movie

In Data Connect, GraphQL fields are mapped to columns. The Movie type has id, title, imageUrl and genre. Data Connect recognizes the primitive data types String and UUID.

Copy the following snippet or uncomment the corresponding lines in the file.

# File `/dataconnect/schema/schema.gql`

# By default, a UUID id key will be created by default as primary key.
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

MovieMetadata

Now that you have movies, you can model movie metadata.

Copy the following snippet or uncomment the corresponding lines in the file.

# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # This time, we omit adding a primary key because
  # you can rely on Data Connect to manage it.

  # @unique indicates a 1-1 relationship
  movie: Movie! @unique
  # movieId: UUID <- this is created by the above reference
  rating: Float
  releaseYear: Int
  description: String
}

Notice that the movie field is mapped to a type of Movie. Data Connect understands that this is a relationship between Movie and MovieMetadata and will manage this relationship for you.

Learn more about Data Connect schemas in the documentation

Deploy your schema to production

If you are using the Firebase VS Code extension to work with your production database, you need to deploy your schema before continuing. After deploying your schema to your production database, you should be able to view the schema on the console.

Note: Provisioning of your Cloud SQL for PostgreSQL instance can take up to 15 minutes. You won't be able to deploy until your instance is ready. Before you deploy your schema, confirm the Data Connect setup flow, including database provisioning, is complete using the Google Cloud console.

1. You can use the Data Connect VS Code extension to deploy.
   • In the extension UI, under the Firebase Data Connect panel, click Deploy to production.
2. You may need to review schema changes and approve potentially destructive modifications. You'll be prompted to:
   • Review schema changes using firebase dataconnect:sql:diff
   • When you are satisfied with changes, apply them using the flow started by firebase dataconnect:sql:migrate.

Add data to your tables

In the VS Code editor panel, you can see CodeLens buttons appear over the GraphQL types in /dataconnect/schema/schema.gql. Since you've deployed your schema to production, you can use the Add data and Run (Production) buttons add data to your database on the backend.

To add records to the Movie table:

1. In schema.gql, click the Add data button above the Movie type declaration.
   
2. In the Movie_insert.gql file that is generated, hard code data for the four fields.
3. Click the Run (Production) button.
   

To quickly verify data was added:

1. Back in schema.gql, click the Read data button.
2. In the resulting Movie_read.gql file, click the Run (Production) button to execute the query.

Learn more about Data Connect mutations in the documentation

Define your query

Now the fun part, queries. As a developer, you're accustomed to writing SQL queries rather than GraphQL queries, so this can feel a bit different at first. However, GraphQL is far more terse and type-safe than raw SQL. And our VS Code extension eases the development experience.

Start editing the /dataconnect/connector/queries.gql file. If you want to get all movies, use a query like this.

# File `/dataconnect/connector/queries.gql`

# @auth() directives control who can call each operation.
# Anyone should be able to list all movies, so the auth level
# is set to PUBLIC
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

Execute the query using the nearby CodeLens button.

Learn more about Data Connect queries in the documentation

Generate SDKs and use them in your app

Update your connector/connector.yaml file to generate SDK code for the client platforms in your project.

# File `/dataconnect/connector.yaml`

connectorId: movies
generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"
  kotlinSdk:
    outputDir: "../src/main/java/com/myapplication"
    package: "com.myapplication"

Once you save your edits to connector.yaml, you should see the code generated for each platform under the director specified by outputDir.

Learn how to use the generated SDK to call queries and mutations from client apps (web, Android, and iOS).

Deploy your schema and query to production

You have worked through a development iteration. Now you can deploy your schema, data, and queries to the server with the Firebase extension UI or the Firebase CLI, just as you did with your schema.

If you use the Firebase VS Code extension to deploy, click the Deploy to production button.

Once deployed, go to the Firebase console to verify the schema, operations and data has been uploaded to the cloud. You should be able to view the schema, and run your operations on the console as well. The Cloud SQL for PostgreSQL instance will be updated with its final deployed generated schema and data.

Learn more about using the Data Connect emulator in the documentation

Next steps

Review your deployed project and discover more tools:

• Add data to your database, inspect and modify your schemas, and monitor your Data Connect service in the Firebase console. Access more information in the documentation. For example, since you've completed the quickstart:

• Learn more about schema, query and mutation development

• Learn about generating client SDKs and calling queries and mutations from client code for web, Android, and iOS.