Skip to main contentSkip to user menuSkip to navigation
System Designer
Back to Technology

Firebase Data Connect

Learn Firebase Data Connect schemas, connectors, generated SDKs, PostgreSQL queries, authorization, deployment, and operations.

40 min read•Intermediate
Not Started
Loading...

What is Firebase Data Connect?

Firebase Data Connect is a managed relational application backend built on Cloud SQL for PostgreSQL. You describe relational tables with a GraphQL-based application schema, define the exact queries and mutations that clients may call in connectors, then generate typed SDKs from those deployed operations.

The database remains PostgreSQL. Data Connect supplies the managed API contract between client code and that database; it does not erase relational modeling, query planning, migrations, backups, or capacity work.

Product naming

Current Firebase documentation calls the evolved product Firebase SQL Connect. This lesson keeps the established Data Connect route and title, but follows the current SQL Connect architecture and operational guidance.

The invariant

A client may execute only a named connector operation whose selection set, authorization, and variable contract were reviewed and deployed. Generated SDK types describe that contract; they do not replace server-side authorization or PostgreSQL constraints.

Separate the three data contracts

A Data Connect service has three different sources of truth. Treating them as one file causes unsafe schema changes and broken clients.

Stored truth

PostgreSQL SQL schema

Tables, columns, constraints, indexes, and rows live in Cloud SQL. Database migrations change this durable layer.

Mapped model

Application schema

GraphQL types in .gql files map application entities and relationships to the SQL schema.

Client API

Connectors

Named queries and mutations define what clients can execute. connector.yaml groups the operation sources used to generate SDKs.

The current schema and connector deployment guide defines the deployment order: migrate the SQL schema, update the application schema, then update connectors. A connector deployment can break an existing app even when no row changes.

One generated SDK request

The client calls a deployed operation; it does not submit an arbitrary selection set to PostgreSQL.

App

Generated client method

Typed variables and response data come from the connector operation at SDK-generation time.

API contract

Deployed connector

Data Connect authenticates the request, applies @auth, and executes the named query or mutation.

Mapping

Application schema

Generated relational fields and directives map the operation to PostgreSQL tables and columns.

Durable state

Cloud SQL for PostgreSQL

The database executes SQL and enforces keys, constraints, transactions, storage, and recovery behavior.

Design schema and operations together

GraphQL nesting makes a response readable, but it does not make the underlying work free. A useful connector operation starts with one client task, selects only the needed fields, bounds list sizes, and makes ownership visible.

Use the workbench to compare three workloads. The row-work and payload figures are teaching estimates, not Firebase latency or pricing predictions.

Loading the query and schema model...

Model relationships in PostgreSQL

This compact catalog schema uses a real join table. Data Connect infers the foreign-key fields from the User and Product references, while the compound key prevents a user from saving the same product twice.

A relational Data Connect application schema

Important schema rules:

  • define a relationship on one side and let Data Connect generate the reverse access fields;
  • use PostgreSQL keys and constraints for durable invariants;
  • use server expressions such as uuidV4(), request.time, and auth.uid instead of trusting equivalent client values;
  • keep indexes and query plans aligned with the filters and ordering used by deployed operations;
  • remember that application field names cannot contain underscores because generated supplemental fields use them.

The schema design guide documents table mapping, inferred relationships, compound keys, and server values.

Put the API contract in connectors

Client applications do not send arbitrary GraphQL documents for server execution. Queries and mutations are authored in connector source, deployed, and converted into platform-specific SDK methods.

The example exposes an intentionally public catalog read and two owner-scoped favorite operations. Notice where authority comes from:

  • ListCatalog is PUBLIC, bounded, and carries an explicit public-data rationale;
  • ListMyFavorites filters userId with eq_expr: "auth.uid";
  • AddFavorite writes userId_expr: "auth.uid" instead of accepting a user ID from the caller;
  • every list has an explicit limit and narrow selection set.
Reviewed connector operations

Authentication is only the starting point

@auth(level: USER) proves that a non-anonymous Firebase user signed in. By itself, it does not prove that a requested row belongs to that user. Bind ownership with server-evaluated auth.uid filters or expressions. An operation without @auth defaults to NO_ACCESS for clients.

Data Connect uses operation directives such as @auth, @check, @redact, and @transaction; it does not use Firestore Security Rules for these connector operations. The authorization guide also explains Firebase App Check and the separate IAM boundary for administrators.

Make authorization and deployment one release decision

An operation can be logically correct and still be unsafe to release. The SQL migration may drop data, the connector may break deployed SDK clients, or an authorization directive may expose another user's rows.

Change all three decisions in the release lab. A healthy result requires a resource boundary, a production-safe migration plan, and a connector contract that old clients can still execute.

Loading the authorization and deployment model...

The Admin SDK is a privileged server boundary. Current Admin SDK operations run with administrative authority unless authentication impersonation is supplied, so a missing client @auth check must never be treated as protection from trusted server code. Keep server credentials and Cloud SQL roles narrowly scoped.

