Get started with Firebase Data Connect

In this quickstart, you will learn how to:

  • 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 using an email app example.
    • Define queries and mutations for your schema.
    • Use automatically-generated SDKs to call these queries and mutations from your clients.
    • Deploy your final prototype to production.

Prerequisites

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

Add Data Connect to your project and create a data source

  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. Upgrade your project to the Blaze plan. This lets you create a Cloud SQL for PostgreSQL instance.

  3. Navigate to the Data Connect section of the Firebase console and follow the product setup workflow.

  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.

Choose and set up a development environment

You'll start with Data Connect by prototyping an app in Visual Studio Code.

Optionally, you can install a local PostgreSQL database for local development with the Data Connect emulator. This setup is covered at the end of this quickstart guide.

Data Connect supports two development experiences for prototyping:

  • If you're a web or Kotlin Android developer, you can prototype schemas and operations locally while connecting to your Cloud SQL for PostgreSQL instance, or (optionally) run PostgreSQL locally.
  • If you're a web developer, you can use IDX to prototype in an IDX workspace using a pre-configured IDX template with PostgreSQL, VS Code extension with Data Connect emulator, and quickstart code set up for you.

VS Code development

If you like to develop locally instead of using IDX, set up the Firebase VS Code extension to help you iterate your development quickly with SDK generation for web, Kotlin Android and, coming soon, iOS.

  1. Create a new directory for your local project.
  2. Open VS Code in the new directory.
  3. Download the extension, bundled as a VSIX package, from Firebase Storage.
  4. In VS Code, from the View menu, select Extensions.
  5. On the Extensions panel title bar, click the menu icon more_horiz, then follow Install from VSIX....

IDX development

IDX is an environment optimized for web app development. If you're a Kotlin Android developer, follow the steps on the VS Code development tab.

To set up a Data Connect IDX template:

  1. Access the template at the Project IDX site.
  2. Follow the setup flow.

Set up your local project

Install the CLI, following the normal instructions.

Then, enable the Firebase Data Connect experiment.

firebase experiments:enable dataconnect

To set up your local project, we will initialize your project directory and update a few configuration files needed for code generation.

Set up your project directory

Initialize your project directory.

Firebase extension setup

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

In the Firebase extension UI:

  1. Make sure you've signed in.
  2. In the Firebase console, confirm the Data Connect setup flow, including database provisioning, is complete.
  3. Click the Run firebase init button.
  4. Check the Terminal tab in the VS Code lower Panel for prompts.
  5. Select Data Connect as a feature to use in this directory.
  6. When prompted, supply the project, service and database IDs of the Data Connect project you created earlier in the console.

Terminal setup

  1. If necessary, sign in using firebase login.
  2. In the Firebase console, confirm the Data Connect setup flow, including database provisioning, is complete.
  3. Run firebase init to initialize your directory as a Firebase project, following the onscreen prompts.
  4. Select Data Connect as a feature to use in this directory.
  5. When prompted, supply the project, service and database IDs of the Data Connect project you created earlier in the console.

Either flow will create a firebase.json and .firebaserc files, and dataconnect subdirectories including important dataconnect.yaml and connector.yaml files in your local working directory.

Configure where SDK code is generated

Data Connect automatically generates SDK code while you edit your schema.

To specify where SDKs are generated to, update the file for your initial connector, in dataconnect/connector/connector.yaml.

connectorId: "my-connector"
authMode: "PUBLIC"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@email-manager/emails"
    packageJsonDir: "../../"
  kotlinSdk:
    outputDir: "../kotlin-email-generated"
    package: com.myemailapplication

Get familiar with the Data Connect Toolkit

The Data Connect Toolkit is a component of the Firebase VS Code extension that helps with schema development, and query and mutation management, directly from Visual Studio Code.

To have a look at Toolkit features:

  1. If you haven't already, open your Firebase project directory in VS Code.
  2. In VS Code, in the left-hand panel, click the Firebase icon to open the Firebase VS Code extension UI.

Throughout your development work, note that the Toolkit lets you to interact with your local environment as well as with your production resources. In this quickstart, you'll interact with your production environment.

VS Code extension for Data Connect, in IDX

The extension UI provides you several useful features:

In the VS Code Primary Side Bar:

  • A Config panel, which lets you sign in to Google and select a Firebase project.
  • A Firebase Data Connect panel, which lets you control the built-in emulator and deploy resources to production.
  • An FDC Explorer panel, which lists automatically-generated implicit queries and mutations based on your schema
In the VS Code lower Panel:

  • A Data Connect Execution tab, with tools to let you pass data in requests, mimic authentication, and view results.

Before we start developing an app, have a look at some features of the extension.

Try the custom CodeLens When you work with resources in your schema.gql, queries.gql and mutations.gql files, once you've written syntactically complete code blocks, a custom CodeLens displays actions you can take on your declared tables and operations.
  • For tables, the CodeLens helps you generate mutations to add data to the backend database.
  • For queries and mutations, the CodeLens lets you run the operations locally or against production resources.
Set authentication level for requests In the lower panel, the Data Connect Execution panel provides a Configuration tab where you can select simulated authentication levels for operations.
Populate variables in queries and mutations In the same Configuration tab, you can populate operation payloads.
Inspect history, responses and errors Also in the Configuration tab, you can check the History and Results tabs for debugging information.

Create a Data Connect schema and query

Your setup is done. Now we can start developing with Data Connect.

Start using GraphQL to model users and emails. You'll update sources in:

  • /dataconnect/schema/schema.gql
  • /dataconnect/connector/queries.gql

Start developing a schema

