Firebase Data Connect

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: 1. Review GraphQL Schema: Both user-defined and generated extensions (in .dataconnect/schema/main/). 2. 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.

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](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](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](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](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](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:

---

Deployment & CLI

Read [reference/config.md](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

1. Understand the app idea. Ask clarification questions if unclear. 2. Run npx -y firebase-tools@latest init dataconnect. 3. Validate that the app template and generated SDK are setup.

How to build apps using SQL Connect locally

1. Start the emulator: npx -y firebase-tools@latest emulators:start --only dataconnect. 2. Write schema and operations. 3. Seed local test data into seed_data.gql. Read reference/data_seeding.md. 4. Run npx -y firebase-tools@latest dataconnect:compile or npx -y firebase-tools@latest dataconnect:sdk:generate to validate them. 5. Use the operations in your app and build it.

How to deploy SQL Connect to Cloud SQL

1. Run npx -y firebase-tools@latest deploy --only dataconnect.

Examples

For complete, working code examples of schemas and operations, see [examples.md](examples.md).

For ready-to-use starter templates (CRUD, user-owned resources, many-to-many, YAML configs, SDK init), see [templates.md](templates.md).

Examples

Complete, working examples for common SQL Connect use cases.

---

Movie Review App

A complete schema for a movie database with reviews, actors, and user authentication.

Schema

# schema.gql

# Users
type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  email: String! @unique
  displayName: String
  createdAt: Timestamp! @default(expr: "request.time")
}

# Movies
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int
  genre: String @index
  rating: Float
  description: String
  posterUrl: String
  createdAt: Timestamp! @default(expr: "request.time")
}

# Movie metadata (one-to-one)
type MovieMetadata @table {
  movie: Movie! @unique
  director: String
  runtime: Int
  budget: Int64
}

# Actors
type Actor @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String!
  birthDate: Date
}

# Movie-Actor relationship (many-to-many)
type MovieActor @table(key: ["movie", "actor"]) {
  movie: Movie!
  actor: Actor!
  role: String!  # "lead" or "supporting"
  character: String
}

# Reviews (user-owned)
type Review @table @unique(fields: ["movie", "user"]) {
  id: UUID! @default(expr: "uuidV4()")
  movie: Movie!
  user: User!
  rating: Int!
  text: String
  createdAt: Timestamp! @default(expr: "request.time")
}

Queries

# queries.gql

# Public: List movies with filtering
query ListMovies($genre: String, $minRating: Float, $limit: Int) 
  @auth(level: PUBLIC) {
  movies(
    where: {
      genre: { eq: $genre },
      rating: { ge: $minRating }
    },
    orderBy: [{ rating: DESC }],
    limit: $limit
  ) {
    id title genre rating releaseYear posterUrl
  }
}

# Public: Get movie with full details
query GetMovie($id: UUID!) @auth(level: PUBLIC) {
  movie(id: $id) {
    id title genre rating releaseYear description
    metadata: movieMetadata_on_movie { director runtime }
    actors: actors_via_MovieActor { name }
    reviews: reviews_on_movie(orderBy: [{ createdAt: DESC }], limit: 10) {
      rating text createdAt
      user { displayName }
    }
  }
}

# User: Get my reviews
query MyReviews @auth(level: USER) {
  reviews(where: { user: { uid: { eq_expr: "auth.uid" }}}) {
    id rating text createdAt
    movie { id title posterUrl }
  }
}

Mutations

# mutations.gql

# User: Create/update profile on first login
mutation UpsertUser($email: String!, $displayName: String) @auth(level: USER) {
  user_upsert(data: {
    uid_expr: "auth.uid",
    email: $email,
    displayName: $displayName
  })
}

# User: Add review (one per movie per user)
mutation AddReview($movieId: UUID!, $rating: Int!, $text: String) 
  @auth(level: USER) {
  review_upsert(data: {
    movie: { id: $movieId },
    user: { uid_expr: "auth.uid" },
    rating: $rating,
    text: $text
  })
}

# User: Delete my review
mutation DeleteReview($id: UUID!) @auth(level: USER) {
  review_delete(
    first: { where: {
      id: { eq: $id },
      user: { uid: { eq_expr: "auth.uid" }}
    }}
  )
}

Realtime Queries

# queries.gql (realtime additions)

# Auto-refresh: this single-entity lookup refreshes automatically
# when any mutation modifies this specific movie. No @refresh needed.
query GetMovie($id: UUID!) @auth(level: PUBLIC) {
  movie(id: $id) {
    id title genre rating releaseYear description
    metadata: movieMetadata_on_movie { director runtime }
    reviews: reviews_on_movie(orderBy: [{ createdAt: DESC }], limit: 10) {
      rating text createdAt
      user { displayName }
    }
  }
}

# Event-driven: Simple refresh when any movie is added
query ListMoviesSimple @auth(level: PUBLIC) @refresh(onMutationExecuted: { operation: "AddMovie" }) {
  movies { id title }
}

# Counterpart mutation for ListMoviesSimple
mutation AddMovie($title: String!) @auth(level: USER) {
  movie_insert(data: { title: $title })
}

# Event-driven: Refresh only when a movie of the same genre is added
# Demonstrates the use of 'condition' and 'mutation.variables'
query ListMoviesByGenre($genre: String!) @auth(level: PUBLIC)
  @refresh(onMutationExecuted: {
    operation: "AddMovieWithGenre",
    condition: "mutation.variables.genre == request.variables.genre"
  }) {
  movies(where: { genre: { eq: $genre } }) { id title }
}

# Counterpart mutation for ListMoviesByGenre
mutation AddMovieWithGenre($title: String!, $genre: String!) @auth(level: USER) {
  movie_insert(data: { title: $title, genre: $genre })
}

# Event-driven: Refresh user profile when updated
# Demonstrates condition based on auth context
query MyProfile @auth(level: USER)
  @refresh(onMutationExecuted: {
    operation: "UpdateProfile",
    condition: "mutation.auth.uid == request.auth.uid"
  }) {
  user(uid_expr: "auth.uid") { id name }
}

# Counterpart mutation for MyProfile
mutation UpdateProfile($name: String!) @auth(level: USER) {
  user_update(id_expr: "auth.uid", data: { name: $name })
}

# Time-based: live leaderboard refreshing every 30 seconds
query MovieLeaderboard
  @auth(level: PUBLIC)
  @refresh(every: { seconds: 30 }) {
  movies(orderBy: [{ rating: DESC }], limit: 10) {
    id title rating
  }
}

import { listMoviesRef, movieLeaderboardRef } from '@movie-app/dataconnect';
import { subscribe } from 'firebase/data-connect';

// Subscribe to movie list — refreshes when AddReview mutation runs
const unsubMovies = subscribe(listMoviesRef({ genre: 'Action' }), {
  onNext: (result) => updateMovieList(result.data.movies),
  onError: (error) => console.error(error)
});

// Subscribe to leaderboard — refreshes every 30 seconds
const unsubLeaderboard = subscribe(movieLeaderboardRef(), {
  onNext: (result) => updateLeaderboard(result.data.movies),
  onError: (error) => console.error(error)
});

// Cleanup
// unsubMovies();
// unsubLeaderboard();

---

E-Commerce Store

Products, orders, and cart management with user authentication.

Schema

# schema.gql

type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  email: String! @unique
  name: String
  shippingAddress: String
}

type Product @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String! @index
  description: String
  price: Float!
  stock: Int! @default(value: 0)
  category: String @index
  imageUrl: String
}

type CartItem @table(key: ["user", "product"]) {
  user: User!
  product: Product!
  quantity: Int!
}

enum OrderStatus {
  PENDING
  PAID
  SHIPPED
  DELIVERED
  CANCELLED
}

type Order @table {
  id: UUID! @default(expr: "uuidV4()")
  user: User!
  status: OrderStatus! @default(value: PENDING)
  total: Float!
  shippingAddress: String!
  createdAt: Timestamp! @default(expr: "request.time")
}

type OrderItem @table {
  id: UUID! @default(expr: "uuidV4()")
  order: Order!
  product: Product!
  quantity: Int!
  priceAtPurchase: Float!
}

Operations

# Public: Browse products
query ListProducts($category: String, $search: String) @auth(level: PUBLIC) {
  products(where: {
    category: { eq: $category },
    name: { contains: $search },
    stock: { gt: 0 }
  }) {
    id name price stock imageUrl
  }
}

# User: View cart
query MyCart @auth(level: USER) {
  cartItems(where: { user: { uid: { eq_expr: "auth.uid" }}}) {
    quantity
    product { id name price imageUrl stock }
  }
}

# User: Add to cart
mutation AddToCart($productId: UUID!, $quantity: Int!) @auth(level: USER) {
  cartItem_upsert(data: {
    user: { uid_expr: "auth.uid" },
    product: { id: $productId },
    quantity: $quantity
  })
}

# User: Checkout (transactional)
mutation Checkout($shippingAddress: String!) 
  @auth(level: USER) 
  @transaction {
  # Query cart items
  query @redact {
    cartItems(where: { user: { uid: { eq_expr: "auth.uid" }}}) 
      @check(expr: "this.size() > 0", message: "Cart is empty") {
      quantity
      product { id price }
    }
  }
  # Create order (in real app, calculate total from cart)
  order_insert(data: {
    user: { uid_expr: "auth.uid" },
    shippingAddress: $shippingAddress,
    total: 0  # Calculate in app logic
  })
}

---

Blog with Permissions

Multi-author blog with role-based permissions.

Schema

# schema.gql

type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  email: String! @unique
  name: String!
  bio: String
}

enum UserRole {
  VIEWER
  AUTHOR
  EDITOR
  ADMIN
}

