# Firebase Data Connect

> Construye y despliega backends de Firebase SQL Connect (antes Data Connect) con PostgreSQL de forma segura, incluyendo esquemas, queries/mutations autorizadas, tiempo real y SDKs type-safe.

Fuente: https://skillsagentes.com/skills/firebase/agent-skills/firebase-data-connect
Markdown: https://skillsagentes.com/skills/firebase/agent-skills/firebase-data-connect.md

Repositorio: https://github.com/firebase/agent-skills
Autor: firebase
Licencia: Apache-2.0
Actualizado: el mes pasado
Coste de contexto: 94 tok instalada, 2.4k tok al activarse, 30.5k tok con todos los archivos del bundle
Bundle: 17 archivos, 119 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add firebase/agent-skills --skill firebase-data-connect-basics --agent claude-code
# Cursor
npx -y skills add firebase/agent-skills --skill firebase-data-connect-basics --agent cursor
# Codex
npx -y skills add firebase/agent-skills --skill firebase-data-connect-basics --agent codex
# Gemini CLI
npx -y skills add firebase/agent-skills --skill firebase-data-connect-basics --agent gemini
# Windsurf
npx -y skills add firebase/agent-skills --skill firebase-data-connect-basics --agent windsurf
# Cline
npx -y skills add firebase/agent-skills --skill firebase-data-connect-basics --agent cline
```

## Qué hace

- Define esquemas GraphQL con tablas y relaciones para PostgreSQL vía @table/@col
- Escribe queries y mutations autorizadas con @auth, @check y @redact
- Configura actualizaciones en tiempo real con @refresh y suscripciones
- Genera SDKs type-safe para web, Android, iOS, Flutter y Admin Node.js
- Valida y despliega el backend con firebase-tools (compile, sdk:generate, deploy)

## Cuándo usarla

- Diseñar esquemas con tablas y relaciones
- Escribir queries y mutations autorizadas
- Configurar actualizaciones de datos en tiempo real
- Generar SDKs type-safe o cuando el usuario menciona SQL Connect o Data Connect

## Qué la activa

- "Crea un esquema de películas con tablas y relaciones en SQL Connect"
- "Añade una mutation de upsert para el perfil de usuario"
- "Configura suscripciones en tiempo real con @refresh"
- "Genera el SDK de TypeScript para mi conector de Data Connect"

## Antes de instalar

- Requiere firebase-tools (via npx) y un proyecto Firebase con Cloud SQL para PostgreSQL.
- Necesita en el PATH: npx

## Archivos

- SKILL.md — 9 KB
- examples.md — 15 KB
- reference/cloud_functions.md — 6 KB
- reference/config.md — 7 KB
- reference/data_seeding.md — 6 KB
- reference/native_sql.md — 7 KB
- reference/operations.md — 11 KB
- reference/realtime.md — 8 KB
- reference/schema.md — 7 KB
- reference/sdk_admin_node.md — 4 KB
- reference/sdk_android.md — 4 KB
- reference/sdk_flutter.md — 3 KB
- reference/sdk_ios.md — 4 KB
- reference/sdk_web.md — 4 KB
- reference/search.md — 9 KB
- reference/security.md — 9 KB
- templates.md — 7 KB

## SKILL.md

Reproducido tal cual desde firebase/agent-skills bajo Apache-2.0. Esta sección es el documento original y está en inglés.

# 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

```text
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/`).
1. **Validate Operations**: Run
   `npx -y firebase-tools@latest dataconnect:compile` against the schema.

## Operation Strategies: GraphQL vs. Native SQL

Always default to **Native GraphQL**. **Native SQL lacks type safety** and
bypasses schema-enforced structures. Only use **Native SQL** when the user
explicitly requests it or when the task requires advanced database features.

| Strategy                     | When to use                                                                                                            | Implementation                                                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Native GraphQL** (Default) | Almost all use cases. Standard CRUD, basic filtering/sorting, simple relational joins. Requires full type safety.      | Auto-generated fields (`movie_insert`, `movies`). Strong typing and schema enforcement.                               |
| **Native SQL** (Advanced)    | PostgreSQL extensions (e.g., PostGIS), window functions (`RANK()`), complex aggregations, or highly tuned sub-queries. | Raw SQL string literals via `_select`, `_execute`, etc. Requires strict positional parameters (`$1`). No type safety. |

## Development Workflow

Follow this strict workflow to build your application. You **must** read the
linked reference files for each step to understand the syntax and available
features.

### 1. Define Data Model (`schema/schema.gql`)

Define your GraphQL types, tables, and relationships (which map to a Postgres
schema).

> **Read [reference/schema.md](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`:

