firebase-data-connect

Gives your app a classic tables-and-rows database, hosted for you — you describe the tables and the queries you need, and the code your app calls them with is generated to match.

WHEN TO USE

SCOPE

USE FOR

Design a relational schema with tables and relationships that map to PostgreSQL.
Write authorized queries and mutations without hand-writing backend code.
Generate a type-safe SDK for your web, Android, iOS, or Flutter app.
Add real-time updates that refresh a query automatically when data changes.
Drop into raw SQL for PostGIS, window functions, or other advanced Postgres features.
Seed local test data and run the whole backend in an emulator before deploying.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (8)

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"

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.

Account or credentials required

1 FOR YOU · 2 FOR THE AGENT

Items without a tag are required.

01
Initialize SQL Connect in your Firebase project
Run npx -y firebase-tools@latest init dataconnect to scaffold the dataconnect.yaml, schema, and connector files.
```
npx -y firebase-tools@latest init dataconnect
```
02
Optional Start the local emulator before writing operations
Run npx -y firebase-tools@latest emulators:start --only dataconnect so you can write and test schema and operations locally before deploying.
```
npx -y firebase-tools@latest emulators:start --only dataconnect
```
03
Deploy to Cloud SQL when ready
Run npx -y firebase-tools@latest deploy --only dataconnect to push your schema and connector to a live Cloud SQL for PostgreSQL instance.
```
npx -y firebase-tools@latest deploy --only dataconnect
```

Listed as free: Connected services may require an account or charge fees.

This skill ships inside the Firebase Agent Skills plugin. Listed package contents include 1 agent and an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add firebase/agent-skills --skill "firebase-data-connect" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Firebase Agent Skills plugin package selected for your AI tool.

Add the plugin's marketplace, then install it

Install Claude Code first to get the claude command, then run the commands below in your terminal, outside a Claude Code session.

claude plugin marketplace add firebase/agent-skills
claude plugin install firebase@firebase

Add Firebase's marketplace, then install the plugin

Run both lines in a terminal. They add Firebase's marketplace, which is this repository, and install the firebase plugin: Firebase's skills plus the Firebase MCP server.

codex plugin marketplace add firebase/agent-skills

02
```
codex plugin add firebase@firebase
```

Installation and loading

Start a new Codex session before using it.

Good to know

Plugins work in Codex CLI and the ChatGPT desktop app, not in the Codex IDE extension.
For the desktop app, Firebase has you run the first line, fully restart the app, then install Firebase from Plugins.

Run it in a terminal, not inside a Gemini CLI session. It installs this repository as a Gemini CLI extension with Firebase's skills and the Firebase MCP server.