type BlogPermission @table(key: ["user"]) {
  user: User!
  role: UserRole! @default(value: VIEWER)
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type Post @table {
  id: UUID! @default(expr: "uuidV4()")
  author: User!
  title: String! @searchable
  content: String! @searchable
  status: PostStatus! @default(value: DRAFT)
  publishedAt: Timestamp
  createdAt: Timestamp! @default(expr: "request.time")
  updatedAt: Timestamp! @default(expr: "request.time")
}

type Comment @table {
  id: UUID! @default(expr: "uuidV4()")
  post: Post!
  author: User!
  content: String!
  createdAt: Timestamp! @default(expr: "request.time")
}

Operations with Role Checks

# Public: Read published posts
query PublishedPosts @auth(level: PUBLIC) {
  posts(
    where: { status: { eq: PUBLISHED }},
    orderBy: [{ publishedAt: DESC }]
  ) {
    id title content publishedAt
    author { name }
  }
}

# Author+: Create post
mutation CreatePost($title: String!, $content: String!) 
  @auth(level: USER) 
  @transaction {
  # Check user is at least AUTHOR
  query @redact {
    blogPermission(key: { user: { uid_expr: "auth.uid" }})
      @check(expr: "this != null", message: "No permission record") {
      role @check(expr: "this in ['AUTHOR', 'EDITOR', 'ADMIN']", message: "Must be author+")
    }
  }
  post_insert(data: {
    author: { uid_expr: "auth.uid" },
    title: $title,
    content: $content
  })
}

# Editor+: Publish any post
mutation PublishPost($id: UUID!) 
  @auth(level: USER) 
  @transaction {
  query @redact {
    blogPermission(key: { user: { uid_expr: "auth.uid" }}) {
      role @check(expr: "this in ['EDITOR', 'ADMIN']", message: "Must be editor+")
    }
  }
  post_update(id: $id, data: {
    status: PUBLISHED,
    publishedAt_expr: "request.time"
  })
}

# Admin: Grant role
mutation GrantRole($userUid: String!, $role: UserRole!) 
  @auth(level: USER) 
  @transaction {
  query @redact {
    blogPermission(key: { user: { uid_expr: "auth.uid" }}) {
      role @check(expr: "this == 'ADMIN'", message: "Must be admin")
    }
  }
  blogPermission_upsert(data: {
    user: { uid: $userUid },
    role: $role
  })
}

---

Native SQL Examples

For scenarios where standard GraphQL cannot express the required database logic, use Native SQL.

Basic SELECT with field aliasing

query GetMoviesByGenre($genre: String!, $limit: Int!) @auth(level: PUBLIC) {
  movies: _select(
    sql: """
      SELECT id, title, release_year, rating
      FROM movie
      WHERE genre = $1
      ORDER BY release_year DESC
      LIMIT $2
    """,
    params: [$genre, $limit]
  )
}

Basic UPDATE

mutation UpdateMovieRating($movieId: UUID!, $newRating: Float!) @auth(level: USER) {
  _execute(
    sql: """
      UPDATE movie
      SET rating = $2
      WHERE id = $1
    """,
    params: [$movieId, $newRating]
  )
}

Advanced aggregation with RANK

query GetMoviesRankedByRating @auth(level: PUBLIC) {
  _select(
    sql: """
      SELECT
        id,
        title,
        rating,
        RANK() OVER (ORDER BY rating DESC) as rank
      FROM movie
      WHERE rating IS NOT NULL
      LIMIT 20
    """,
    params: []
  )
}

UPDATE with RETURNING and Auth Context

mutation UpdateMyReviewText($movieId: UUID!, $newText: String!) @auth(level: USER) {
  updatedReview: _executeReturningFirst(
    sql: """
      UPDATE review
      SET text = $2
      WHERE movie_id = $1 AND user_uid = $3
      RETURNING movie_id, user_uid, rating, text
    """,
    params: [$movieId, $newText, {_expr: "auth.uid"}]
  )
}

Advanced CTE with upserts (atomic get-or-create)

Note: Data-modifying CTEs are only supported by `_execute`, not `_executeReturning`.

mutation CreateMovieCTE($movieId: UUID!, $userUid: String!, $reviewId: UUID!) @auth(level: USER) {
  _execute(
    sql: """
      WITH
      new_user AS (
        INSERT INTO "user" (uid, email, display_name)
        VALUES ($2, 'auto@example.com', 'Auto-Generated User')
        ON CONFLICT (uid) DO NOTHING
        RETURNING uid
      ),
      movie AS (
        INSERT INTO movie (id, title, poster_url, release_year, genre)
        VALUES ($1, 'Auto-Generated Movie', 'https://placeholder.com', 2025, 'Sci-Fi')
        ON CONFLICT (id) DO NOTHING
        RETURNING id
      )
      INSERT INTO review (id, movie_id, user_uid, rating, text, created_at)
      VALUES (
        $3,
        $1,
        $2,
        5,
        'Good!',
        NOW()
      )
    """,
    params: [$movieId, $userUid, $reviewId]
  )
}

Multi-statement Transactions

Because mutation operations are single requests, you can chain multiple _execute commands within a @transaction to ensure they all succeed or fail together.

mutation SafeTransfer($from: UUID!, $to: UUID!, $amount: Float!) @auth(level: USER) @transaction {
  deduct: _execute(
    sql: "UPDATE account SET balance = balance - $2 WHERE id = $1", 
    params: [$from, $amount]
  )
  add: _execute(
    sql: "UPDATE account SET balance = balance + $2 WHERE id = $1", 
    params: [$to, $amount]
  )
}

Use of extensions (e.g. PostGIS for geospatial data)

Prerequisite: You must enable the extension on your underlying Cloud SQL instance by connecting to your database as the postgres user and running:

CREATE EXTENSION IF NOT EXISTS postgis;

query GetNearbyActiveRestaurants($userLong: Float!, $userLat: Float!, $maxDistanceMeters: Float!) @auth(level: USER) {
  nearby: _select(
    sql: """
      SELECT 
        id, 
        name,
        tags,
        ST_Distance(
          ST_MakePoint((metadata->>'longitude')::float, (metadata->>'latitude')::float)::geography, 
          ST_MakePoint($1, $2)::geography
        ) as distance_meters
      FROM restaurant
      WHERE active = true
        AND metadata ? 'longitude' AND metadata ? 'latitude'
        AND ST_DWithin(
          ST_MakePoint((metadata->>'longitude')::float, (metadata->>'latitude')::float)::geography, 
          ST_MakePoint($1, $2)::geography, 
          $3
        )
      ORDER BY distance_meters ASC
      LIMIT 10
    """,
    params: [$userLong, $userLat, $maxDistanceMeters]
  )
}

After running the query using a client SDK, the result will be in `data.nearby`.

Cloud Functions Integration Reference

Use this reference to handle database events in SQL Connect by triggering Cloud Functions in response to mutation executions.

---

Core Trigger Configuration

To handle a mutation execution, define the onMutationExecuted event handler.

🚨 Critical Infinite Loop Constraint

Unlike document-based database triggers (like Firestore or Realtime Database), SQL Connect event triggers do not provide a "before" snapshot of the data. Because SQL Connect proxies requests directly to PostgreSQL, "before" states cannot be resolved transactionally.

• Warning: If onMutationExecuted executes a SQL Connect mutation, it can trigger another onMutationExecuted trigger in a cascading loop. Make sure that onMutationExecuted has a filter on operation to reduce the chance of infinite loops.
• Rule: Ensure that no mutation executed inside the function can ever trigger the handler itself, even indirectly.

Location & Region Matching Rule

The Cloud Function region option must match your SQL Connect service location. You must explicitly configure the region parameter (e.g., 'us-central1') in the trigger options to match the location specified in dataconnect.yaml.

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const logMutation = onMutationExecuted(
  {
    region: "europe-west1" // Must match the SQL Connect service location
  },
  (event) => {
    logger.info("A mutation was executed!", {
      eventId: event.id,
      type: event.type
    });
  }
);

---

Event Filtering

To prevent unnecessary function invocations and infinite execution loops, always specify narrow filters using service and operation attributes.

• `service` & `operation` (Recommended): Always specify these to restrict the trigger to a specific mutation in your project.
• `connector` (Optional): Can be omitted if you want to trigger on the same operation name across multiple connectors. Specify it only if you need to restrict the trigger to a specific connector.

Comprehensive Example

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

// Triggers for "CreateUser" mutation in "myAppService" service.
// 'connector' is omitted (optional), meaning it matches "CreateUser" in any connector.
export const onUserCreate = onMutationExecuted(
  {
    service: "myAppService",
    operation: "CreateUser",
    // region: "us-central1" // Optional: defaults to us-central1, change if database is elsewhere
  },
  (event) => {
    logger.info("A new user was created!");
  }
);

// Advanced: Trigger using wildcards or capture variables
export const onMutationCaptures = onMutationExecuted(
  {
    service: "myAppService",
    operation: "{operation}", // Captures matching operation name dynamically
  },
  (event) => {
    const triggeredOp = event.params.operation;
    logger.info(`Captured operation execution: ${triggeredOp}`);
  }
);

---

Accessing User Authentication Context

Extract security credentials about the caller who executed the mutation using event.authType and event.authId.

Auth Context Mappings

Auth Extraction Example

export const processSensitiveMutation = onMutationExecuted(
  { operation: "UpdateFinancials" },
  (event) => {
    if (event.authType === "admin") {
      console.log("Elevated admin mutation execution.");
    } else {
      console.log(`Mutation initiated by user: ${event.authId}`);
    }
  }
);

---

Parsing Event Data Payloads

The trigger payload provides inputs passed to the mutation (payload.variables) and return values generated from the execution (payload.data).

Event Payload Structure

{
  "authType": "app_user",
  "authId": "user-123",
  "data": {
    "payload": {
      "variables": {
        "movieId": "m-1",
        "rating": 5
      },
      "data": {
        "review_insert": {
          "id": "r-99"
        }
      },
      "errors": []
    }
  }
}

• `event.data.payload.variables`: Inputs passed to the mutation.
• `event.data.payload.data`: Fields returned by the mutation execution.
• `event.data.payload.errors`: Array of execution errors. Empty if successful.

Payload Extraction Example

import { onMutationExecuted } from "firebase-functions/dataconnect";
import { logger } from "firebase-functions";

export const onNewReview = onMutationExecuted(
  {
    service: "myAppService",
    connector: "reviews",
    operation: "CreateReview",
  },
  (event) => {
    // Extract input variables passed to the mutation
    const inputVariables = event.data.payload.variables;

    // Extract returned fields from the database write
    const returnedFields = event.data.payload.data;

    logger.info(`Processed review ${returnedFields.review_insert.id} for movie ${inputVariables.movieId}`);
  }
);

Configuration Reference

Contents

• Project Structure
• dataconnect.yaml
• connector.yaml
• Firebase CLI Commands
• Emulator
• Deployment

---

Project Structure

project-root/
├── firebase.json           # Firebase project config
└── dataconnect/
    ├── dataconnect.yaml    # Service configuration
    ├── schema/
    │   └── schema.gql      # Data model (types, relationships)
    └── connector/
        ├── connector.yaml  # Connector config + SDK generation
        ├── queries.gql     # Query operations
        └── mutations.gql   # Mutation operations (optional separate file)

---

dataconnect.yaml

Main SQL Connect service configuration:

specVersion: "v1"
serviceId: "my-service"
location: "us-central1"
schemaValidation: "STRICT" # or "COMPATIBLE"
schema:
  source: "./schema"
  datasource:
    postgresql:
      database: "fdcdb"
      cloudSql:
        instanceId: "my-instance"
connectorDirs: ["./connector"]

Cloud SQL Configuration

schema:
  datasource:
    postgresql:
      database: "my-database"      # Database name
      cloudSql:
        instanceId: "my-instance"  # Cloud SQL instance ID

---

connector.yaml

Connector configuration and SDK generation:

connectorId: "default"
generate:
  javascriptSdk:
    outputDir: "../web/src/lib/dataconnect"
    package: "@myapp/dataconnect"
  kotlinSdk:
    outputDir: "../android/app/src/main/kotlin/com/myapp/dataconnect"
    package: "com.myapp.dataconnect"
  swiftSdk:
    outputDir: "../ios/MyApp/DataConnect"

SDK Generation Options

---

Firebase CLI Commands

Initialize SQL Connect

# Interactive setup
npx -y firebase-tools@latest init dataconnect

# Set project
npx -y firebase-tools@latest use <project-id>

Local Development

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

# Start with database seed data
npx -y firebase-tools@latest emulators:start --only dataconnect --import=./seed-data

# Generate SDKs
npx -y firebase-tools@latest dataconnect:sdk:generate

# Watch for schema changes (auto-regenerate)
npx -y firebase-tools@latest dataconnect:sdk:generate --watch

Schema Management

# Compare local schema to production
npx -y firebase-tools@latest dataconnect:sql:diff


# Apply migration
npx -y firebase-tools@latest dataconnect:sql:migrate

Deployment

# Deploy SQL Connect service
npx -y firebase-tools@latest deploy --only dataconnect

# Deploy specific connector
npx -y firebase-tools@latest deploy --only dataconnect:connector-id

# Deploy with schema migration
npx -y firebase-tools@latest deploy --only dataconnect --force

---

Emulator

Start Emulator

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

Default ports:

• SQL Connect: 9399
• PostgreSQL: 9939 (local PostgreSQL instance)

Emulator Configuration (firebase.json)

{
  "emulators": {
    "dataconnect": {
      "port": 9399
    }
  }
}

Connect from SDK

// Web
import { connectDataConnectEmulator } from 'firebase/data-connect';
connectDataConnectEmulator(dc, 'localhost', 9399);

// Android
connector.dataConnect.useEmulator("10.0.2.2", 9399)

// iOS
connector.useEmulator(host: "localhost", port: 9399)

Seed Data

Create seed data files and import:

# Export current emulator data
npx -y firebase-tools@latest emulators:export ./seed-data

# Start with seed data
npx -y firebase-tools@latest emulators:start --only dataconnect --import=./seed-data

---

Deployment

Deploy Workflow

1. Test locally with emulator 2. Generate SQL diff: npx -y firebase-tools@latest dataconnect:sql:diff 3. Review migration: Check breaking changes 4. Deploy: npx -y firebase-tools@latest deploy --only dataconnect

Schema Migrations

SQL Connect auto-generates PostgreSQL migrations:

# Preview migration
npx -y firebase-tools@latest dataconnect:sql:diff

# Apply migration (interactive)
npx -y firebase-tools@latest dataconnect:sql:migrate

# Force migration (non-interactive)
npx -y firebase-tools@latest dataconnect:sql:migrate --force

Breaking Changes

Some schema changes require special handling:

• Removing required fields
• Changing field types
• Removing tables

Use --force flag to acknowledge breaking changes during deploy.

CI/CD Integration

# GitHub Actions example
- name: Deploy SQL Connect
  run: |
    npx -y firebase-tools@latest deploy --only dataconnect --token ${{ secrets.FIREBASE_TOKEN }} --force

---

VS Code Extension

Install "Firebase SQL Connect" extension for:

• Schema intellisense and validation
• GraphQL operation testing
• Emulator integration
• SDK generation on save

Extension Settings

{
  "firebase.dataConnect.autoGenerateSdk": true,
  "firebase.dataConnect.emulator.port": 9399
}

Data Seeding & Bulk Operations Reference

Use this reference to populate local development databases for prototyping, execute CI/CD tests, and perform bulk data migrations in production environments.

---

1. Local Prototyping: Data Seeding

Local database seeding allows developer agents to test queries, mutations, complex joins, and role-based access control (RBAC) under realistic conditions.

The seed_data.gql Workflow

Always write prototyping seed mutations to `dataconnect/seed_data.gql` (located at the project root, not inside connector/). This file is excluded from production deployments and client SDK generation.

⚠️ Seeding Directives Rule

Do not declare `@auth` directives inside `seed_data.gql` mutations. Since this file runs locally to establish a test state and is not an exposed API connector endpoint, authorization directives are completely unnecessary and should be omitted.

Seeding Independent Tables (FK Order)

When executing standard bulk insertions (_insertMany) across multiple tables, always insert parent tables before referencing them in child or join tables.

# dataconnect/seed_data.gql
mutation SeedIndependentTables @transaction {
  # Step 1: Seed parent tables
  movie_insertMany(data: [
    { id: "m-1", title: "Inception", genre: "sci-fi" },
    { id: "m-2", title: "The Matrix", genre: "action" }
  ])

  actor_insertMany(data: [
    { id: "a-1", name: "Leonardo DiCaprio" },
    { id: "a-2", name: "Keanu Reeves" }
  ])

  # Step 2: Seed join table (depends on pre-existing parent IDs)
  movieActor_insertMany(data: [
    { movie: { id: "m-1" }, actor: { id: "a-1" }, role: "main" },
    { movie: { id: "m-2" }, actor: { id: "a-2" }, role: "main" }
  ])
}

Seeding Related Tables (Nested Relational Inserts)

To seed parent-child relationships atomically, perform a nested relational insert using literal payloads. This avoids the need to manage foreign keys manually.

• Omit Parent Foreign Keys: Do not specify the parent foreign key (e.g. movieId) inside the nested child objects. The database engine automatically maps and resolves them.

# dataconnect/seed_data.gql
mutation SeedMoviesAndReviews @transaction {
  movie_insert(data: {
    id: "m-1",
    title: "Inception",
    genre: "sci-fi",
    # Nested reviews are inserted atomically without manual movieId mapping
    reviews_on_movie: [
      {
        id: "r-1",
        rating: 5,
        reviewText: "Mind-bending masterpiece!",
        user: { id: "user-123" } # Links to pre-existing user
      },
      {
        id: "r-2",
        rating: 4,
        reviewText: "Visually stunning but complex.",
        user: { id: "user-456" }
      }
    ]
  })
}

Resetting Seed Data

For continuous testing or CI/CD flows, return the database to a zero state using one of the following strategies:

• Strategy A: Upsert Many (Idempotent): Re-run seeds using _upsertMany mutations. This overrides existing records or inserts missing ones in a single step.
• Strategy B: Delete and Re-Insert: Call _deleteMany(all: true) on your tables in reverse foreign key order (child/join tables first, then parent tables) followed by your seed _insertMany operations.

# dataconnect/seed_data.gql
mutation ResetDatabaseToOriginalState @transaction {
  # Delete child tables first to prevent FK constraint violations
  movieActor_deleteMany(all: true)
  actor_deleteMany(all: true)
  movie_deleteMany(all: true)
  # (Optional) Follow up with new _insertMany steps
}

---

2. Production: Admin SDK Bulk Operations

Use the Firebase Admin SDK for Node.js for bulk data loading and production migrations. Avoid running large mutations directly via raw GraphQL endpoints in production.

The Admin SDK provides direct, type-safe methods: dc.insert, dc.insertMany, dc.upsert, and dc.upsertMany.

SDK Bulk APIs Features:

• No Manual GraphQL Strings: Do not write raw mutation {...} strings when executing privileged batch operations. Pass Javascript objects directly.
• Relational Support: The bulk helper methods natively support nested 1:Many relationships inside the input arrays.

SDK Bulk Operations Example

import { initializeApp } from 'firebase-admin/app';
import { getDataConnect } from 'firebase-admin/data-connect';

const app = initializeApp();
const dc = getDataConnect({ location: "us-west2", serviceId: "my-service" });

const bulkMoviesData = [
  {
    id: "m-1",
    title: "Inception",
    genre: "sci-fi",
    // Atomic nested relational inserts are fully supported
    reviews_on_movie: [
      {
        rating: 5,
        reviewText: "Incredible concept.",
        user: { id: "user-123" }
      }
    ]
  },
  {
    id: "m-2",
    title: "The Matrix",
    genre: "action",
    reviews_on_movie: [
      {
        rating: 5,
        reviewText: "A classic.",
        user: { id: "user-456" }
      }
    ]
  }
];

// Atomically load thousands of records (parent and child tables combined)
const response = await dc.insertMany("movie", bulkMoviesData);

---

3. Production: Bulk Operations via raw SQL

When working with a stable schema in production, you can use standard SQL tools (like psql or Cloud SQL import pipelines) to execute bulk data updates directly on the PostgreSQL instance.

🚨 Critical SQL Operations Constraint

Never modify your database schema directly using SQL tools. Direct schema alterations (ALTER TABLE, CREATE INDEX, etc.) outside of your schema.gql file will bypass SQL Connect's schema compiler, breaking connector mappings, and causing active client SDK integrations to fail.

Native SQL Operations

Always default to Native GraphQL. Use Native SQL only when you need database-specific features not available in GraphQL (e.g., PostGIS, Window Functions, Complex Aggregations, or specific DML CTEs).

Core Agent Constraints

When generating Native SQL operations, you are bypassing GraphQL and talking directly to PostgreSQL. You MUST adhere to these strict constraints:

1. Operation Syntax Isolation: Never mix Native SQL positional parameters ($1) with standard GraphQL named variables ($id). The sql: argument MUST be a hardcoded string literal block ("""SELECT..."""), not a GraphQL variable. 2. Table & Column Mapping (Case Sensitivity):

• Default `snake_case` Conversion: By default, SQL Connect converts PascalCase types and camelCase fields to snake_case in the database.
• Schema: type UserProfile { releaseYear: Int } -> Native SQL: SELECT release_year FROM user_profile
• Explicit Overrides (Requires Double Quotes): If the schema uses @table(name: "ExactName") or @col(name: "ExactCol"), you MUST wrap the identifier in double quotes if it contains capital letters (e.g., SELECT * FROM "ExactName"). Without quotes, Postgres folds it to lowercase and fails validation.

Syntax rules & limitations

Native SQL enforces strict parsing rules to ensure security and prevent SQL injection:

• String Literals Only: The sql argument must be a hardcoded string literal block ("""SELECT...""") directly in the .gql file. It cannot be a GraphQL variable.
• Validation: Do NOT use DDL in any operations (modify the schema.gql file instead for table/column changes). Furthermore, query operations cannot contain DML and must start with SELECT, TABLE, or WITH.
• Parameters: Use strict positional parameters ($1, $2) that match the params array order. Named parameters ($id, :name) are forbidden.
• Comments: Use block comments (/* ... */). Line comments (--) are forbidden because they can truncate subsequent clauses during query compilation. If you comment out a line containing a parameter (e.g., /* WHERE id = $1 */), you must also remove that parameter from the params list, or it will fail with unused parameter: $1.
• Strings: Extended string literals (E'...') and dollar-quoted strings ($$...$$) are supported.
• Context Maps (`_expr`): Variables cannot be used inside _expr fields; to ensure security, _expr must be a static string (e.g., {_expr: "auth.uid"}, not {_expr: $uidVar}).

Native SQL Root Fields

Operations are executed using the permissions granted to the SQL Connect service account. You can alias the root field (e.g., movies: _select) to make the client response cleaner (data.movies instead of data._select).

Note on `Any` Return Types: Because Native SQL completely bypasses GraphQL's strong typing, queries like _select and _executeReturning return the generic Any scalar type. The generated client SDKs (TypeScript, Swift, Kotlin, Dart) will type this as any (or equivalent). AGENT INSTRUCTION: When you generate client-side code that consumes these operations, you MUST manually cast or validate the shape of the data, as the typical type safety of SQL Connect will not be present.

Use these root fields in query or mutation operations:

Query Fields (Read-Only)

• _select: Executes a SQL query returning zero or more rows. Returns [Any].

    query GetMovies($genre: String!) @auth(level: PUBLIC) {
      movies: _select(
        sql: "SELECT id, title FROM movie WHERE genre = $1",
        params: [$genre]
      )
    }

• _selectFirst: Executes a SQL query expected to return zero or one row. Returns Any or null.

    query GetTotalReviews @auth(level: PUBLIC) {
      stats: _selectFirst(
        sql: "SELECT COUNT(*) as total_reviews FROM review"
      ) # params can be omitted if empty
    }

Mutation Fields (DML)

• _execute: Executes DML (INSERT, UPDATE, DELETE). Returns Int (number of rows affected).
• Note 1: RETURNING clauses are ignored in the result.
• Note 2: Only _execute supports Data-Modifying Common Table Expressions (e.g., WITH new_row AS (INSERT...)).

    mutation UpdateRating($id: UUID!, $rating: Float!) @auth(level: USER) {
      _execute(
        sql: "UPDATE movie SET rating = $2 WHERE id = $1",
        params: [$id, $rating]
      )
    }

• _executeReturning: Executes DML with a RETURNING clause. Returns [Any]. Data-Modifying CTEs are not supported.

    mutation DeleteUserReviews($uid: String!) @auth(level: USER) {
      deletedReviews: _executeReturning(
        sql: "DELETE FROM review WHERE user_id = $1 RETURNING id, rating",
        params: [{_expr: "auth.uid"}]
      )
    }

• _executeReturningFirst: Executes DML with RETURNING, expecting zero or one row. Returns Any or null. Data-Modifying CTEs are not supported.

    mutation UpdateMyReview($movieId: UUID!, $text: String!) @auth(level: USER) {
      updatedReview: _executeReturningFirst(
        sql: """
          UPDATE review SET text = $2 
          WHERE movie_id = $1 AND user_id = $3 
          RETURNING id, text
        """,
        params: [$movieId, $text, {_expr: "auth.uid"}]
      )
    }

PostgreSQL Extensions

Native SQL allows you to directly query and utilize PostgreSQL extensions, such as PostGIS, without needing to map complex geometry types into your GraphQL schema or alter your underlying tables (e.g., using JSON operators to extract values and pass them into ST_MakePoint).

Note: You must enable the extension on your underlying Cloud SQL instance by connecting as the `postgres` user and running `CREATE EXTENSION IF NOT EXISTS ...;`

(See `examples.md` for a full `GetNearbyActiveRestaurants` implementation).

⚠️ Security: Stored Procedures & Dynamic SQL

SQL Connect parameterizes inputs at the GraphQL boundary automatically. However, if your Native SQL calls custom PL/pgSQL stored procedures, you must manually prevent 2nd-order SQL injection:

• NEVER concatenate user input into an EXECUTE string (EXECUTE 'UPDATE ' || table || ' SET x=' || val;).
• DO use the USING clause to bind data values safely.
• DO use format('%I') for safe database identifier injection.
• DO validate dynamic table/column names against a strict hardcoded allowlist.

Secure PL/pgSQL Pattern:

CREATE OR REPLACE PROCEDURE secure_update(target_table TEXT, new_value TEXT, row_id INT)
LANGUAGE plpgsql AS $$
BEGIN
    -- 1. Strict Allowlist for Identifiers
    IF target_table NOT IN ('orders', 'users', 'inventory') THEN
        RAISE EXCEPTION 'Invalid table name';
    END IF;

    -- 2. format(%I) for Identifiers, USING for Data
    EXECUTE format('UPDATE %I SET status = $1 WHERE id = $2', target_table)
    USING new_value, row_id;
END;
$$;

Operations Reference

Contents

• Generated Fields
• Queries
• Mutations
• Key Scalars
• Multi-Step Operations

---

Generated Fields

SQL Connect auto-generates fields for each @table type:

Relation Fields

For a Post with author: User!:

• post.author - Navigate to related User
• user.posts_on_author - Reverse: all Posts by User

For many-to-many via MovieActor:

• movie.actors_via_MovieActor - Get all actors
• actor.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.

1. Location: .dataconnect/schema/main/ (relative to project root). 2. 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. 3. Validation: Always run firebase dataconnect:compile to 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

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
  })
}

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 })
}

