Get started with Firebase Data Connect locally

Note: Firebase Data Connect is in Public Preview. Data Connect will be subject to the "Pre-GA Offerings Terms" in the Service Specific Terms section of the Google Cloud Platform Terms of Service. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Note: Follow this local quickstart guide if you want to try out Data Connect with a Spark plan project. In this guide, you will prototype locally with an emulator and local database. If instead you're ready to add Data Connect to a Blaze plan project and set up a service and Cloud SQL database, try the production get started.

In this quickstart, you will learn how to build Firebase Data Connect in your application locally without setting up a production SQL instance. You will:

• Add Firebase Data Connect to your Firebase project.
• Set up a development environment including a Visual Studio Code extension to work with a local instance.
• Then we will show you how to:
  • Create a schema for a movie app
  • Define queries and mutations that will be used in your app
  • Test your queries and mutations with sample data against a local emulator
  • Generate strongly typed SDKs and use them in your app
  • Deploy your final schema, queries and data to the cloud (optional, with a Blaze plan upgrade).

Find a quickstart app repository and build a fully-featured Data Connect app by following our codelab for web. Codelabs for Android and iOS are coming soon.

Choose a local development flow

Data Connect offers you two ways to install development tools and work locally.

Auto installation (macOS or Linux) Manual installation (Windows)

Prerequisites

To use this quickstart, you'll need the following.

• A Firebase project. If you haven't already created one, do so in the Firebase console.

Set up the development environment

1. Create a new directory for your local project.

2. Run the following command in the new directory you created.

     curl -sL https://firebase.tools/dataconnect | bash
   

   This script tries to set up the development environment for you and launch a browser-based IDE. This IDE provides toolings, including a pre-bundled VS Code extension, to help you manage your schema and define queries and mutations to be used in your application, and generate strongly-typed SDKs.

   Note: If you already have the desktop version of VS Code installed, the script will open it automatically.
   Note: If the script fails, use the manual installation steps.

Tip: Optionally, you can set up an alias by appending the following line to your shell profile (e.g. ~/.zshrc or ~/.bash_profile). This lets you locally upgrade the tooling or re-launch the browser-based IDE by just typing dataconnect.

alias dataconnect='curl -sL https://firebase.tools/dataconnect | bash'

Set up your project directory

To set up your local project, initialize your project directory. In the IDE window, in the left-hand panel, click the Firebase icon to open the Data Connect 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. 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 about movies.

Movie

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

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

# By default, a UUID id key will be created by default as primary key.
# If you want to specify a primary key, say title, which you can do through
# the @table(key: "title") directive
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

MovieMetadata

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

Add data to your tables

In the IDE editor panel, you will see CodeLens buttons appear over the GraphQL types in /dataconnect/schema/schema.gql. You can use the Add data and Run (Local) buttons add data to your local database.

To add records to the Movie, and MovieMetadata tables:

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 three fields.
3. Click the Run (Local) button.
   
4. Repeat the previous steps to add a record to the MovieMetadata table, supplying the id of your Movie in the movieId field, as prompted in the generated MovieMetadata_insert mutation.

To quickly verify data was added:

1. Back in schema.gql, click the Read data button above the Movie type declaration.
2. In the resulting Movie_read.gql file, click the Run (Local) button to execute the query.

Learn more about Data Connect mutations in the documentation

Define your query

Now the fun part: let's define the queries you will need in your application. 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.

A really exciting feature here is the ability to treat the database's relationships like a graph. Since a MovieMetadata record has a movie field that references a movie, you can nest into the field and get information about the movie info back. Try adding the generated type movieMetadata_on_movie to the ListMovies query.

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
    movieMetadata_on_movie {
        rating
    }
  }
}

Learn more about Data Connect queries in the documentation

Generate SDKs and use them in your app

In the IDE left-hand panel, click the Firebase icon to open the Data Connect VS Code extension UI:

1. Click the Add SDK to app button.

2. In the dialog that appears, select a directory containing code for your app. Data Connect. SDK code will be generated and saved there.

   Note: If you don't have an app directory yet, you can create and select a new directory for SDK code for now and link it to your app later.

3. Select your app platform, then note that SDK code is immediately generated in your selected directory.

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

Deploy your schema and query to production

Once you have your local setup on your app, now you can deploy your schema, data, and queries to the cloud. You will need Blaze plan to set up a Cloud SQL instance.

1. Navigate to Data Connect section of the Firebase console and create a free trial Cloud SQL instance.

   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.

2. In the IDE integrated Terminal, run firebase init dataconnect and select the Region/Service ID you just created on the console.

3. Select "Y" when prompted with "File dataconnect/dataconnect.yaml already exists, Overwrite?".

4. In the VS Code Extension UI, click the Deploy to production button.

5. 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.

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, and Flutter.