Firebase Data Connect

Firebase (Google)OfficialCreated by Google LLCDistributed by Firebase (Google)

Skill
Tool integration
Software development
Apache-2.0
Low risk

From the author

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 description by Google LLC

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Firebase SQL Connect (formerly Firebase Data Connect) provides a managed relational database service built on Cloud SQL for PostgreSQL. It enables developers to define data models using GraphQL schemas, automatically generating type-safe SDKs for various platforms. The service emphasizes a secure-by-default approach, offering built-in authorization, real-time data updates, and support for complex operations through both GraphQL and native SQL.

What it does

Defines relational data models using GraphQL schema syntax.
Generates type-safe SDKs for TypeScript, Kotlin, Swift, Dart, and Node.js.
Manages database operations including queries, mutations, and transactions.
Configures real-time data subscriptions and event-driven updates.
Supports advanced PostgreSQL features via native SQL when necessary.
Provides local emulation for development, testing, and data seeding.

When to use it

When building a new application that requires a relational database integrated with Firebase.
When you need to generate type-safe client SDKs from a defined database schema.
When implementing row-level security and authorized data access.
When your application requires real-time data synchronization.
When you need to perform complex database operations like vector search or window functions.

Advantages

Strong type safety across the full stack via auto-generated SDKs.
Secure-by-default architecture with built-in authorization directives.
Seamless integration with the Firebase ecosystem and Cloud SQL.
Flexible operation strategies allowing for both standard GraphQL and advanced native SQL.
Robust local development tooling including emulators and schema validation.

Usage examples

“How do I define a new table for my user profiles in Firebase SQL Connect?”: The agent will guide you to define a GraphQL type in schema.gql using the @table directive, specifying columns and relationships.
“Generate a TypeScript SDK for my current Firebase SQL Connect project.”: The agent will show you how to configure the generate block in connector.yaml and run the SDK generation command.
“How can I perform a complex PostgreSQL window function in my query?”: The agent will explain how to use Native SQL operations with _select or _execute to bypass standard GraphQL limitations.
“Set up a real-time subscription for my movie list.”: The agent will demonstrate using the @refresh directive in your query to enable event-driven updates.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/firebase/firebase-data-connect/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip firebase-data-connect.zip -d .agents/skills

Documentation by Google LLC

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 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 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 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:
@refresh directive for time-based polling and event-driven updates.
CEL conditions to scope refresh triggers precisely.
Read reference/native_sql.md for Native SQL operations:
Embedding raw SQL with _select, _selectFirst, _execute
Strict rules for positional parameters ($1, $2), quoting, and CTEs
Advanced PostgreSQL features (PostGIS, Window Functions)

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"
    package: "DataConnectGenerated"

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
Android (Kotlin): reference/sdk_android.md
iOS (Swift): reference/sdk_ios.md
Admin (Node.js): reference/sdk_admin_node.md
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	`@table`, `@unique`, `@index`, Relations
Vector Search	reference/search.md	`Vector`, `@col(dataType: "vector")`, embeddings
Full-Text Search	reference/search.md	`@searchable`, `movies_search`
Upserting Data	reference/operations.md	`_upsert` mutations
Complex Filters	reference/operations.md	`_or`, `_and`, `_not`, `eq`, `contains`
Transactions	reference/operations.md	`@transaction`, `response` binding
Environment Config	reference/config.md	`dataconnect.yaml`, `connector.yaml`
Realtime Subscriptions	reference/realtime.md	`@refresh`, `subscribe()`, auto-refresh
Cloud Functions Integration	reference/cloud_functions.md	`onMutationExecuted`, triggering events
Data Seeding & Migrations	reference/data_seeding.md	`seed_data.gql`, `_insertMany`, Admin SDK bulk
Starter Templates	templates.md	CRUD, user-owned resources, many-to-many, SDK init

Deployment & CLI

Read reference/config.md 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.
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.

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

Files

ATTRIBUTION.mdAdded by AutoGineer989 B
LICENSELicence file added by AutoGineer11.1 KiB
SKILL.md9.3 KiB
examples.md14.7 KiB
reference/cloud_functions.md6.0 KiB
reference/config.md7.1 KiB
reference/data_seeding.md5.8 KiB
reference/native_sql.md6.9 KiB
reference/operations.md11.0 KiB
reference/realtime.md7.7 KiB
reference/schema.md7.4 KiB
reference/sdk_admin_node.md4.1 KiB
reference/sdk_android.md5.9 KiB
reference/sdk_flutter.md3.4 KiB
reference/sdk_ios.md4.2 KiB
reference/sdk_web.md4.8 KiB
reference/search.md8.7 KiB
reference/security.md8.9 KiB
templates.md7.1 KiB

reference/schema.md

Schema Reference

Defining Types
Core Directives
Relationships
Data Types
Enumerations

Defining Types

Types with @table map to PostgreSQL tables. SQL Connect auto-generates an implicit id: UUID! primary key.

type Movie @table {
  # id: UUID! is auto-added
  title: String!
  releaseYear: Int
  genre: String
}

Customizing Tables

type Movie @table(name: "movies", key: "id", singular: "movie", plural: "movies") {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int @col(name: "release_year")
  genre: String @col(dataType: "varchar(20)")
}