Realtime Reference

Contents

• When to Use What
• The @refresh Directive
• CEL Bindings in Conditions
• Implicit Entity Refresh signals

---

When to Use What

SQL Connect provides three mechanisms for live data updates. Pick the right one based on what you're querying:

List queries require explicit @refresh to tell SQL Connect which mutations affect the result set.

Clients consume all three using subscribe() instead of execute(). See sdks.md for per-platform subscribe patterns.

---

The @refresh Directive

@refresh is a repeatable directive applied to queries. It defines when connected subscribers should receive updated data.

Time-Based Polling (every)

Keep the query fresh with a recommended refresh interval. Note that every and mutation signals can be used together; whichever signal arrives first will trigger the refresh.

query MovieLeaderboard
  @auth(level: PUBLIC)
  @refresh(every: { seconds: 30 }) {
  movies(orderBy: [{ rating: DESC }], limit: 10) {
    id title rating
  }
}

Constraints:

• The every argument takes a duration object: { seconds: Int }
• Minimum: { seconds: 10 } — protects against excessive server load
• Maximum: { hours: 1 } (3600 seconds)
• Values outside this range fail validation at deploy time

Use time-based polling when freshness matters but you don't have a specific mutation to listen for (e.g., dashboards aggregating external data, stock tickers, activity feeds).

