Firebase Data Connect
Firebase (Google)OfficialCreated by Google LLCDistributed by Firebase (Google)
- Skill
- Tool integration
- Software development
- Apache-2.0
- Low risk
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://mp-staging.autogineer.com/agent-skills/firebase/firebase-data-connect/downloadUnzip 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 # MutationsKey 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:compileagainst 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,@defaultRelationships (
@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
_upsertto "insert or update" records (CRITICAL for user profiles).Transactions: Use
@transactionfor 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.
@checkand@redactfor row-level security and validation.Read reference/realtime.md for real-time subscriptions:
@refreshdirective 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,_executeStrict rules for positional parameters (
$1,$2), quoting, and CTEsAdvanced 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:generateFor 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:compileornpx -y firebase-tools@latest dataconnect:sdk:generateto 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/operations.md
Operations Reference
Contents
Generated Fields
Queries
Mutations
Key Scalars
Multi-Step Operations
Generated Fields
SQL Connect auto-generates fields for each @table type:
| Generated Field | Purpose | Example |
|---|---|---|
movie(id: UUID, key: Key, first: Row) | Get single record | movie(id: $id) or movie(first: {where: ...}) |
movies(where: ..., orderBy: ..., limit: ..., offset: ..., distinct: ..., having: ...) | List/filter records | movies(where: {...}) |
movie_insert(data: ...) | Create record | Returns key |
movie_insertMany(data: [...]) | Bulk create | Returns keys |
movie_update(id: ..., data: ...) | Update by ID | Returns key or null |
movie_updateMany(where: ..., data: ...) | Bulk update | Returns count |
movie_upsert(data: ...) | Insert or update | Returns key |
movie_delete(id: ...) | Delete by ID | Returns key or null |
movie_deleteMany(where: ...) | Bulk delete | Returns count |
Relation Fields
For a Post with author: User!:
post.author- Navigate to related Useruser.posts_on_author- Reverse: all Posts by User
For many-to-many via MovieActor:
movie.actors_via_MovieActor- Get all actorsactor.movies_via_MovieActor- Get all movies
Referencing Generated GraphQL Schema
Do not guess available queries or mutations. Review the generated schema files instead of trying to deduce them from the data model.
Location:
.dataconnect/schema/main/(relative to project root).Action: Scan this directory for generated files (
query.gql,mutation.gql,relation.gql,input.gql) to understand the exact shape of the API and auto-generated types.Validation: Always run
firebase dataconnect:compileto verify operations against the full schema.
Queries
Basic Query
query GetMovie($id: UUID!) @auth(level: PUBLIC) {
movie(id: $id) {
id title genre releaseYear
}
}List with Filtering
query ListMovies($genre: String, $minRating: Int) @auth(level: PUBLIC) {
movies(
where: {
genre: { eq: $genre },
rating: { ge: $minRating }
},
orderBy: [{ releaseYear: DESC }, { title: ASC }],
limit: 20,
offset: 0
) {
id title genre rating
}
}Filter Operators
| Operator | Description | Example |
|---|---|---|
eq | Equals | { title: { eq: "Matrix" }} |
ne | Not equals | { status: { ne: "deleted" }} |
gt, ge | Greater than (or equal) | { rating: { ge: 4 }} |
lt, le | Less than (or equal) | { releaseYear: { lt: 2000 }} |
in | In list | { genre: { in: ["Action", "Drama"] }} |
nin | Not in list | { status: { nin: ["deleted", "hidden"] }} |
isNull | Is null check | { description: { isNull: true }} |
contains | String contains | { title: { contains: "war" }} |
startsWith | String starts with | { title: { startsWith: "The" }} |
endsWith | String ends with | { email: { endsWith: "@gmail.com" }} |
includes | Array includes | { tags: { includes: "sci-fi" }} |
Expression Operators (Compare with Server Values)
Use _expr suffix to compare with server-side values:
query MyPosts @auth(level: USER) {
posts(where: { authorUid: { eq_expr: "auth.uid" }}) {
id title
}
}
query RecentPosts @auth(level: PUBLIC) {
posts(where: { publishedAt: { lt_expr: "request.time" }}) {
id title
}
}Logical Operators
query ComplexFilter($genre: String, $minRating: Int) @auth(level: PUBLIC) {
movies(where: {
_or: [
{ genre: { eq: $genre }},
{ rating: { ge: $minRating }}
],
_and: [
{ releaseYear: { ge: 2000 }},
{ status: { ne: "hidden" }}
],
_not: { genre: { eq: "Horror" }}
}) { id title }
}Relational Queries
# Navigate relationships
query MovieWithDetails($id: UUID!) @auth(level: PUBLIC) {
movie(id: $id) {
title
# One-to-one
metadata: movieMetadata_on_movie { director }
# One-to-many
reviews: reviews_on_movie { rating user { name }}
# Many-to-many
actors: actors_via_MovieActor { name }
}
}
# Filter by related data
query MoviesByDirector($director: String!) @auth(level: PUBLIC) {
movies(where: {
movieMetadata_on_movie: { director: { eq: $director }}
}) { id title }
}
# Filter by null relationship (e.g., top-level categories with no parent)
# Use the generated foreign key field (e.g., parentId)
query TopLevelCategories @auth(level: PUBLIC) {
categories(where: { parentId: { eq: null } }) {
id
name
}
}Aliases
query CompareRatings($genre: String!) @auth(level: PUBLIC) {
highRated: movies(where: { genre: { eq: $genre }, rating: { ge: 8 }}) {
title rating
}
lowRated: movies(where: { genre: { eq: $genre }, rating: { lt: 5 }}) {
title rating
}
}Mutations
Create
mutation CreateMovie($title: String!, $genre: String) @auth(level: USER) {
movie_insert(data: {
title: $title,
genre: $genre
})
}Create with Server Values
mutation CreatePost($title: String!, $content: String!) @auth(level: USER) {
post_insert(data: {
authorUid_expr: "auth.uid", # Current user
id_expr: "uuidV4()", # Auto-generate UUID
createdAt_expr: "request.time", # Server timestamp
title: $title,
content: $content
})
}Update
mutation UpdateMovie($id: UUID!, $title: String, $genre: String) @auth(level: USER) {
movie_update(
id: $id,
data: {
title: $title,
genre: $genre,
updatedAt_expr: "request.time"
}
)
}Update Operators
mutation IncrementViews($id: UUID!) @auth(level: PUBLIC) {
movie_update(id: $id, data: {
viewCount_update: { inc: 1 }
})
}
mutation AddTag($id: UUID!, $tag: String!) @auth(level: USER) {
movie_update(id: $id, data: {
tags_update: { add: [$tag] } # add, remove, append, prepend
})
}| Operator | Types | Description |
|---|---|---|
inc | Int, Float, Date, Timestamp | Increment value |
dec | Int, Float, Date, Timestamp | Decrement value |
add | Lists | Add items if not present |
remove | Lists | Remove all matching items |
append | Lists | Append to end |
prepend | Lists | Prepend to start |
Upsert
mutation UpsertUser($email: String!, $name: String!) @auth(level: USER) {
user_upsert(data: {
uid_expr: "auth.uid",
email: $email,
name: $name
})
}Delete
mutation DeleteMovie($id: UUID!) @auth(level: USER) {
movie_delete(id: $id)
}
mutation DeleteOldDrafts @auth(level: USER) {
post_deleteMany(where: {
status: { eq: "draft" },
createdAt: { lt_time: { now: true, sub: { days: 30 }}}
})
}Filtered Updates/Deletes (User-Owned)
mutation UpdateMyPost($id: UUID!, $content: String!) @auth(level: USER) {
post_update(
first: { where: {
id: { eq: $id },
authorUid: { eq_expr: "auth.uid" } # Only own posts
}},
data: { content: $content }
)
}Key Scalars
Key scalars (Movie_Key, User_Key) are auto-generated types representing
primary keys:
# Using key scalar
query GetMovie($key: Movie_Key!) @auth(level: PUBLIC) {
movie(key: $key) { title }
}
# Variable format
# { "key": { "id": "uuid-here" } }
# Composite key
# { "key": { "movieId": "...", "userId": "..." } }Key scalars are returned by mutations:
mutation CreateAndFetch($title: String!) @auth(level: USER) {
key: movie_insert(data: { title: $title })
# Returns: { "key": { "id": "generated-uuid" } }
}Multi-Step Operations
@transaction
Ensures atomicity - all steps succeed or all rollback:
mutation CreateUserWithProfile($name: String!, $bio: String!)
@auth(level: USER)
@transaction {
# Step 1: Create user
user_insert(data: {
uid_expr: "auth.uid",
name: $name
})
# Step 2: Create profile (uses response from step 1)
userProfile_insert(data: {
userId_expr: "response.user_insert.uid",
bio: $bio
})
}Using response Binding
Access results from previous steps:
mutation CreateTodoWithItem($listName: String!, $itemText: String!)
@auth(level: USER)
@transaction {
todoList_insert(data: {
id_expr: "uuidV4()",
name: $listName
})
todoItem_insert(data: {
listId_expr: "response.todoList_insert.id", # From previous step
text: $itemText
})
}Embedded Queries
Run queries within mutations for validation:
mutation AddToPublicList($listId: UUID!, $item: String!)
@auth(level: USER)
@transaction {
# Step 1: Verify list exists and is public
query @redact {
todoList(id: $listId) @check(expr: "this != null", message: "List not found") {
isPublic @check(expr: "this == true", message: "List is not public")
}
}
# Step 2: Add item
todoItem_insert(data: { listId: $listId, text: $item })
}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
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