/firebase-data-connect

name: firebase-data-connect
description: "Use when setting up Data Connect, writing GraphQL queries/mutations, configuring generated SDKs, handling offline, or applying security rules."
license: MIT

Firebase Data Connect Skill

This skill defines how to correctly use Firebase Data Connect in Flutter applications.

When to Use

Use this skill when:

• Setting up and configuring Firebase Data Connect in a Flutter project.
• Designing schemas, queries, and mutations for Data Connect.
• Implementing generated SDK calls for typed queries and mutations.
• Handling network failures, data inconsistencies, and offline scenarios.
• Applying security and performance best practices.

---

1. Setup and Configuration

Step 1: Install the package

flutter pub add firebase_data_connect

Step 2: Import and initialize

import 'package:firebase_data_connect/firebase_data_connect.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

Step 3: Define a schema in `dataconnect/schema/schema.gql`

type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int
  genre: String
  rating: Float
  description: String
}

Step 4: Define queries and mutations in `dataconnect/connector/queries.gql`

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    releaseYear
    genre
    rating
  }
}

mutation CreateMovie($title: String!, $releaseYear: Int, $genre: String) @auth(level: USER) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
  })
}

mutation DeleteMovie($id: UUID!) @auth(level: USER) {
  movie_delete(id: $id)
}

Step 5: Generate the typed Flutter SDK

flutterfire generate

This produces typed Dart classes for each query and mutation.

**Platform support:**

| Platform | Support | |---|---| | iOS | Full | | Android | Full | | Web | Full | | Other platforms | Not supported |

---

2. Executing Queries and Mutations

Use the generated SDK to execute typed queries and mutations:

// Execute a query
final result = await ListMoviesQuery().execute();
final movies = result.data.movies;

// Execute a mutation
await CreateMovieMutation(title: 'Inception', releaseYear: 2010, genre: 'Sci-Fi')
    .execute();

// Delete by ID
await DeleteMovieMutation(id: movieId).execute();

Real-Time Listeners

Subscribe to query changes for live updates:

final subscription = ListMoviesQuery().subscribe();
subscription.listen((result) {
  final movies = result.data.movies;
  // Update UI with latest movie list
});

---

3. Performance and Caching

• Design efficient queries requesting only the fields needed to minimize data transfer.
• Implement **pagination** for large datasets:

  query ListMoviesPaginated($limit: Int!, $offset: Int!) @auth(level: PUBLIC) {
    movies(limit: $limit, offset: $offset) {
      id
      title
      releaseYear
    }
  }

• Use real-time listeners judiciously to avoid unnecessary network usage.
• Consider **offline capabilities** for critical app functionality by caching query results locally.

---

4. Error Handling

Wrap Data Connect calls in try/catch to handle network and validation errors:

try {
  final result = await ListMoviesQuery().execute();
  return result.data.movies;
} on FirebaseException catch (e) {
  if (e.code == 'unavailable') {
    // Handle offline — return cached data
    return _localCache.getMovies();
  }
  rethrow;
}

• Implement **retry logic** with exponential backoff for transient connection errors.
• Provide meaningful error messages for data validation failures.
• Monitor error rates and investigate recurring issues.

---

5. Security

• Use `@auth` directives in schema to control access levels (`PUBLIC`, `USER`, `NO_ACCESS`).
• Integrate **Firebase Authentication** for user-based access control.
• Validate data on both client and server sides.
• Follow data privacy best practices when handling user information.

---

References

• [Firebase Data Connect documentation](https://firebase.google.com/docs/data-connect)
• [Data Connect Flutter SDK reference](https://firebase.google.com/docs/data-connect/flutter-sdk)