Explicit Mutation Signals (onMutationExecuted)

Trigger a query refresh when a specific mutation executes. This is the most common pattern for keeping lists in sync.

# Example with condition (refreshes only when the condition is met)
query ChatRoom($roomId: UUID!) @auth(level: PUBLIC)
  @refresh(onMutationExecuted: {
    operation: "SendMessage",
    condition: "mutation.variables.roomId == request.variables.roomId"
  }) {
  messages(where: {roomId: {eq: $roomId}}, orderBy: [{createTime: DESC}], limit: 50) {
    author content createTime
  }
}

# Example without condition (refreshes on any execution of the named mutation)
query ListAllMessages
  @auth(level: PUBLIC)
  @refresh(onMutationExecuted: {
    operation: "SendMessage"
  }) {
  messages { id content }
}

Arguments:

• `operation` (required): The name of the mutation operation to listen for. Must match the mutation's operation name exactly.
• `condition` (optional): A CEL expression that must evaluate to true for the refresh to fire. Without a condition, every execution of the named mutation triggers a refresh.

It's highly recommended to define fine granular conditions. Inaccurate refresh policies could consume Postgres resources and make your app slower.

Use conditions to scope refreshes precisely — a review list should only refresh when the mutation targets the same movie, not every review across the entire app.

Combining Multiple @refresh Directives

Since @refresh is repeatable, you can combine strategies on a single query:

