firebase-data-connect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Firebase SQL Connect是一项基于Cloud SQL for PostgreSQL的关系型数据库服务，支持GraphQL Schema、自动生成的查询/变更操作以及类型安全的SDK。

[!NOTE] 产品更名: Firebase Data Connect已更名为Firebase SQL Connect。本技能仓库中所有提及“Data Connect”或“Firebase Data Connect”的说明、参考资料和示例，同样适用于“SQL Connect”和“Firebase SQL Connect”。

Project Structure

项目结构

text

dataconnect/
├── dataconnect.yaml      # Service configuration
├── schema/
│   └── schema.gql        # Data model (types with @table)
└── connector/
    ├── connector.yaml    # Connector config + SDK generation
    ├── queries.gql       # Queries
    └── mutations.gql     # Mutations

text

dataconnect/
├── dataconnect.yaml      # Service configuration
├── 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:

Review GraphQL Schema: Both user-defined and generated extensions (in
```
.dataconnect/schema/main/
```
).

Validate Operations: Run

npx -y firebase-tools@latest dataconnect:compile

against the schema.

依靠以下两种机制确保项目正确性：

审查GraphQL Schema：包括用户自定义的Schema和自动生成的扩展文件（位于
```
.dataconnect/schema/main/
```
目录下）。

验证操作：针对Schema运行命令

npx -y firebase-tools@latest dataconnect:compile

。

Operation Strategies: GraphQL vs. Native SQL

操作策略：GraphQL vs 原生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.

默认始终使用原生GraphQL。原生SQL缺乏类型安全性，且会绕过Schema强制的结构约束。仅当用户明确要求，或任务需要高级数据库特性时，才使用原生SQL。

策略	使用场景	实现方式
原生GraphQL（默认）	几乎所有使用场景。标准CRUD操作、基础过滤/排序、简单关联查询。需要完整类型安全性。	自动生成字段（如 `movie_insert` 、 `movies` ）。强类型与Schema约束。
原生SQL（高级）	PostgreSQL扩展（如PostGIS）、窗口函数（ `RANK()` ）、复杂聚合或高度优化的子查询。	通过 `_select` 、 `_execute` 等使用原始SQL字符串字面量。要求严格使用位置参数（ `$1` ）。无类型安全性。

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

)

1. 定义数据模型（

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

定义您的GraphQL类型、表和关系（映射到Postgres Schema）。

**阅读reference/schema.md**了解：
@table
、
@col
、
@default
指令
关系（
@ref
、一对多、多对多）
数据类型（UUID、Vector、JSON等）

2. Define Authorized Operations (

connector/queries.gql

connector/mutations.gql

)

2. 定义授权操作（

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)

编写客户端将使用的查询和变更操作，包括授权逻辑。SQL Connect默认是安全的。

**阅读reference/operations.md**了解：
查询：过滤（
where
）、排序（
orderBy
）、分页（
limit
/
offset
）。
变更：创建（
_insert
）、更新（
_update
）、删除（
_delete
）。
Upsert操作：使用
_upsert
实现“插入或更新”记录（对用户资料至关重要）。
事务：使用
@transaction
实现多步骤原子操作。使用
_expr: "response.<prevStep>"
在步骤间传递数据。
**阅读reference/security.md**了解授权机制：
@auth(level: ...)
用于设置PUBLIC、USER或NO_ACCESS权限。
@check
和
@redact
用于行级安全和验证。
**阅读reference/realtime.md**了解实时订阅：
@refresh
指令用于基于时间的轮询和事件驱动更新。
CEL条件用于精确限定刷新触发范围。
**阅读reference/native_sql.md**了解原生SQL操作：
通过
_select
、
_selectFirst
、
_execute
嵌入原始SQL
位置参数（
$1
、
$2
）、引号和CTE的严格规则
PostgreSQL高级特性（PostGIS、窗口函数）

3. Use type-safe SDK in your apps

3. 在应用中使用类型安全的SDK

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

为您的客户端平台生成类型安全的代码。

在

connector.yaml

中配置SDK生成：

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"

生成SDK：

bash

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

关于如何使用生成的SDK的平台特定说明，请阅读：

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:

Feature	Reference File	Key Concepts
Data Modeling	reference/schema.md	`@table` , `@unique` , `@index` , Relations
Vector Search	reference/advanced.md	`Vector` , `@col(dataType: "vector")`
Full-Text Search	reference/advanced.md	`@searchable`
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
Starter Templates	templates.md	CRUD, user-owned resources, many-to-many, SDK init

如果您需要实现特定功能，请查阅对应的参考文件：

