Firebase Data Connect

1---2name: firebase-data-connect3description: Build and deploy Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL. Use for schema design, GraphQL queries/mutations, authorization, and SDK generation for web, Android, iOS, and Flutter apps.4---5 6# Firebase Data Connect7 8Firebase Data Connect is a relational database service using Cloud SQL for PostgreSQL with GraphQL schema, auto-generated queries/mutations, and type-safe SDKs.9 10> [!NOTE]11> **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.12 13## Project Structure14 15```16dataconnect/17├── dataconnect.yaml      # Service configuration18├── schema/19│   └── schema.gql        # Data model (types with @table)20└── connector/21    ├── connector.yaml    # Connector config + SDK generation22    ├── queries.gql       # Queries23    └── mutations.gql     # Mutations24```25 26## Operation Strategies: GraphQL vs. Native SQL27 28Always 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.29 30| Strategy | When to use | Implementation |31|----------|-------------|----------------|32| **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. |33| **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. |34 35## Development Workflow36 37Follow this strict workflow to build your application. You **must** read the linked reference files for each step to understand the syntax and available features.38 39### 1. Define Data Model (`schema/schema.gql`)40Define your GraphQL types, tables, and relationships.41> **Read [reference/schema.md](reference/schema.md)** for:42> *   `@table`, `@col`, `@default`43> *   Relationships (`@ref`, one-to-many, many-to-many)44> *   Data types (UUID, Vector, JSON, etc.)45 46### 2. Define Operations (`connector/queries.gql`, `connector/mutations.gql`)47Write the queries and mutations your client will use. Data Connect generates the underlying SQL.48> **Read [reference/operations.md](reference/operations.md)** for:49> *   **Queries**: Filtering (`where`), Ordering (`orderBy`), Pagination (`limit`/`offset`).50> *   **Mutations**: Create (`_insert`), Update (`_update`), Delete (`_delete`).51> *   **Upserts**: Use `_upsert` to "insert or update" records (CRITICAL for user profiles).52> *   **Transactions**: use `@transaction` for multi-step atomic operations.53> 54> **Read [reference/native_sql.md](reference/native_sql.md)** for Native SQL operations:55> *   Embedding raw SQL with `_select`, `_selectFirst`, `_execute`56> *   Strict rules for positional parameters (`$1`, `$2`), quoting, and CTEs57> *   Advanced PostgreSQL features (PostGIS, Window Functions)58 59### 3. Secure Your App (`connector/` files)60Add authorization logic closely with your operations.61> **Read [reference/security.md](reference/security.md)** for:62> *   `@auth(level: ...)` for PUBLIC, USER, or NO_ACCESS.63> *   `@check` and `@redact` for row-level security and validation.64 65### 4. Generate & Use SDKs66Generate type-safe code for your client platform.67> **Read [reference/sdks.md](reference/sdks.md)** for:68> *   Android (Kotlin), iOS (Swift), Web (TypeScript), Flutter (Dart).69> *   How to initialize and call your queries/mutations.70> *   **Nested Data**: See how to access related fields (e.g., `movie.reviews`).71 72---73 74## Feature Capability Map75 76If you need to implement a specific feature, consult the mapped reference file:77 78| Feature | Reference File | Key Concepts |79| :--- | :--- | :--- |80| **Data Modeling** | [reference/schema.md](reference/schema.md) | `@table`, `@unique`, `@index`, Relations |81| **Vector Search** | [reference/advanced.md](reference/advanced.md) | `Vector`, `@col(dataType: "vector")` |82| **Full-Text Search** | [reference/advanced.md](reference/advanced.md) | `@searchable` |83| **Upserting Data** | [reference/operations.md](reference/operations.md) | `_upsert` mutations |84| **Complex Filters** | [reference/operations.md](reference/operations.md) | `_or`, `_and`, `_not`, `eq`, `contains` |85| **Transactions** | [reference/operations.md](reference/operations.md) | `@transaction`, `response` binding |86| **Environment Config** | [reference/config.md](reference/config.md) | `dataconnect.yaml`, `connector.yaml` |87 88---89 90## Deployment & CLI91 92> **Read [reference/config.md](reference/config.md)** for deep dive on configuration.93 94Common commands (run from project root):95```bash96# Initialize Data Connect97npx -y firebase-tools@latest init dataconnect98 99# Start local emulator100npx -y firebase-tools@latest emulators:start --only dataconnect101 102# Generate SDK code103npx -y firebase-tools@latest dataconnect:sdk:generate104 105# Deploy to production106npx -y firebase-tools@latest deploy --only dataconnect107```108 109## Examples110 111For complete, working code examples of schemas and operations, see **[examples.md](examples.md)**.