Get started with Firebase Data Connect locally

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 Visual Studio Code extensions to work with a local instance.
• Then we will show you how to:
  • Use VS Code extension tooling, with Gemini Code Assist , to:
    • Create a schemafor an app
    • Create administrative queries and mutationsto populate your local database
    • Help you implement queries and mutationsfor your app in a deployable connector
  • Test your queries and mutations with sample data against a local emulator
  • Generate strongly typed SDKsand use them in your app
  • Deployyour final schema and connector to the cloud (optional, with a Blaze plan upgrade).

Choose a local development flow

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

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. To set up a Data Connect development environment and browser-based IDE, run the following command in the new directory you created.

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

   This script attempts the installation. The installed IDE provides toolings, including pre-bundled VS Code extensions, to help you manage your schema and define queries and mutations to be used in your application.

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 Googlebutton.
2. Click the Connect a Firebase projectbutton and select the project you created earlier in the console.
3. Click the Run firebase initbutton.

4. Click the Start emulatorsbutton.

Create a schema

In your Firebase project directory, in the /dataconnect/schema/schema.gql file, start defining a GraphQL schema about, for example, movie reviews.

Use Gemini Code Assist to build a schema

To create a movie review app schema using Gemini Code Assist :

1. Click the Data Connect VS Code extension icon to open its sidebar.
2. Click Build your schema and queries with AI. The Gemini Code Assist chat window opens.
3. At the bottom of the chat window, make sure Agentmode is toggled on.
4. Click the chat box at the bottom of the chat window, and begin typing a natural language description of the kind of app you're building.
5. Press enter, and Gemini will display the MCP server command it will execute to begin developing the schema.
6. Click Accept. After a few moments, a recommended schema appears. Review the schema.

7. To add the code to schema.gql :

   1. Wait for Gemini Code Assist to prompt you for the file to update.
   2. Click Acceptto modify the file, or View Changesbefore committing.

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

You may see a type definition like the following. Or, you can copy the following snippet or uncomment the corresponding lines in the default 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 dataand 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 databutton 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 databutton 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 a query

Now for more fun: 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, both for queries and mutations.

To create a query using Gemini Code Assist :

1. Click the Data Connect VS Code extension icon to open its sidebar.
2. Click Build your schema and queries with AI. The Gemini Code Assist chat window opens.
3. At the bottom of the chat window, make sure Agentmode is toggled on.
4. Click the chat box at the bottom of the chat window, and begin typing a natural language description of the kind of operation you want to develop.
5. Press enter, and Gemini will display the MCP server command it will execute to begin developing the operation.
6. Click Accept. After a few moments, a recommended query appears. Review the query.

7. To add the code to queries.gql :

   1. Wait for Gemini Code Assist to prompt you for the file to update.
   2. Click Acceptto modify the file, or View Changesbefore committing.

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

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

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

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

Use the SDKs to call your query from an app

You can use the SDK that Data Connect generated to implement a call to your ListMovies query. You can then execute this query locally using the Data Connect emulator.

  import 
  
 'package:firebase_core/firebase_core.dart' 
 ; 
 import 
  
 'package:flutter/material.dart' 
 ; 
 import 
  
 'firebase_options.dart' 
 ; 
 // Generated queries. 
 // Update as needed with the path to your generated SDK 
  import 
  
 'movies_connector/movies.dart' 
 ; 
 void 
  
 main 
 () 
  
 async 
  
 { 
  
 WidgetsFlutterBinding 
 . 
 ensureInitialized 
 (); 
  
   
 await 
  
 Firebase 
 . 
 initializeApp 
 ( 
  
 options: 
  
 DefaultFirebaseOptions 
 . 
 currentPlatform 
 , 
  
 ); 
  
  
 MoviesConnector 
 . 
 instance 
 . 
 dataConnect 
  
 . 
 useDataConnectEmulator 
 ( 
 Uri 
 . 
 base 
 . 
 host 
 , 
  
 443 
 , 
  
 isSecure: 
  
 true 
 ); 
  
  
 runApp 
 ( 
 const 
  
 MyApp 
 ()); 
 } 
 class 
  
 MyApp 
  
 extends 
  
 StatelessWidget 
  
 { 
  
 const 
  
 MyApp 
 ({ 
 super 
 . 
 key 
 }); 
  
 @override 
  
 Widget 
  
 build 
 ( 
 BuildContext 
  
 context 
 ) 
  
 { 
  
 return 
  
 MaterialApp 
 ( 
  
 home: 
  
 Scaffold 
 ( 
  
 body: 
  
 Column 
 ( 
 children: 
  
 [ 
  
 ConstrainedBox 
 ( 
  
 constraints: 
  
 const 
  
 BoxConstraints 
 ( 
 maxHeight: 
  
 200 
 ), 
  
 child: 
  
 FutureBuilder 
 ( 
   
 future: 
  
 MoviesConnector 
 . 
 instance 
 . 
 listMovies 
 (). 
 execute 
 (), 
  
 builder: 
  
 ( 
 context 
 , 
  
 snapshot 
 ) 
  
 { 
  
 if 
  
 ( 
 snapshot 
 . 
 connectionState 
  
 == 
  
 ConnectionState 
 . 
 done 
 ) 
  
 { 
  
 return 
  
 ListView 
 . 
 builder 
 ( 
  
 scrollDirection: 
  
 Axis 
 . 
 vertical 
 , 
  
 itemBuilder: 
  
 ( 
 context 
 , 
  
 index 
 ) 
  
 = 
>  
 Card 
 ( 
  
 child: 
  
 Text 
 ( 
   
 snapshot 
 . 
 data 
 ! 
 . 
 data 
 . 
 movies 
 [ 
 index 
 ]. 
 title 
 , 
  
 )), 
   
 itemCount: 
  
 snapshot 
 . 
 data 
 ! 
 . 
 data 
 . 
 movies 
 . 
 length 
 , 
  
 ); 
  
 } 
  
 return 
  
 const 
  
 CircularProgressIndicator 
 (); 
  
 }), 
  
 ) 
  
 ]))); 
  
 } 
 } 
 

Deploy your schema and query to production

Once you have your local setup on your app, now you can deploy your schema and connectorto the cloud. You need a Blaze plan project 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.

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

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

4. In the IDE window, in the VS Code Extension UI, click the Deploy to productionbutton.

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:

• Discover more AI assistance tools and guidance to help you generate schemas, queries and mutations. The AI assistance guide covers how to set up and use our MCP server with your IDEs and best practices for writing prompts .
• 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 .