firebase-data-connect

Firebase SQL Connect

Firebase SQL Connect 是一项关系型数据库服务，使用 Cloud SQL for PostgreSQL，并提供 GraphQL 架构、自动生成的查询/变更操作和类型安全的 SDK。

说明

产品更名：Firebase Data Connect 已更名为 Firebase SQL Connect。本技能仓库中所有提及“Data Connect”或“Firebase Data Connect”的说明、 参考内容和示例，同样适用于“SQL Connect”和“Firebase SQL Connect”。

项目结构

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

验证的关键工具

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

1. 检查 GraphQL 架构：包括用户定义的架构和生成的扩展（位于 .dataconnect/schema/main/）。
2. 验证操作：针对架构运行 npx -y firebase-tools@latest dataconnect:compile。

操作策略：GraphQL 与原生 SQL

始终优先使用原生 GraphQL。原生 SQL 不具备类型安全性，并会绕过架构强制执行的结构。仅当用户明确要求，或任务需要高级数据库功能时，才使用原生 SQL。

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

开发工作流

遵循此严格工作流来构建应用。你必须阅读每个步骤链接的参考文件，以了解语法和可用功能。

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

定义 GraphQL 类型、表和关系（它们会映射到 Postgres 架构）。

请阅读 reference/schema.md，了解：

• @table、@col、@default
• 关系（@ref、一对多、多对多）
• 数据类型（UUID、Vector、JSON 等）

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

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

请阅读 reference/operations.md，了解：

• 查询：筛选（where）、排序（orderBy）、分页（limit/offset）。
• 变更：创建（_insert）、更新（_update）、删除（_delete）。
• 插入或更新：使用 _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，了解 Native SQL 操作：

• 使用 _select、_selectFirst、_execute 嵌入原始 SQL
• 位置参数（$1、$2）、引号和 CTE 的严格规则
• 高级 PostgreSQL 功能（PostGIS、窗口函数）

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

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

在 connector.yaml 中配置 SDK 生成：

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"

生成 SDK：

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

---

功能能力索引

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

功能	参考文件	关键概念
数据建模	reference/schema.md	@table、@unique、@index、关系
向量搜索	reference/search.md	Vector、@col(dataType: "vector")、嵌入
全文搜索	reference/search.md	@searchable、movies_search
数据 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()、自动刷新
Cloud Functions 集成	reference/cloud_functions.md	onMutationExecuted、触发事件
数据填充与迁移	reference/data_seeding.md	seed_data.gql、_insertMany、Admin SDK 批量操作
入门模板	templates.md	CRUD、用户自有资源、多对多关系、SDK 初始化

---

部署与 CLI

请阅读 reference/config.md，深入了解 配置。

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

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

1. 了解应用的构想。如有不清楚之处，请提出澄清问题。
2. 运行 npx -y firebase-tools@latest init dataconnect。
3. 验证应用模板和生成的 SDK 均已设置妥当。

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

1. 启动模拟器： npx -y firebase-tools@latest emulators:start --only dataconnect。
2. 编写架构和操作。
3. 将本地测试数据填入 seed_data.gql。请阅读 reference/data_seeding.md。
4. 运行 npx -y firebase-tools@latest dataconnect:compile 或 npx -y firebase-tools@latest dataconnect:sdk:generate 进行验证。
5. 在应用中使用这些操作并构建应用。

如何将 SQL Connect 部署到 Cloud SQL

1. 运行 npx -y firebase-tools@latest deploy --only dataconnect。

示例

如需查看完整、可运行的架构和操作代码示例，请参阅 examples.md。

如需查看可直接使用的入门模板（CRUD、用户自有资源、多对多关系、 YAML 配置、SDK 初始化），请参阅 templates.md。