vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-data-connect/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: firebase-data-connect
+description: Builds and deploys Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL securely. Use when designing schemas with tables and relations, writing authorized queries and mutations, configuring real-time data updates, or generating type-safe SDKs. Use when you need a relational database with Firebase, or when the user mentions SQL Connect or 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
+
+```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"
+```
+
+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#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)**.