query ActiveOrders($userId: UUID!)
  @auth(level: USER)
  @refresh(onMutationExecuted: {
    operation: "UpdateOrderStatus",
    condition: "request.variables.userId == mutation.variables.userId"
  })
  @refresh(every: { seconds: 60 }) {
  orders(where: { user: { id: { eq: $userId }}, status: { ne: DELIVERED }}) {
    id status total updatedAt
  }
}

This query refreshes whenever an order status changes for this user, and polls every 60 seconds as a fallback to catch any updates that might not have a direct mutation trigger.

---

CEL Bindings in Conditions

The condition expression in onMutationExecuted has access to two contexts:

request — The Query Subscription

The state of the query being subscribed to.

mutation — The Triggering Event

The mutation that just executed.

Common Patterns

# Refresh only when the mutation targets the same entity
"request.variables.id == mutation.variables.id"

# Refresh only when the same user who subscribed makes a change
"request.auth.uid == mutation.auth.uid"

# Refresh when a specific field value matches a condition
"request.auth.uid == mutation.auth.uid && mutation.variables.status == 'PUBLISHED'"

# Refresh when a specific flag is set in the mutation
"mutation.variables.isPublic == true"

---

Implicit Entity Refresh signals

For single-entity lookups by unique identifier, SQL Connect handles refreshes automatically — no @refresh directive needed.

What qualifies:

• Queries fetching one entity by its primary key: movie(id: $id), user(key: { uid: $uid })
• If a single-entity mutation modifies that specific entity, all active subscribers automatically receive the update. Supported operations include:
• _insert(data) or _insertMany(data)
• _upsert(data) or _upsertMany(data)
• _update(id) or _update(key)
• _delete(id) or _delete(key)
• Note: Bulk operations like _updateMany and _deleteMany do not trigger automatic entity refreshes.

What does NOT qualify:

• List queries: movies(where: {...}), users { id name } — these require explicit @refresh
• Nested query with JOINs
• Aggregation
• Native SQL
• Customized Resolver (if supported)

# When subscribed to, this query auto-refreshes when movie data changes — no @refresh needed
query GetMovie($id: UUID!) @auth(level: PUBLIC) {
  movie(id: $id) {
    id title rating description
    reviews_on_movie { rating text user { displayName } }
  }
}

To consume automatic refreshes on the client, use subscribe() instead of execute() — the same client pattern works regardless of whether the refresh is automatic or directive-driven.

Schema Reference

Contents

• Defining Types
• Core Directives
• Relationships
• Data Types
• Enumerations

---

Defining Types

Types with @table map to PostgreSQL tables. SQL Connect auto-generates an implicit id: UUID! primary key.

type Movie @table {
  # id: UUID! is auto-added
  title: String!
  releaseYear: Int
  genre: String
}

Customizing Tables

type Movie @table(name: "movies", key: "id", singular: "movie", plural: "movies") {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int @col(name: "release_year")
  genre: String @col(dataType: "varchar(20)")
}

User Table with Auth

type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  email: String! @unique
  displayName: String @col(dataType: "varchar(100)")
  createdAt: Timestamp! @default(expr: "request.time")
}

---

Core Directives

@table

Defines a database table.

@col

Customizes column mapping.

@default

Sets default value for inserts.

Common expressions:

• uuidV4() - Generate UUID
• auth.uid - Current user's Firebase Auth UID
• request.time - Server timestamp

@unique

Adds unique constraint.

type User @table {
  email: String! @unique
}

# Composite unique
type Review @table @unique(fields: ["movie", "user"]) {
  movie: Movie!
  user: User!
  rating: Int
}

@index

Creates database index for query performance.

type Movie @table @index(fields: ["genre", "releaseYear"], order: [ASC, DESC]) {
  title: String! @index
  genre: String
  releaseYear: Int
}

@searchable

Enables full-text search on String fields.

type Post @table {
  title: String! @searchable
  body: String! @searchable(language: "english")
}

# Usage
query SearchPosts($q: String!) @auth(level: PUBLIC) {
  posts_search(query: $q) { id title body }
}

---

Relationships

One-to-Many (Implicit Foreign Key)

type Post @table {
  id: UUID! @default(expr: "uuidV4()")
  author: User!  # Creates authorId foreign key
  title: String!
}

type User @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String!
  # Auto-generated: posts_on_author: [Post!]!
}

@ref Directive

Customizes foreign key reference.

type Post @table {
  author: User! @ref(fields: "authorId", references: "id")
  authorId: UUID!  # Explicit FK field
}

Cascade behavior:

• Required reference (User!): CASCADE DELETE (post deleted when user deleted)
• Optional reference (User): SET NULL (authorId set to null when user deleted)

One-to-One

Use @unique on the reference field:

type User @table { id: UUID! name: String! }

type UserProfile @table {
  user: User! @unique  # One profile per user
  bio: String
  avatarUrl: String
}

# Query: user.userProfile_on_user

Many-to-Many

Use a join table with composite primary key:

type Movie @table { id: UUID! title: String! }
type Actor @table { id: UUID! name: String! }

type MovieActor @table(key: ["movie", "actor"]) {
  movie: Movie!
  actor: Actor!
  role: String!  # Extra data on relationship
}

# Generated fields:
# - movie.actors_via_MovieActor: [Actor!]!
# - actor.movies_via_MovieActor: [Movie!]!
# - movie.movieActors_on_movie: [MovieActor!]!

---

Data Types

---

Enumerations

enum Status {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type Post @table {
  status: Status! @default(value: DRAFT)
  allowedStatuses: [Status!]
}

Rules:

• Enum names: PascalCase, no underscores
• Enum values: UPPER_SNAKE_CASE
• Values are ordered (for comparison operations)
• Changing order or removing values is a breaking change

---

Views (Advanced)

Map custom SQL queries to GraphQL types:

type MovieStats @view(sql: """
  SELECT
    movie_id,
    COUNT(*) as review_count,
    AVG(rating) as avg_rating
  FROM review
  GROUP BY movie_id
""") {
  movie: Movie @unique
  reviewCount: Int
  avgRating: Float
}

# Query movies with stats
query TopMovies @auth(level: PUBLIC) {
  movies(orderBy: [{ rating: DESC }]) {
    title
    stats: movieStats_on_movie {
      reviewCount avgRating
    }
  }
}

Admin Node SDK

Consult this file when writing server-side code (e.g., Cloud Functions) that needs elevated privileges or needs to impersonate specific users.

Best Practices for Agents

• Understand Operation Storage: SQL Connect queries and mutations are stored on the server like Cloud Functions. Clients do not submit the raw operations. Therefore, whenever you update operations, you must regenerate the SDK and redeploy services that use it.
• Follow Least Privilege: Admin SDKs have unrestricted access by default. Always use impersonation when possible to limit access.
• Impersonation: Use the impersonate parameter to run operations as a specific user or as an unauthenticated user.
• Impersonation Variables: If you call an operation with optional variables and want to pass impersonation options but without variables, you MUST pass undefined as the first argument (variables) to clearly indicate no variables are being provided.
• Admin Operations: If you create operations intended only for administration, define them with @auth(level: NO_ACCESS). This ensures they can only be called via the Admin SDK with unrestricted access.
• Resilient Enum Handling: JavaScript/TypeScript does not enforce exhaustive checks on enums. Always add a default branch to switch statements or an else branch to handle unknown values gracefully when schemas evolve.

Configuration in connector.yaml

To generate an Admin SDK, add the adminNodeSdk block to your connector.yaml:

connectorId: my-connector
generate:
  adminNodeSdk:
    outputDir: "./admin-sdk"
    package: "@dataconnect/admin-generated"
    packageJsonDir: "." # Directory containing package.json

Generation

Run the generation command:

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

Usage Examples

1. Impersonating an Unauthenticated User

Unauthenticated users can only run operations marked as PUBLIC.

import { initializeApp } from "firebase-admin/app";
import { getDataConnect } from "firebase-admin/data-connect";
import { connectorConfig, getSongs } from "@dataconnect/admin-generated";

const adminApp = initializeApp();
const adminDc = getDataConnect(connectorConfig);

const songs = await getSongs(
  adminDc,
  { limit: 4 },
  { impersonate: { unauthenticated: true } }
);

2. Impersonating a Specific User (Cloud Functions)

When using callable Cloud Functions, the authentication token is automatically verified.

import { HttpsError, onCall } from "firebase-functions/https";
import { getMyFavoriteSongs } from "@dataconnect/admin-generated";

export const callableExample = onCall(async (req) => {
    const authClaims = req.auth?.token;
    if (!authClaims) {
        throw new HttpsError("unauthenticated", "Unauthorized");
    }

    const favoriteSongs = await getMyFavoriteSongs(
        adminDc,
        undefined,
        { impersonate: { authClaims } }
    );

    return favoriteSongs;
});

3. Impersonating a Specific User (Plain HTTP)

For non-callable endpoints, you must verify the token yourself.

import { getAuth } from "firebase-admin/auth";
import { onRequest } from "firebase-functions/https";
import { getMyFavoriteSongs } from "@dataconnect/admin-generated";

const auth = getAuth();

export const httpExample = onRequest(async (req, res) => {
    const token = req.header("authorization")?.replace(/^bearer\s+/i, "");
    if (!token) {
        res.sendStatus(401);
        return;
    }
    let authClaims;
    try {
        authClaims = await auth.verifyIdToken(token);
    } catch {
        res.sendStatus(401);
        return;
    }

    const favoriteSongs = await getMyFavoriteSongs(
        adminDc,
        undefined,
        { impersonate: { authClaims } }
    );

    res.send(favoriteSongs);
});

4. Running with Unrestricted Access

Omit the impersonate parameter to run with full admin access. Only do this for true administrative tasks.

import { upsertSong } from "@dataconnect/admin-generated";

await upsertSong(adminDc, {
  title: "New Song",
  genre: "Rock"
});

Android SDK

Consult this file when writing Android application code (Kotlin) that interacts with the SQL Connect backend.

Best Practices for Agents

• Understand Operation Storage: SQL Connect queries and mutations are stored on the server like Cloud Functions. Whenever you update operations, you must regenerate the SDK and redeploy services that use it to avoid breaking clients.
• Resilient Enum Handling: The generated SDK forces handling of unknown values by wrapping them in EnumValue. You must unwrap it into EnumValue.Known or EnumValue.Unknown to handle schema updates gracefully.
• Flow Behavior: While you can collect a Flow from a query, note that this Flow is not updated in real-time automatically by default. It only produces a result when a new query result is retrieved using a call to the query's execute() method.
• Leverage Coroutines: Call .execute() within a coroutine scope for asynchronous operations.

Dependencies (build.gradle.kts)

Ensure you have the Kotlin Serialization plugin and standard SQL Connect dependencies:

plugins {
    kotlin("plugin.serialization") version "1.8.22" // Must match Kotlin version
}

dependencies {
    // [AGENT] Fetch the latest available BoM version from https://firebase.google.com/support/release-notes/android before adding this
    implementation(platform("com.google.firebase:firebase-bom:34.12.0"))
    implementation("com.google.firebase:firebase-dataconnect")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
}

Initialization

Retrieve the generated connector instance:

import com.google.firebase.dataconnect.generated.MoviesConnector

val connector = MoviesConnector.instance

// For local development with emulator
// Defaults to correct host for Android emulator (10.0.2.2)
connector.dataConnect.useEmulator()
// Or specify a non-default port:
// connector.dataConnect.useEmulator(port = 9999)

Calling Operations

Basic Query

val result = connector.listMovies.execute()
result.data.movies.forEach { movie ->
    println(movie.title)
}

Mutation

val newMovie = connector.createMovie.execute(
    title = "Empire Strikes Back",
    releaseYear = 1980,
    genre = "Sci-Fi",
    rating = 5
)

Resilient Enum Handling

Unwrap the EnumValue to handle known and unknown cases safely.

val result = connector.listMovies.execute()

result.data.movies.forEach { movie ->
    when (val aspect = movie.aspectratio) {
        is EnumValue.Known -> println("Known aspect: ${aspect.value.name}")
        is EnumValue.Unknown -> println("Unknown aspect: ${aspect.stringValue}")
    }
}

Client-Side Caching

Enable caching in connector.yaml to reduce requests and support offline scenarios.

generate:
  kotlinSdk:
    outputDir: "../android"
    package: "com.google.firebase.dataconnect.generated"
    clientCache:
      maxAge: 5s
      storage: persistent # Default for Android is persistent

Use policies in code:

val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)
val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)

