Firebase Data Connect

Firebase Data 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 ├── schema/ │ └── schema.gql # Data model (types with @table) └── connector/ ├── connector.yaml # Connector config + SDK generation ├── queries.gql # Queries └── mutations.gql # Mutations

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.

Read reference/schema.md for:

• @table , @col , @default

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

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

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

Write the queries and mutations your client will use. Data Connect generates the underlying SQL.

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.

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. Secure Your App (connector/ files)

Add authorization logic closely with your operations.

Read reference/security.md for:

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

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

4. Generate & Use SDKs

Generate type-safe code for your client platform.

Read reference/sdks.md for:

• Android (Kotlin), iOS (Swift), Web (TypeScript), Flutter (Dart).

• How to initialize and call your queries/mutations.

• Nested Data: See how to access related fields (e.g., movie.reviews ).

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/advanced.md Vector , @col(dataType: "vector")

Full-Text Search reference/advanced.md @searchable

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

Deployment & CLI

Read reference/config.md for deep dive on configuration.

Common commands (run from project root):

Initialize Data Connect

npx -y firebase-tools@latest init dataconnect

Start local emulator

npx -y firebase-tools@latest emulators:start --only dataconnect

Generate SDK code

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

Deploy to production

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

Examples

For complete, working code examples of schemas and operations, see examples.md.