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 for an email app and deploy to production.
- Define queries and mutations for your schema.
- Deploy your final prototype to production.
Prerequisites
To use this quickstart, you'll need the following.
- Linux, macOS, or Windows
- Visual Studio Code
Add Data Connect to your project and create a data source
- If you haven't already, create a Firebase project.
- In the Firebase console, click Add project, then follow the on-screen instructions.
Upgrade your project to the Blaze plan. This lets you create a Cloud SQL for PostgreSQL instance.
Navigate to the Data Connect section of the Firebase console and follow the product setup workflow.
Select a location for your CloudSQL for PostgreSQL database.
Note the project, service and database names and IDs for confirmation later.
Follow the remaining setup flow then click Done.
Choose and set up a development environment
Data Connect supports two development experiences for prototyping:
- If you're a Kotlin Android or web developer, you can use VS Code development to prototype 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 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.
- Create a new directory for your local project.
- Open VS Code in the new directory.
Download the extension, bundled as a VSIX package, from Firebase Storage.
In VS Code, from the View menu, select Extensions.
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:
- Access the template at the Project IDX site.
- Follow the setup flow.
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.
Set up your local project
Install the CLI, following the normal instructions. If you have npm already installed, run the following command:
npm install -g firebase-tools
To set up your local project, initialize your project directory.
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.
In the Firebase extension UI:
- Make sure you've signed in.
- Click the Run firebase init button.
- Check the Terminal tab in the VS Code lower Panel for prompts.
- Select Data Connect as a feature to use in this directory.
- When prompted, supply the project, service and database IDs of the Data Connect project you created earlier in the console.
Create a Data Connect schema and query
Start using GraphQL to model users and emails. You'll update sources in:
/dataconnect/schema/schema.gql
/dataconnect/default-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.
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
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.
- You can use the Firebase VS Code extension to deploy.
- In the extension UI, under the Firebase Data Connect panel, click Deploy all.
- 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
.
- Review schema changes using
Execute mutations to 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 in the resulting generated files to perform these actions on your
backend.
To add records to the User
and Email
tables:
- In
schema.gql
, click the Add data button above theUser
type declaration.
- In the
User_insert.gql
file that is generated, hard code data for the three fields. - Click the Run (Production) button.
- Repeat the previous steps to add a record to the
Email
table, supplying theuid
of your user in thefromUid
field, as prompted in the generatedEmail_insert
mutation.
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/default-connector/queries.gql
file. If you want
to get all emails, use a query like this.
# File `/dataconnect/default-connector/queries.gql`
query ListEmails @auth(level: NO_ACCESS) {
emails {
id, subject, text, sent
from {
name
}
}
}
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 an Email has a from
field that references a
User, you can nest into the field and get information about the user back.
Deploy your completed prototype 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 all button.
Once deployed, you should be able to view and run your operations on the console as well. 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.
- macOS. Download and install Postgres.app.
- Windows: Use the EDB installer from the PostgreSQL downloads page.
- Docker: Pull and run the
pgvector/pgvector:15
image, which comes with both PostgreSQL 15.x and vector support. - Linux: We recommend using Docker with the preceding image, but you can also follow alternative instructions for popular distributions.
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:
- In VS Code, in the left-hand panel, click the Firebase icon to open the Firebase VS Code extension UI.
- Click the Connect to Local PostgreSQL button.