In your Firebase project directory, note the dataconnect folder. This is where you define your data model for a Cloud SQL database using GraphQL.

In the /dataconnect/schema/schema.gql file, start defining a schema that includes users and emails.

User

In Data Connect, GraphQL fields are mapped to columns. Users have a uid, name, and email address. Data Connect recognizes several primitive data types: String and Date.

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

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

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

By default Firebase Data Connect will add a UUID id key if none is provided. However, in this case you want my uid to be the primary key, which you can do through the @table(key: "uid") directive.

Email

Now that you have users, you can model emails. Here you can add the typical fields (or columns) for email data. This time, we omit adding a primary key because you can rely on Data Connect to manage it.

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

type Email @table {
   subject: String!
   sent: Date!
   text: String!
   from: User!
}

Notice that the from field is mapped to a type of User. Data Connect understands that this is a relationship between Email and User and will manage this relationship for you.

Deploy your schema to production

Because you are using the Firebase VS Code extension to work with your production database, you need to deploy your schema before continuing.

  1. You can use the Firebase VS Code extension to deploy.
    • In the extension UI, under the Firebase Data Connect panel, click Deploy.
  2. Alternatively, you can use the Firebase CLI.

    firebase deploy
    
  3. In either the extension or CLI flow, 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.

Look at generated schema extensions

As you edit your email schema, Data Connect automatically generates schema extensions, queries, mutations, filters and table relations. You can view this generated code in two ways.

  • You can see a list of generated implicit queries and mutations in the Firebase extension UI, under the FDC Explorer panel.
  • You can view all local generated code in the sources in the .dataconnect/schema directory.

Execute a mutation to add data to your table

You can see CodeLens buttons appear over the GraphQL types in /dataconnect/schema/schema.gql.

Development time queries and mutations

The operations associated with these CodeLens buttons are quick and useful actions, in this case, adding data to the table. Data Connect uses GraphQL mutations to describe how and who can operate against the database. Using this button it creates a development time operation for quick data seeding.

Once you've deployed your schema to production, you can use the Run (Production) CodeLens buttons to perform these actions on your backend.

Write a query to list emails

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 emails, use a query like this.

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

query ListEmails @auth(level: NO_ACCESS) {
  emails {
    id, subject, text, sent
    from {
      name
    }
  }
}

A really exciting feature here is the ability to treat the database's relationships like a graph. Since an Email has a from field that references a User, you can nest into the field and get information about the user back.

@auth directive

The @auth directive is not being used to its fullest potential in this example but the concept is really powerful. This is how you decide the authorization policy for operations against the database.

This query is fairly straightforward, the real exciting features of Data Connect start to shine when you perform more complex joins with many-to-many relationships. You will learn more about this as you explore tools and documentation.

Test your query

Now that we have this query created, check if it works before integrating it into client code. A part of the developer experience for Data Connect is the ability to quickly iterate and test query results with the Data Connect Execution panel.

You can provide the arguments this query needs and then click the CodeLens button above the query name. This executes the query and displays the results, so you can see that it's working as expected.

Generate client SDK code and query data from a client app

To close out the development cycle, integrate this query into client code.

You can write a client to demonstrate calling the query and handling replies from the Data Connect service.

  1. Locate automatically-generated sources at the location you specified previously in your connector.yaml file.
  2. Add Firebase to your project, register your app, and install the relevant Firebase core SDK:

  3. If you're not using IDX, you can set up a client, callable from the command line.

JavaScript

Create a source file, clientTest.js, and copy the following code.

const { initializeApp } = require("firebase/app");
const {
  connectDataConnectEmulator,
  getDataConnect,
} = require("firebase/data-connect");
const { listEmails, connectorConfig } = require("@email-manager/emails");

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  //...
};

const app = initializeApp(firebaseConfig);
const dc = getDataConnect(app, connectorConfig);

// Remove the following line to connect directly to production
connectDataConnectEmulator(dc, "localhost", 9399);

listEmails().then(res => {
  console.log(res.data.emails);
  process.exit(0);
});
    

And you can run your client.

    node clientTest.js
    
Kotlin Android

Create a source file, clientTest.kt, and copy the following code.

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleScope.launch {
      val connector = MyConnector.instance
      connector.dataConnect.useEmulator() // Remove to connect to production
      try {
        println(connector.listEmails.execute().data.emails)
      } catch (e: Throwable) {
        println("ERROR: $e")
      }
    }
  }
}
    

Then:

  1. Run the Activity.
  2. Check Android's logcat output.

Deploy your completed prototype to production

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

Once deployed, your Data Connect service will be ready to process operations from clients. The Cloud SQL for PostgreSQL instance will be updated with its final deployed generated schema and data.

(Optional) Install PostgreSQL locally

Installing PostgreSQL locally and integrating it with the emulator lets you prototype in a fully local development environment.

You can install a new instance of PostgreSQL or use an existing instance.

Install PostgreSQL

Install PostgreSQL version 15.x following instructions for your platform.

Note hostname, port, username and password and related parameters output during the installation sequence.

To connect to your PostgreSQL instance, the emulator needs:

  • These setup configuration parameters
  • The database name from your dataconnect.yaml and a correspondingly-named database initialized in your local instance.

Update your .firebaserc with the connection string

Use your local PostgreSQL configuration details, including your local PostgreSQL username and password, for a connection string to add to the following key in your .firebaserc file.

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

Connect to your local PostgreSQL instance

With this configuration done, to connect to your local database:

  1. In VS Code, in the left-hand panel, click the Firebase icon to open the Firebase VS Code extension UI.
  2. Click the Connect to Local PostgreSQL button.

Next steps