Index of every page on this site: llms.txt
All skills
firebase avatar

/firebase-data-connect-basics

@99954a3 official
by firebasefirebase/agent-skills520 stars
116
Run it yourself

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.

  • 17 files
  • 123 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/firebase/agent-skills/firebase-data-connect-basics

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈101 tokens for metadata: the name and description. ≈2.3k when used: this file. ≈29k more on demand in 16 files.

Description uses 5.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈398 characters, or 5.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

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 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 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 for authorization:

  • @auth(level: ...) for PUBLIC, USER, or NO_ACCESS.
  • @check and @redact for row-level security and validation.

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

Generate SDKs:

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

For platform-specific instructions on how to use the generated SDKs, read:


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

Deployment & CLI

Read 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.

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 99954a3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 months ago
metadata
{
  "author": "Google LLC",
  "category": "Databases"
}

README badge

README badge for firebase/agent-skills/firebase-data-connect-basics