Data Type Mapping Reference

• GraphQL String -> Kotlin String
• GraphQL Int -> Kotlin Int (32-bit)
• GraphQL Float -> Kotlin Double (64-bit)
• GraphQL Boolean -> Kotlin Boolean
• GraphQL UUID -> Kotlin java.util.UUID
• GraphQL Date -> Kotlin com.google.firebase.dataconnect.LocalDate
• GraphQL Timestamp -> Kotlin com.google.firebase.Timestamp
• GraphQL Int64 -> Kotlin Long
• GraphQL Any -> Kotlin com.google.firebase.dataconnect.AnyValue

Flutter SDK

Consult this file when writing Flutter application code (Dart) that interacts with the SQL Connect backend.

Best Practices for Agents

• Understand Operation Storage: SQL Connect queries and mutations are stored on the server like Cloud Functions. Whenever you update operations, you must regenerate the SDK and redeploy services that use it to avoid breaking clients.
• Resilient Enum Handling: The generated SDK forces handling of unknown values for enumerations. Client code must unwrap the EnumValue object into either Known or Unknown to handle schema updates gracefully.
• Use Ref for Subscriptions: Call .ref() on operation methods to get a QueryRef for advanced usage like subscriptions.
• Builder Pattern for Optionals: Use the builder pattern for mutations with optional fields.

Installation

flutter pub add firebase_data_connect

Imports

import 'package:firebase_data_connect/firebase_data_connect.dart';
// Import generated connector
import 'generated/movies.dart'; 

Initialization

// For local development with emulator
MoviesConnector.instance.dataConnect.useDataConnectEmulator('127.0.0.1', 9399);

Calling Operations

Basic Query

final response = await MoviesConnector.instance.listMovies().execute();
print(response.data.movies);

Mutation with Optional Fields (Builder Pattern)

await MoviesConnector.instance.createMovie(
  title: 'Empire Strikes Back', 
  releaseYear: 1980, 
  genre: 'Sci-Fi' 
).rating(5).execute();

Resilient Enum Handling

When dealing with schema enumerations, use the forced unwrapping pattern to handle unknown values (e.g., when a new value is added to the backend but client is old).

final result = await MoviesConnector.instance.listMovies().execute();

if (result.data != null && result.data!.isNotEmpty) {
  handleEnumValue(result.data![0].aspectratio);
}

void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
  if (aspectValue.value != null) {
    switch(aspectValue.value!) {
      case AspectRatio.ACADEMY:
        print("Academy aspect");
        break;
      case AspectRatio.WIDESCREEN:
        print("Widescreen aspect");
        break;
      // Add other known cases...
    }
  } else {
    print("Unknown aspect ratio detected: ${aspectValue.stringValue}");
  }
}

Client-Side Caching

Enable caching in connector.yaml to reduce requests and support offline scenarios.

generate:
  dartSdk: # Or the appropriate block for your project
    outputDir: ../dart/
    package: "dataconnect_generated"
    clientCache:
      maxAge: 5s
      storage: memory # Or persistent for native

Use policies in code:

// Only serve cached values
await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);

// Unconditionally fetch fresh values
await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);

Real-time Subscriptions

final queryRef = MoviesConnector.instance.getMovieById(id: "<MOVIE_ID>").ref();
final subscription = queryRef.subscribe().listen((result) {
  final movie = result.data.movie;
  if (movie != null) {
    updateUi(movie.title);
  }
});

Data Type Mapping Reference

• GraphQL Timestamp -> Dart firebase_data_connect.Timestamp
• GraphQL Int -> Dart int
• GraphQL Date -> Dart DateTime
• GraphQL UUID -> Dart string
• GraphQL Float -> Dart double
• GraphQL Boolean -> Dart bool

iOS SDK

Consult this file when writing iOS application code (Swift) that interacts with the SQL Connect backend.

Best Practices for Agents

• Understand Operation Storage: SQL Connect queries and mutations are stored on the server like Cloud Functions. Whenever you update operations, you must regenerate the SDK and redeploy services that use it to avoid breaking clients.
• Resilient Enum Handling: The generated SDK forces handling of unknown values by adding an ._UNKNOWN case. Swift enforces exhaustive switch statements, so you must handle this case.
• Observable Macro: By default, query refs support the @Observable macro (iOS 17+), making them ideal for binding to SwiftUI views. The bindable query results are available in the data variable of the query ref.
• Handle Errors: Use try await with operation execution as they are asynchronous and may throw errors.

Dependencies (Package.swift or SPM)

Configure the generated SDK as a package dependency in Xcode.

Initialization

Retrieve the generated connector instance:

import FirebaseCore
import FirebaseDataConnect

// Assuming connector name is 'movies' in connector.yaml
// The connector name is the lower camel case connectorId defined in connector.yaml suffixed with the word 'Connector'
let connector = DataConnect.moviesConnector

// For local development with emulator
// Defaults to 127.0.0.1:9399
connector.useEmulator() 
// Or specify a non-default port:
// connector.useEmulator(port: 9999)

Calling Operations

Basic Query

let result = try await connector.listMovies.execute()
for movie in result.data.movies {
    print(movie.title)
}

Mutation

let mutationResult = try await connector.createMovieMutation.execute(
  title: "Empire Strikes Back",
  releaseYear: 1980,
  genre: "Sci-Fi",
  rating: 5
)

Resilient Enum Handling

Handle generated enums exhaustively, including the ._UNKNOWN case.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print("Unknown: \(unknownAspect)")
            }
        }
    }
} catch {
    // handle error
}

Client-Side Caching

Enable caching in connector.yaml to reduce requests, support offline scenarios, enable realtime support for queries.

generate:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    clientCache:
      maxAge: 5s
      storage: persistent # Default for iOS is persistent

Use cache policies in code:

try await execute(fetchPolicy: .cacheOnly)
try await execute(fetchPolicy: .serverOnly)

Subscriptions (Realtime)

SwiftUI Example

import Combine
import SwiftUI

struct ListMovieView: View {
    // QueryRef has the Observable attribute, so its properties will
    // automatically trigger updates on changes.
    private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")

    // Store the handle to unsubscribe from query updates.
    @State private var querySub: AnyCancellable?

    var body: some View {
        VStack {
            // Use the query results in a View.
            ForEach(queryRef.data?.movies ?? [], id: \.id) { movie in
                    Text(movie.title)
                }
        }
        .onAppear {
            // Subscribe to the query for updates using the Observable macro.
            Task {
                do {
                    querySub = try await queryRef.subscribe().sink { _ in }
                } catch {
                    print("Error subscribing to query: \(error)")
                }
            }
        }
        .onDisappear {
          querySub?.cancel()
        }
    }
}

Data Type Mapping Reference

• GraphQL UUID -> Swift UUID
• GraphQL Date -> Swift FirebaseDataConnect.LocalDate
• GraphQL Timestamp -> Swift FirebaseCore.Timestamp
• GraphQL Int -> Swift Int
• GraphQL Float -> Swift Double
• GraphQL Boolean -> Swift Bool

Web SDK

Consult this file when writing client-side web code (TypeScript/JavaScript) that interacts with the SQL Connect backend.

Best Practices for Agents

• Understand Operation Storage: SQL Connect queries and mutations are stored on the server like Cloud Functions. Whenever you update operations, you must regenerate the SDK and redeploy services that use it to avoid breaking clients.
• Resilient Enum Handling: JavaScript/TypeScript does not enforce exhaustive checks on enums. Always add a default branch to switch statements or an else branch to handle unknown values gracefully when schemas evolve.
• TanStack Query vs. Native: You can generate hooks for React/Angular using TanStack Query. Choose either TanStack or SQL Connect's built-in real-time and caching support, but do not use both in the same project. SQL Connect offers normalized caching and remote invalidation.
• Emulator Connection: connectDataConnectEmulator is only required if connecting to the emulator. Otherwise, the generated SDK auto-creates the instance.

