Firebase Data Connect · firebase/agent-skills · Skills Docs

Skills

Chapter 7 of 12

Firebase Data Connect

Builds and deploys Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL securely.

3 minutes · 612 words · 14 sections

Firebase SQL Connect

Firebase SQL Connect is a relational database service using Cloud SQL for PostgreSQL with GraphQL schema, auto-generated queries/mutations, and type-safe SDKs.

[!NOTE] Product Rename: Firebase Data Connect was renamed to Firebase SQL Connect. All instructions, references, and examples in this skill repository referring to “Data Connect” or “Firebase Data Connect” apply to “SQL Connect” and “Firebase SQL Connect” as well.

Project Structure

dataconnect/
├── dataconnect.yaml      # Service configuration
├── seed_data.gql         # LOCAL ONLY — prototype/test data
├── schema/
│   └── schema.gql        # Data model (types with @table)
└── connector/
    ├── connector.yaml    # Connector config + SDK generation
    ├── queries.gql       # Queries
    └── mutations.gql     # Mutations

Key Tools for Validation

Rely on these two mechanisms to ensure project correctness:

Review GraphQL Schema: Both user-defined and generated extensions (in .dataconnect/schema/main/).
Validate Operations: Run npx -y firebase-tools@latest dataconnect:compile against the schema.

Operation Strategies: GraphQL vs. Native SQL

Always default to Native GraphQL. Native SQL lacks type safety and bypasses schema-enforced structures. Only use Native SQL when the user explicitly requests it or when the task requires advanced database features.

Strategy	When to use	Implementation
Native GraphQL (Default)	Almost all use cases. Standard CRUD, basic filtering/sorting, simple relational joins. Requires full type safety.	Auto-generated fields (`movie_insert`, `movies`). Strong typing and schema enforcement.
Native SQL (Advanced)	PostgreSQL extensions (e.g., PostGIS), window functions (`RANK()`), complex aggregations, or highly tuned sub-queries.	Raw SQL string literals via `_select`, `_execute`, etc. Requires strict positional parameters (`$1`). No type safety.

Development Workflow

Follow this strict workflow to build your application. You must read the linked reference files for each step to understand the syntax and available features.

1. Define Data Model (`schema/schema.gql`)

Define your GraphQL types, tables, and relationships (which map to a Postgres schema).

Read reference/schema.md (opens in a new tab) for:

@table, @col, @default

Relationships (@ref, one-to-many, many-to-many)

Data types (UUID, Vector, JSON, etc.)

2. Define Authorized Operations (`connector/queries.gql`, `connector/mutations.gql`)

Write the queries and mutations your client will use, including authorization logic. SQL Connect is secure by default.

Read reference/operations.md (opens in a new tab) for:

Queries: Filtering (where), Ordering (orderBy), Pagination (limit/offset).

Mutations: Create (_insert), Update (_update), Delete (_delete).

Upserts: Use _upsert to “insert or update” records (CRITICAL for user profiles).

Transactions: Use @transaction for multi-step atomic operations. Use _expr: "response.<prevStep>" to pass data between steps.

Read reference/security.md (opens in a new tab) for authorization:

@auth(level: ...) for PUBLIC, USER, or NO_ACCESS.

@check and @redact for row-level security and validation.

Read reference/realtime.md for real-time subscriptions:

3. Use type-safe SDK in your apps

Generate type-safe code for your client platform.

Configure SDK generation in connector.yaml:

connectorId: my-connector
generate:
  javascriptSdk:
    outputDir: "../web-app/src/lib/dataconnect"
    package: "@movie-app/dataconnect"
  kotlinSdk:
    outputDir: "../android-app/app/src/main/kotlin/com/example/dataconnect"
    package: "com.example.dataconnect"
  swiftSdk:
    outputDir: "../ios-app/DataConnect"

Generate SDKs:

npx -y firebase-tools@latest dataconnect:sdk:generate

For platform-specific instructions on how to use the generated SDKs, read:

Web (TypeScript): reference/sdk_web.md (opens in a new tab)
Android (Kotlin): reference/sdk_android.md (opens in a new tab)
iOS (Swift): reference/sdk_ios.md (opens in a new tab)
Admin (Node.js): reference/sdk_admin_node.md (opens in a new tab)
Flutter (Dart): reference/sdk_flutter.md

Feature Capability Map

If you need to implement a specific feature, consult the mapped reference file:

Feature	Reference File	Key Concepts
Data Modeling	reference/schema.md (opens in a new tab)	`@table`, `@unique`, `@index`, Relations
Vector Search	reference/search.md (opens in a new tab)	`Vector`, `@col(dataType: "vector")`, embeddings
Full-Text Search	reference/search.md (opens in a new tab)	`@searchable`, `movies_search`

Deployment & CLI

Read reference/config.md (opens in a new tab) for deep dive on configuration.

Follow these patterns based on your current task:

How to initialize SQL Connect in a Firebase project

Understand the app idea. Ask clarification questions if unclear.
Run npx -y firebase-tools@latest init dataconnect.
Validate that the app template and generated SDK are setup.

How to build apps using SQL Connect locally

Start the emulator: npx -y firebase-tools@latest emulators:start --only dataconnect.
Write schema and operations.
Seed local test data into seed_data.gql. Read reference/data_seeding.md (opens in a new tab).
Run npx -y firebase-tools@latest dataconnect:compile or npx -y firebase-tools@latest dataconnect:sdk:generate to validate them.
Use the operations in your app and build it.

How to deploy SQL Connect to Cloud SQL

Run npx -y firebase-tools@latest deploy --only dataconnect.

Examples

For complete, working code examples of schemas and operations, see examples.md (opens in a new tab).

For ready-to-use starter templates (CRUD, user-owned resources, many-to-many, YAML configs, SDK init), see templates.md (opens in a new tab).

Appendix 7.1–7.16

16 files · 110 KB

Everything this skill ships beside its prose. All of it is set here, as subchapters of chapter 7.

ReferencesMarkdown · 14 files

Documentation the agent loads on demand, rather than up front.

Also bundledMarkdown · 2 files

Everything else published alongside the skill.

Install this repository

$ npx skills add firebase/agent-skills

» /plugin marketplace add firebase/agent-skills

Skills install per repository, not per chapter — the CLI has no documented per-skill form, so we do not print one.

About this skill

Trigger

Builds and deploys Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL securely. Use when designing schemas with tables and relations, writing authorized queries and mutations, configuring real-time data updates, or generating type-safe SDKs. Use when you need a relational database with Firebase, or when the user mentions SQL Connect or Data Connect.

The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.

Colophon for this issue

Colophon

How this issue was made

Source

github.com/firebase/agent-skills, branch main, last pushed 6 August 2026.

Licence

Apache-2.0 — the text of every chapter is reproduced unmodified, frontmatter included, under the upstream licence.

Discovery

12 chapters found by walking the repository tree for SKILL.md, not by matching a directory convention. One layout observed: skills/*/SKILL.md.

Issue colours

Resolved from a curated brand profile — hue 88°, chroma 0.168. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.

Heading repairs

1 repair applied to this chapter so the document has one h1 and no skipped levels:

Shifted “14 headings” from h1 to h2 so the chapter title is the only h1.

Spec compliance

1 editorial note across 1 of 12 chapters. They are printed in the margin of each chapter rather than as errors here.

Firebase Data Connect — 1 note

Images

Images inside a chapter come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.

Marketplace

A plugin manifest is published at .claude-plugin/marketplace.json by Firebase, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree.

Signal

Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.

Agent surfaces