User Table with Auth

type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  email: String! @unique
  displayName: String @col(dataType: "varchar(100)")
  createdAt: Timestamp! @default(expr: "request.time")
}

Core Directives

@table

Defines a database table.

Argument	Description
`name`	PostgreSQL table name (snake_case default)
`key`	Primary key field(s), default `["id"]`
`singular`	Singular name for generated fields
`plural`	Plural name for generated fields

@col

Customizes column mapping.

Argument	Description
`name`	Column name in PostgreSQL
`dataType`	PostgreSQL type: `serial`, `varchar(n)`, `text`, etc.
`size`	Required for `Vector` type

@default

Sets default value for inserts.

Argument	Description
`value`	Literal value: `@default(value: "draft")`
`expr`	CEL expression: `@default(expr: "uuidV4()")`, `@default(expr: "auth.uid")`, `@default(expr: "request.time")`
`sql`	Raw SQL: `@default(sql: "now()")`

Common expressions:

uuidV4() - Generate UUID
auth.uid - Current user's Firebase Auth UID
request.time - Server timestamp

@unique

Adds unique constraint.

type User @table {
  email: String! @unique
}

# Composite unique
type Review @table @unique(fields: ["movie", "user"]) {
  movie: Movie!
  user: User!
  rating: Int
}

@index

Creates database index for query performance.

type Movie @table @index(fields: ["genre", "releaseYear"], order: [ASC, DESC]) {
  title: String! @index
  genre: String
  releaseYear: Int
}

Argument	Description
`fields`	Fields for composite index (on @table)
`order`	`[ASC]` or `[DESC]` for each field
`type`	`BTREE` (default), `GIN` (arrays), `HNSW`/`IVFFLAT` (vectors)

@searchable

Enables full-text search on String fields.

type Post @table {
  title: String! @searchable
  body: String! @searchable(language: "english")
}

# Usage
query SearchPosts($q: String!) @auth(level: PUBLIC) {
  posts_search(query: $q) { id title body }
}

Relationships

One-to-Many (Implicit Foreign Key)

type Post @table {
  id: UUID! @default(expr: "uuidV4()")
  author: User!  # Creates authorId foreign key
  title: String!
}

type User @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String!
  # Auto-generated: posts_on_author: [Post!]!
}

@ref Directive

Customizes foreign key reference.

type Post @table {
  author: User! @ref(fields: "authorId", references: "id")
  authorId: UUID!  # Explicit FK field
}

Argument	Description
`fields`	Local FK field name(s)
`references`	Target field(s) in referenced table
`constraintName`	PostgreSQL constraint name

Cascade behavior:

Required reference (User!): CASCADE DELETE (post deleted when user deleted)
Optional reference (User): SET NULL (authorId set to null when user deleted)

One-to-One

Use @unique on the reference field:

type User @table { id: UUID! name: String! }

type UserProfile @table {
  user: User! @unique  # One profile per user
  bio: String
  avatarUrl: String
}

# Query: user.userProfile_on_user

Many-to-Many

Use a join table with composite primary key:

type Movie @table { id: UUID! title: String! }
type Actor @table { id: UUID! name: String! }

type MovieActor @table(key: ["movie", "actor"]) {
  movie: Movie!
  actor: Actor!
  role: String!  # Extra data on relationship
}

# Generated fields:
# - movie.actors_via_MovieActor: [Actor!]!
# - actor.movies_via_MovieActor: [Movie!]!
# - movie.movieActors_on_movie: [MovieActor!]!

Data Types

GraphQL Type	PostgreSQL Default	Other PostgreSQL Types
`String`	`text`	`varchar(n)`, `char(n)`
`Int`	`int4`	`int2`, `serial`
`Int64`	`bigint`	`bigserial`, `numeric`
`Float`	`float8`	`float4`, `numeric`
`Boolean`	`boolean`
`UUID`	`uuid`
`Date`	`date`
`Timestamp`	`timestamptz`	Stored as UTC
`Any`	`jsonb`
`Vector`	`vector`	Requires `@col(size: N)`
`[Type]`	Array	e.g., `[String]` → `text[]`

Enumerations

enum Status {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type Post @table {
  status: Status! @default(value: DRAFT)
  allowedStatuses: [Status!]
}

Rules:

Enum names: PascalCase, no underscores
Enum values: UPPER_SNAKE_CASE
Values are ordered (for comparison operations)
Changing order or removing values is a breaking change

Views (Advanced)

Map custom SQL queries to GraphQL types:

type MovieStats @view(sql: """
  SELECT
    movie_id,
    COUNT(*) as review_count,
    AVG(rating) as avg_rating
  FROM review
  GROUP BY movie_id
""") {
  movie: Movie @unique
  reviewCount: Int
  avgRating: Float
}

# Query movies with stats
query TopMovies @auth(level: PUBLIC) {
  movies(orderBy: [{ rating: DESC }]) {
    title
    stats: movieStats_on_movie {
      reviewCount avgRating
    }
  }
}

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Google LLC

Publisher

Firebase (Google) (Official)

Distributed by

Firebase (Google)

Source

firebase/agent-skills · skills/firebase-data-connect-basics · commit b76be96

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Google LLC or Firebase (Google).

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download firebase-data-connect.zip