Generate SDKs from the reviewed connector

SDK generation turns connector operations into typed functions, references, variables, and result data for web, Android, iOS, and Flutter clients. Regenerate SDKs whenever the connector contract changes, and fail CI when generated output is stale.

Calling generated web SDK references

Generated types catch contract drift during development, but they do not:

  • authorize a request on the server;
  • prevent an old mobile app from calling an incompatible deployed connector;
  • add a missing PostgreSQL index;
  • make a multi-step business workflow atomic unless the mutation and database transaction express that boundary;
  • turn broad nested reads into inexpensive queries.

Use the Data Connect emulator for local connector behavior and authorization tests. The generated web SDK guide documents SDK initialization, generation in CI, emulator connection, and query or mutation execution.

Deploy schema changes without gambling with data

Schema and connector releases are coupled but recover differently. An earlier connector revision can restore an API shape; it cannot recreate a column or rows removed by a destructive migration.

  1. 1

    Observe

    Inventory deployed contracts

    List the current services and connectors. Identify client versions still in use, operation error rates, Cloud SQL backup state, and the owner of the release.

  2. 2

    Migrate

    Review the SQL diff

    Run firebase dataconnect:sql:diff. Use COMPATIBLE validation for production data unless every optional drop is explicitly planned, backed up, and recoverable.

  3. 3

    Release

    Deploy compatible connectors

    Let CLI breaking-change assessments stop non-interactive deployment. Do not use --force as a routine way around client-contract review.

  4. 4

    Verify

    Regenerate and observe

    Generate SDKs, run client contract tests, deploy clients in stages, and monitor per-operation requests and errors together with PostgreSQL health.

A reviewable CLI deployment sequence

For a field removal, split the change:

  1. remove the field from connector selections while keeping the database column;
  2. regenerate SDKs and move deployed clients to the compatible contract;
  3. verify old client traffic has drained;
  4. remove the application-schema field and apply the reviewed SQL migration.

Firebase recommends COMPATIBLE schema validation for databases with production data. In that mode, optional DROP SCHEMA, DROP TABLE, and DROP COLUMN actions are not applied.

Operate the API and database as separate systems

Data Connect and Cloud SQL share a request path, but they have different failure, security, observability, and cost boundaries.

Contract

Connector boundary

Breaking operation variables or selected fields can fail old generated clients even when PostgreSQL is healthy.

Access

Authorization boundary

Firebase Auth identifies a caller. @auth, filters, server expressions, App Check, IAM, and PostgreSQL roles govern different layers.

API

Service boundary

Watch requests, errors, and operation rates globally and per operation in the Firebase console. Quota or service errors can block a healthy database.

State

Database boundary

Cloud SQL owns compute, storage, connections, query behavior, backups, maintenance, replicas, and regional database availability.

Observe both layers

For Data Connect, monitor:

  • request rate, error rate, and latency by named operation;
  • authorization denials and App Check enforcement failures;
  • connector revision and client SDK version during a release;
  • operation quota consumption and network egress.

For Cloud SQL for PostgreSQL, monitor:

  • CPU, memory, storage headroom, active connections, and transaction pressure;
  • slow or high-load SQL using Query Insights and PostgreSQL evidence;
  • replication lag where replicas exist;
  • backup success, point-in-time recovery configuration, and restore rehearsal;
  • maintenance events and instance availability.

The service management guide documents per-operation monitoring, the Data Connect request quota, same-location requirements, and the separate Cloud SQL administration boundary.

Budget the whole path

Current billing has at least two independent components:

  1. Data Connect service operations and network egress;
  2. the Cloud SQL for PostgreSQL instance, including its compute, storage, backup, networking, and replica choices.

Vertex AI integration adds its own embedding charges. Pricing thresholds can change, so use the current pricing page, Cloud SQL pricing, a billing budget, and workload measurements instead of a hard-coded per-request calculator.

Know when Data Connect is the right boundary

Choose Data Connect when the application benefits from:

  • relational constraints, joins, and PostgreSQL transactions;
  • a reviewed set of client operations rather than an open-ended API;
  • generated SDKs for web or mobile clients;
  • Firebase Authentication and App Check at the connector boundary;
  • managed Cloud SQL integration while retaining SQL administration options.

Reconsider or add other services when the workload needs:

  • globally active-active writes with no application-level conflict design;
  • unbounded analytical scans on an operational database;
  • binary object storage;
  • arbitrary public GraphQL documents rather than deployed operations;
  • a claim that Firebase management removes backup, migration, indexing, or incident ownership.

The architectural question is not “Can GraphQL express this response?” It is “Can one deployed operation preserve authorization, relational invariants, a bounded query envelope, client compatibility, and a recoverable release?”

No quiz questions available
Could not load questions file
Spotted an issue or have a better explanation? This page is open source.Edit on GitHub·Suggest an improvement