功能	参考文件	核心概念
数据建模	reference/schema.md	`@table` 、 `@unique` 、 `@index` 、关系
向量搜索	reference/advanced.md	`Vector` 、 `@col(dataType: "vector")`
全文搜索	reference/advanced.md	`@searchable`
数据Upsert	reference/operations.md	`_upsert` 变更操作
复杂过滤	reference/operations.md	`_or` 、 `_and` 、 `_not` 、 `eq` 、 `contains`
事务	reference/operations.md	`@transaction` 、 `response` 绑定
环境配置	reference/config.md	`dataconnect.yaml` 、 `connector.yaml`
实时订阅	reference/realtime.md	`@refresh` 、 `subscribe()` 、自动刷新
启动模板	templates.md	CRUD、用户自有资源、多对多关系、SDK初始化

Deployment & CLI

部署与CLI工具

Read reference/config.md for deep dive on configuration.

Follow these patterns based on your current task:

**阅读reference/config.md**深入了解配置详情。

根据当前任务遵循以下模式：

How to initialize SQL Connect in a Firebase project

如何在Firebase项目中初始化SQL Connect

Understand the app idea. Ask clarification questions if unclear.

Run

npx -y firebase-tools@latest init dataconnect

Validate that the app template and generated SDK are setup.

理解应用构想。如有不清楚的地方，询问澄清问题。

运行命令

npx -y firebase-tools@latest init dataconnect

。

验证应用模板和生成的SDK已正确设置。

How to build apps using SQL Connect locally

如何使用SQL Connect本地构建应用

Start the emulator:

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

Write schema and operations.

Run

npx -y firebase-tools@latest dataconnect:compile

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

to validate them.

Use the operations in your app and build it.

启动模拟器：

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

。

编写Schema和操作。

运行命令

npx -y firebase-tools@latest dataconnect:compile

或

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

验证它们。

在应用中使用这些操作并构建应用。

How to deploy SQL Connect to Cloud SQL

如何将SQL Connect部署到Cloud SQL

Run

npx -y firebase-tools@latest deploy --only dataconnect

运行命令

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.

如需完整可运行的Schema和操作代码示例，请查看**examples.md**。

如需即用型启动模板（CRUD、用户自有资源、多对多关系、YAML配置、SDK初始化），请查看**templates.md**。

firebase-data-connect

Original

Translation

Firebase SQL Connect

Firebase SQL Connect

Project Structure

项目结构

Key Tools for Validation

验证核心工具

Operation Strategies: GraphQL vs. Native SQL

操作策略：GraphQL vs 原生SQL

Development Workflow

开发工作流

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

1. 定义数据模型（
`schema/schema.gql`
）

2. Define Authorized Operations (
`connector/queries.gql`
,
`connector/mutations.gql`
)

2. 定义授权操作（
`connector/queries.gql`
、
`connector/mutations.gql`
）

3. Use type-safe SDK in your apps

3. 在应用中使用类型安全的SDK

Feature Capability Map

功能能力映射

Deployment & CLI

部署与CLI工具

How to initialize SQL Connect in a Firebase project

如何在Firebase项目中初始化SQL Connect

How to build apps using SQL Connect locally

如何使用SQL Connect本地构建应用

How to deploy SQL Connect to Cloud SQL

如何将SQL Connect部署到Cloud SQL

Examples

示例

firebase-data-connect

Original

Translation

Firebase SQL Connect

Firebase SQL Connect

Project Structure

项目结构

Key Tools for Validation

验证核心工具

Operation Strategies: GraphQL vs. Native SQL

操作策略：GraphQL vs 原生SQL

Development Workflow

开发工作流

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

1. 定义数据模型（schema/schema.gql）

2. Define Authorized Operations (connector/queries.gql, connector/mutations.gql)

2. 定义授权操作（connector/queries.gql、connector/mutations.gql）

3. Use type-safe SDK in your apps

3. 在应用中使用类型安全的SDK

Feature Capability Map

功能能力映射

Deployment & CLI

部署与CLI工具

How to initialize SQL Connect in a Firebase project

如何在Firebase项目中初始化SQL Connect

How to build apps using SQL Connect locally

如何使用SQL Connect本地构建应用

How to deploy SQL Connect to Cloud SQL

如何将SQL Connect部署到Cloud SQL

Examples

示例

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

1. 定义数据模型（
`schema/schema.gql`
）

2. Define Authorized Operations (
`connector/queries.gql`
,
`connector/mutations.gql`
)

2. 定义授权操作（
`connector/queries.gql`
、
`connector/mutations.gql`
）