firebase-data-connect

SKILL.md

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.