```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"
    package: "DataConnectGenerated"
```

Generate SDKs:

```bash
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](reference/sdk_web.md)
- **Android (Kotlin)**: [reference/sdk_android.md](reference/sdk_android.md)
- **iOS (Swift)**: [reference/sdk_ios.md](reference/sdk_ios.md)
- **Admin (Node.js)**:
  [reference/sdk_admin_node.md](reference/sdk_admin_node.md)
- **Flutter (Dart)**: [reference/sdk_flutter.md](reference/sdk_flutter.md)

______________________________________________________________________

## Feature Capability Map

If you need to implement a specific feature, consult the mapped reference file:

| Feature                         | Reference File                                               | Key Concepts                                       |
| :------------------------------ | :----------------------------------------------------------- | :------------------------------------------------- |
| **Data Modeling**               | [reference/schema.md](reference/schema.md)                   | `@table`, `@unique`, `@index`, Relations           |
| **Vector Search**               | [reference/search.md](reference/search.md)                   | `Vector`, `@col(dataType: "vector")`, embeddings   |
| **Full-Text Search**            | [reference/search.md](reference/search.md)                   | `@searchable`, `movies_search`                     |
| **Upserting Data**              | [reference/operations.md](reference/operations.md)           | `_upsert` mutations                                |
| **Complex Filters**             | [reference/operations.md](reference/operations.md)           | `_or`, `_and`, `_not`, `eq`, `contains`            |
| **Transactions**                | [reference/operations.md](reference/operations.md)           | `@transaction`, `response` binding                 |
| **Environment Config**          | [reference/config.md](reference/config.md)                   | `dataconnect.yaml`, `connector.yaml`               |
| **Realtime Subscriptions**      | [reference/realtime.md](reference/realtime.md)               | `@refresh`, `subscribe()`, auto-refresh            |
| **Cloud Functions Integration** | [reference/cloud_functions.md](reference/cloud_functions.md) | `onMutationExecuted`, triggering events            |
| **Data Seeding & Migrations**   | [reference/data_seeding.md](reference/data_seeding.md)       | `seed_data.gql`, `_insertMany`, Admin SDK bulk     |
| **Starter Templates**           | [templates.md](templates.md)                                 | CRUD, user-owned resources, many-to-many, SDK init |

______________________________________________________________________

## 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.
1. Run `npx -y firebase-tools@latest init dataconnect`.
1. 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`.
1. Write schema and operations.
1. Seed local test data into `seed_data.gql`. Read
   [reference/data_seeding.md](reference/data_seeding.md#1-local-prototyping-data-seeding).
1. Run `npx -y firebase-tools@latest dataconnect:compile` or
   `npx -y firebase-tools@latest dataconnect:sdk:generate` to validate them.
1. 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)**.

## Dónde encaja

- Categoría: [Bases de datos](https://skillsagentes.com/categorias/bases-de-datos.md) — Diseño de esquemas, migraciones y optimización de consultas.
- Creador: [firebase](https://skillsagentes.com/creators/firebase.md) — 12 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Firebase Ai Logic Basics](https://skillsagentes.com/skills/firebase/agent-skills/firebase-ai-logic-basics.md): Skill oficial para integrar Firebase AI Logic (Gemini API) en apps. Cubre configuración, inferencia multimodal, salida estructurada y seguridad.
- [Firebase Firestore](https://skillsagentes.com/skills/firebase/agent-skills/firebase-firestore.md): Configura, gestiona, consulta y ajusta bases de datos Cloud Firestore (edición Standard/Enterprise): modelado de datos, reglas de seguridad, índices e integraciones SDK (Web, Python, iOS, Android, Flutter).
- [Firebase App Hosting Basics](https://skillsagentes.com/skills/firebase/agent-skills/firebase-app-hosting-basics.md): Despliega y gestiona apps full-stack (Next.js, Angular) con SSR usando Firebase App Hosting: apphosting.yaml, bloques apphosting en firebase.json, secretos y CI/CD con GitHub.
- [Firebase Hosting Basics](https://skillsagentes.com/skills/firebase/agent-skills/firebase-hosting-basics.md): Despliega y configura el Firebase Hosting clásico para sitios estáticos, SPAs y microservicios: dominios, firebase.json, redirects, rewrites y canales de vista previa.
- [Firebase Security Rules Auditor](https://skillsagentes.com/skills/firebase/agent-skills/firebase-security-rules-auditor.md): Audita reglas de seguridad de Firebase (Firestore, Cloud Storage): vulnerabilidades, escalada de privilegios, bypasses de roles, inconsistencias create/update y falta de comprobaciones hasOnly() de ownership.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)