Installation

npm install firebase
firebase init dataconnect:sdk

Initialization

import { connectDataConnectEmulator, getDataConnect } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// Configure the SDK to use local emulator
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

Calling Operations

Using executeQuery (Preferred for clarity)

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

Using Action Shortcuts

import { listMovies } from '@dataconnect/generated';

listMovies().then(data => showInUI(data));

Resilient Enum Handling

Use a default case or check against Object.values.

import { getOldestMovie } from '@dataconnect/generated';

const queryResult = await getOldestMovie();

if (queryResult.data) {
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
        console.log('Filmed in Academy or Widescreen!');
        break;
      default:
        // The default case will catch FULLSCREEN, etc.
        console.log('Not filmed in Academy or Widescreen.');
        break;
  }
}

Client-Side Caching

Enable caching in connector.yaml:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory # Only memory is supported on Web

Use policies in code:

await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);

Subscriptions (Realtime)

Use subscribe() to receive live updates.

Web (Vanilla JS)

import { subscribe } from 'firebase/data-connect';
import { getMovieByIdRef } from '@dataconnect/generated';

const queryRef = getMovieByIdRef({ id: "<MOVIE_ID>" });

const unsubscribe = subscribe(queryRef, (result) => {
  console.log("Updated result:", result);
});

TanStack Query Support (React)

To use React hooks, re-run firebase init dataconnect:sdk after adding React.

Usage

import { useListAllMovies } from "@dataconnect/generated/react";

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  // handle loading, error, and data
}

Data Type Mapping Reference

• GraphQL Timestamp -> TypeScript string
• GraphQL Date -> TypeScript string
• GraphQL UUID -> TypeScript string
• GraphQL Int64 -> TypeScript string
• GraphQL Double -> TypeScript number
• GraphQL Float -> TypeScript number

Search Solutions Reference (Vector & Full-Text Search)

Use this reference to design, configure, and implement search capabilities in SQL Connect. SQL Connect supports three types of search: 1. Vector Similarity Search (Semantic): Best for finding conceptually/semantically similar rows (e.g., recommendations, "more like this"). Requires Vertex AI. 2. Full-Text Search (Lexical): Best for keyword and phrase search across single or multiple columns. Supports lexical stemming. 3. String Pattern Filters (Exact/Regex): Best for simple prefix, exact match, or basic wildcard queries (uses standard Postgres indexing).

---

Search Selection Guide

Use this comparative guide to choose the optimal search strategy for the user's task:

---

1. Vector Similarity Search (Semantic)

Perform semantic matching by generating vector embeddings representing the semantic meaning of text.

Schema Setup

• Configure Column Dimensions: Define the column dimension size using the @col(size: X) directive — SQL Connect requires an explicit size for Vector fields to allocate storage.
• Match Model Specifications: Ensure the column size matches the output dimension of your chosen embedding model (e.g., 768 for Google Vertex AI's textembedding-gecko models) to prevent runtime type mismatches.

type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  description: String
  # Vector field for description embeddings (Vertex AI gecko size is 768)
  descriptionEmbedding: Vector! @col(size: 768)
}

Automatic Embedding Generation (_embed server value)

Ensure you use the exact same embedding model across all queries and mutations on a given vector field — vector embeddings generated from different model versions are incompatible and will result in poor search relevance or errors.

A. Generation on Insert

Use the ${vectorFieldName}_embed input parameter to automatically generate and store embeddings on creation.

# connector/mutations.gql
mutation CreateMovieWithEmbedding($title: String!, $description: String!) @auth(level: USER) {
  movie_insert(data: {
    title: $title,
    description: $description,
    descriptionEmbedding_embed: {
      model: "textembedding-gecko@003",
      text: $description
    }
  })
}

B. Generation on Update

# connector/mutations.gql
mutation UpdateMovieDescription($id: UUID!, $description: String!) @auth(level: USER) {
  movie_update(
    id: $id,
    data: {
      description: $description,
      descriptionEmbedding_embed: {
        model: "textembedding-gecko@003",
        text: $description
      }
    }
  )
}

Similarity Search Queries

SQL Connect automatically generates a similarity query function for every Vector field in the format: ${pluralType}_${vectorFieldName}_similarity

A. Auto-Embedding Search

Use compare_embed to automatically convert the search query string into an embedding on the fly using Vertex AI.

# connector/queries.gql
query SearchMoviesByDescription($query: String!) @auth(level: PUBLIC) {
  movies_descriptionEmbedding_similarity(
    compare_embed: { model: "textembedding-gecko@003", text: $query },
    limit: 5
  ) {
    id
    title
    description
  }
}

B. Custom Vector Search

Use compare to pass raw pre-computed float arrays (cast as a Vector!) directly to the search without calling Vertex AI.

# connector/queries.gql
query SearchMoviesByCustomVector($vector: Vector!, $limit: Int!) @auth(level: PUBLIC) {
  movies_descriptionEmbedding_similarity(
    compare: $vector,
    method: L2,
    limit: $limit
  ) {
    id
    title
  }
}

Tuning Vector Proximity

• Distance Thresholding: Select the _metadata { distance } field to evaluate how close the results are, then define a tight threshold using the within parameter.
• Distance Metric Gotcha: L2 and COSINE return different distance scales. Re-tune your within threshold if you change the method parameter, as their distance ranges are not compatible.

# connector/queries.gql
query SearchMoviesCosineSimilarity($query: String!) @auth(level: PUBLIC) {
  movies_descriptionEmbedding_similarity(
    compare_embed: { model: "textembedding-gecko@003", text: $query },
    method: COSINE,
    within: 0.5, # Maximum distance threshold
    limit: 5
  ) {
    id
    title
    _metadata { distance }
  }
}

---

2. Full-Text Search (Lexical)

Perform fast, stemmed keyword/phrase searches over single or multiple text columns in your table.

Schema Setup

To index columns for full-text search, declare the @searchable directive on the string fields inside your table schema.

type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String! @searchable # Default language (English)
  genre: String @searchable
  description: String @searchable(language: "french") # Custom language
  rating: Float
}

• Stemming Language: By default, parsing uses English stemming. Configure custom stemming using @searchable(language: "languagename").
• Multi-Column Stemming Gotcha: Ensure all indexed columns use the exact same language when searching over multiple columns in a single query — PostgreSQL requires matching text search configurations for multi-column queries.

---

Full-Text Search Queries

SQL Connect automatically generates a full-text query function for each @table containing @searchable fields in the format: ${pluralType}_search

# connector/queries.gql
query SearchMoviesLexical($query: String!) @auth(level: PUBLIC) {
  movies_search(query: $query, limit: 10) {
    id
    title
    genre
    description
  }
}

---

Tuning Full-Text Queries

Configuring query arguments optimizes match relevance and search styles.

1. Query Formats (queryFormat argument)

Configure the search interpretation using the queryFormat parameter:

• `QUERY` (Default): Web-style search (e.g., inception OR matrix, -"space-travel", quotes for exact matches).
• `PLAIN`: Matches all words in the query string in any lexical order (e.g., "brown dog" matches "the dog was brown").
• `PHRASE`: Matches the exact, contiguous phrase sequence (e.g., "brown dog" matches "the brown dog", but NOT "dog is brown").
• `ADVANCED`: Allows standard, complex PostgreSQL tsquery operators (e.g. inception & (matrix | sci-fi)).

# connector/queries.gql
query SearchMoviesExactPhrase($query: String!) @auth(level: PUBLIC) {
  movies_search(query: $query, queryFormat: PHRASE) {
    id
    title
  }
}

2. Relevance Thresholding (relevanceThreshold and _metadata.relevance)

Results default to sorting by descending relevance rank. Select _metadata { relevance } to inspect match rankings, then set a minimum relevanceThreshold value to prune loose or irrelevant matches.

# connector/queries.gql
query SearchMoviesHighRelevance($query: String!, $threshold: Float!) @auth(level: PUBLIC) {
  movies_search(
    query: $query,
    relevanceThreshold: $threshold, # E.g., 0.05
    limit: 5
  ) {
    id
    title
    _metadata {
      relevance
    }
  }
}

Security Reference

Contents

• @auth Directive
• Access Levels
• CEL Expressions
• @check and @redact
• Authorization Patterns
• Anti-Patterns

---

@auth Directive

Every deployable query/mutation must have @auth. Without it, operations default to NO_ACCESS.

query PublicData @auth(level: PUBLIC) { ... }
query UserData @auth(level: USER) { ... }
query AdminOnly @auth(expr: "auth.token.admin == true") { ... }

---

Access Levels

Important: Levels like USER are starting points. Always add filters or expressions to verify the user can access specific data.

---

CEL Expressions

Available Bindings

auth.token Fields

Expression Examples

# Check custom claim
@auth(expr: "auth.token.role == 'admin'")

# Check verified email domain
@auth(expr: "auth.token.email_verified && auth.token.email.endsWith('@company.com')")

# Check multiple conditions
@auth(expr: "auth.uid != nil && (auth.token.role == 'editor' || auth.token.role == 'admin')")

# Check variable
@auth(expr: "has(vars.status) && vars.status in ['draft', 'published']")

Using eq_expr in Filters

Compare database fields with auth values:

query MyPosts @auth(level: USER) {
  posts(where: { authorUid: { eq_expr: "auth.uid" }}) {
    id title
  }
}

mutation UpdateMyPost($id: UUID!, $title: String!) @auth(level: USER) {
  post_update(
    first: { where: {
      id: { eq: $id },
      authorUid: { eq_expr: "auth.uid" }
    }},
    data: { title: $title }
  )
}

---

@check and @redact

Use @check to validate data and @redact to hide results from client:

@check

Validates a field value; aborts if check fails.

@check(expr: "this != null", message: "Not found")
@check(expr: "this == 'editor'", message: "Must be editor")
@check(expr: "this.exists(p, p.role == 'admin')", message: "No admin found")

@redact

Hides field from response (still evaluated for @check):

query @redact { ... }  # Query result hidden but @check still runs

Authorization Data Lookup

Check database permissions before allowing mutation:

mutation UpdateMovie($id: UUID!, $title: String!) 
  @auth(level: USER) 
  @transaction {
  # Step 1: Check user has permission
  query @redact {
    moviePermission(
      key: { movieId: $id, userId_expr: "auth.uid" }
    ) @check(expr: "this != null", message: "No access to movie") {
      role @check(expr: "this == 'editor'", message: "Must be editor")
    }
  }
  # Step 2: Update if authorized
  movie_update(id: $id, data: { title: $title })
}

Validate Key Exists

mutation MustDeleteMovie($id: UUID!) @auth(level: USER) @transaction {
  movie_delete(id: $id) 
    @check(expr: "this != null", message: "Movie not found")
}

---

Authorization Patterns

User-Owned Resources

# Create with owner
mutation CreatePost($content: String!) @auth(level: USER) {
  post_insert(data: {
    authorUid_expr: "auth.uid",
    content: $content
  })
}

# Read own data only
query MyPosts @auth(level: USER) {
  posts(where: { authorUid: { eq_expr: "auth.uid" }}) {
    id content
  }
}

# Update own data only
mutation UpdatePost($id: UUID!, $content: String!) @auth(level: USER) {
  post_update(
    first: { where: { id: { eq: $id }, authorUid: { eq_expr: "auth.uid" }}},
    data: { content: $content }
  )
}

# Delete own data only
mutation DeletePost($id: UUID!) @auth(level: USER) {
  post_delete(
    first: { where: { id: { eq: $id }, authorUid: { eq_expr: "auth.uid" }}}
  )
}

Role-Based Access

# Admin-only query
query AllUsers @auth(expr: "auth.token.admin == true") {
  users { id email name }
}

# Role from database
mutation AdminAction($id: UUID!) @auth(level: USER) @transaction {
  query @redact {
    user(key: { uid_expr: "auth.uid" }) {
      role @check(expr: "this == 'admin'", message: "Admin required")
    }
  }
  # ... admin action
}

Public Data with Filters

query PublicPosts @auth(level: PUBLIC) {
  posts(where: {
    visibility: { eq: "public" },
    publishedAt: { lt_expr: "request.time" }
  }) {
    id title content
  }
}

Tiered Access (Pro Content)

query ProContent @auth(expr: "auth.token.plan == 'pro'") {
  posts(where: { visibility: { in: ["public", "pro"] }}) {
    id title content
  }
}

---

Anti-Patterns

❌ Don't Pass User ID as Variable

# BAD - any user can pass any userId
query GetUserPosts($userId: String!) @auth(level: USER) {
  posts(where: { authorUid: { eq: $userId }}) { ... }
}

# GOOD - use auth.uid
query GetMyPosts @auth(level: USER) {
  posts(where: { authorUid: { eq_expr: "auth.uid" }}) { ... }
}

❌ Don't Use USER Without Filters

# BAD - any authenticated user sees all documents
query AllDocs @auth(level: USER) {
  documents { id title content }
}

# GOOD - filter to user's documents
query MyDocs @auth(level: USER) {
  documents(where: { ownerId: { eq_expr: "auth.uid" }}) { ... }
}

❌ Don't Trust Unverified Email

# BAD - email not verified
@auth(expr: "auth.token.email.endsWith('@company.com')")

# GOOD - verify email first
@auth(expr: "auth.token.email_verified && auth.token.email.endsWith('@company.com')")

❌ Don't Use PUBLIC/USER for Prototyping

During development, set operations to NO_ACCESS until you implement proper authorization. Use emulator and VS Code extension for testing.

Templates

Ready-to-use templates for common Firebase SQL Connect patterns.

---

Basic CRUD Schema

# schema.gql
type Item @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String!
  description: String
  createdAt: Timestamp! @default(expr: "request.time")
  updatedAt: Timestamp! @default(expr: "request.time")
}

# queries.gql
query ListItems @auth(level: PUBLIC) {
  items(orderBy: [{ createdAt: DESC }]) {
    id name description createdAt
  }
}

query GetItem($id: UUID!) @auth(level: PUBLIC) {
  item(id: $id) { id name description createdAt updatedAt }
}

# mutations.gql
mutation CreateItem($name: String!, $description: String) @auth(level: USER) {
  item_insert(data: { name: $name, description: $description })
}

mutation UpdateItem($id: UUID!, $name: String, $description: String) @auth(level: USER) {
  item_update(id: $id, data: {
    name: $name,
    description: $description,
    updatedAt_expr: "request.time"
  })
}

mutation DeleteItem($id: UUID!) @auth(level: USER) {
  item_delete(id: $id)
}

---

User-Owned Resources

# schema.gql
type User @table(key: "uid") {
  uid: String! @default(expr: "auth.uid")
  email: String! @unique
  displayName: String
}

type Note @table {
  id: UUID! @default(expr: "uuidV4()")
  owner: User!
  title: String!
  content: String
  createdAt: Timestamp! @default(expr: "request.time")
}

# queries.gql
query MyNotes @auth(level: USER) {
  notes(
    where: { owner: { uid: { eq_expr: "auth.uid" }}},
    orderBy: [{ createdAt: DESC }]
  ) { id title content createdAt }
}

query GetMyNote($id: UUID!) @auth(level: USER) {
  note(
    first: { where: {
      id: { eq: $id },
      owner: { uid: { eq_expr: "auth.uid" }}
    }}
  ) { id title content }
}

# mutations.gql
mutation CreateNote($title: String!, $content: String) @auth(level: USER) {
  note_insert(data: {
    owner: { uid_expr: "auth.uid" },
    title: $title,
    content: $content
  })
}

mutation UpdateNote($id: UUID!, $title: String, $content: String) @auth(level: USER) {
  note_update(
    first: { where: { id: { eq: $id }, owner: { uid: { eq_expr: "auth.uid" }}}},
    data: { title: $title, content: $content }
  )
}

mutation DeleteNote($id: UUID!) @auth(level: USER) {
  note_delete(
    first: { where: { id: { eq: $id }, owner: { uid: { eq_expr: "auth.uid" }}}}
  )
}

---

Many-to-Many Relationship

# schema.gql
type Tag @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String! @unique
}

type Article @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  content: String!
}

type ArticleTag @table(key: ["article", "tag"]) {
  article: Article!
  tag: Tag!
}

# queries.gql
query ArticlesByTag($tagName: String!) @auth(level: PUBLIC) {
  articles(where: {
    articleTags_on_article: { tag: { name: { eq: $tagName }}}
  }) {
    id title
    tags: tags_via_ArticleTag { name }
  }
}

query ArticleWithTags($id: UUID!) @auth(level: PUBLIC) {
  article(id: $id) {
    id title content
    tags: tags_via_ArticleTag { id name }
  }
}

# mutations.gql
mutation AddTagToArticle($articleId: UUID!, $tagId: UUID!) @auth(level: USER) {
  articleTag_insert(data: {
    article: { id: $articleId },
    tag: { id: $tagId }
  })
}

mutation RemoveTagFromArticle($articleId: UUID!, $tagId: UUID!) @auth(level: USER) {
  articleTag_delete(key: { articleId: $articleId, tagId: $tagId })
}

---

dataconnect.yaml Template

specVersion: "v1"
serviceId: "my-service"
location: "us-central1"
schema:
  source: "./schema"
  datasource:
    postgresql:
      database: "fdcdb"
      cloudSql:
        instanceId: "my-instance"
connectorDirs: ["./connector"]

---

connector.yaml Template

connectorId: "default"
generate:
  javascriptSdk:
    outputDir: "../web/src/lib/dataconnect"
    package: "@myapp/dataconnect"
  kotlinSdk:
    outputDir: "../android/app/src/main/kotlin/com/myapp/dataconnect"
    package: "com.myapp.dataconnect"
  swiftSdk:
    outputDir: "../ios/MyApp/DataConnect"
  dartSdk:
    outputDir: "../flutter/lib/dataconnect"
    package: myapp_dataconnect

---

Firebase Init Commands

# Initialize SQL Connect in project
npx -y firebase-tools@latest init dataconnect

# Initialize with specific project
npx -y firebase-tools@latest use <project-id>
npx -y firebase-tools@latest init dataconnect

# Start emulator for development
npx -y firebase-tools@latest emulators:start --only dataconnect

# Generate SDKs
npx -y firebase-tools@latest dataconnect:sdk:generate

# Deploy to production
npx -y firebase-tools@latest deploy --only dataconnect

---

SDK Initialization (Web)

// lib/firebase.ts
import { initializeApp } from 'firebase/app';
import { getAuth } from 'firebase/auth';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myapp/dataconnect';

const firebaseConfig = {
  apiKey: "...",
  authDomain: "...",
  projectId: "...",
};

export const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);
export const dataConnect = getDataConnect(app, connectorConfig);

// Connect to emulator in development
if (import.meta.env.DEV) {
  connectDataConnectEmulator(dataConnect, 'localhost', 9399);
}

// Example usage
import { listItems, createItem } from '@myapp/dataconnect';

// List items
const { data } = await listItems();
console.log(data.items);

// Create item (requires auth)
await createItem({ name: 'New Item', description: 'Description' });

---

Realtime Query Templates

Time-Based Polling

query LiveDashboard
  @auth(level: PUBLIC)
  @refresh(every: { seconds: 30 }) {
  items(orderBy: [{ updatedAt: DESC }], limit: 20) {
    id name updatedAt
  }
}

Event-Driven Refresh

query ItemList($categoryId: UUID!)
  @auth(level: PUBLIC)
  @refresh(onMutationExecuted: {
    operation: "CreateItem",
    condition: "request.variables.categoryId == mutation.variables.categoryId"
  }) {
  items(where: { category: { id: { eq: $categoryId }}}) {
    id name createdAt
  }
}

Client Subscribe (Web)

import { liveDashboardRef } from '@myapp/dataconnect';
import { subscribe } from 'firebase/data-connect';

const unsubscribe = subscribe(liveDashboardRef(), {
  onNext: (result) => {
    // Called immediately with current data, then on each refresh
    renderDashboard(result.data.items);
  },
  onError: (error) => console.error('Subscription error:', error)
});

// Cleanup when done
// unsubscribe();