Firebase SQL Connect

Firebase SQL Connect 是一种使用 Cloud SQL for PostgreSQL 的关系型数据库服务，支持 GraphQL schema、自动生成的查询/变更，以及类型安全的 SDK。

[!NOTE] 产品更名：Firebase Data Connect 已更名为 Firebase SQL Connect。本 skill 仓库中所有引用 “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 Schema：用户定义的 schema 以及生成的扩展（位于 .dataconnect/schema/main/）。
2. 验证操作：针对 schema 运行 npx -y firebase-tools@latest dataconnect:compile。

操作策略：GraphQL 与 Native SQL

始终默认使用 Native GraphQL。Native SQL 缺乏类型安全，并且会绕过 schema 强制实施的结构。只有在用户明确要求，或任务需要高级数据库功能时，才使用 Native SQL。

| 策略 | 何时使用 | 实现方式 | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Native GraphQL（默认） | 几乎所有用例。标准 CRUD、基本筛选/排序、简单关系连接。需要完整类型安全。 | 自动生成的字段（movie_insert、movies）。强类型和 schema 强制实施。 | | Native SQL（高级） | PostgreSQL 扩展（例如 PostGIS）、窗口函数（RANK()）、复杂聚合，或高度优化的子查询。 | 通过 _select、_execute 等使用原始 SQL 字符串字面量。需要严格的位置参数（$1）。没有类型安全。 |

开发工作流

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

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

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

阅读 [reference/schema.md](reference/schema.md) 以了解：

- @table、@col、@default

- 关系（@ref、一对多、多对多）

- 数据类型（UUID、Vector、JSON 等）

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

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

阅读 [reference/operations.md](reference/operations.md) 以了解：

- 查询：筛选（where）、排序（orderBy）、分页（limit/offset）。

- 变更：创建（_insert）、更新（_update）、删除（_delete）。

- Upsert：使用 _upsert 来“插入或更新”记录（对于用户资料至关重要）。

- 事务：使用 @transaction 进行多步原子操作。使用 _expr: "response.<prevStep>" 在步骤之间传递数据。

阅读 [reference/security.md](reference/security.md) 以了解授权：

- @auth(level: ...) 用于 PUBLIC、USER 或 NO_ACCESS。

- @check 和 @redact 用于行级安全和验证。

阅读 [reference/realtime.md](reference/realtime.md) 以了解实时订阅：

- @refresh 指令，用于基于时间的轮询和事件驱动更新。

- 使用 CEL 条件精确限定刷新触发范围。

阅读 [reference/native_sql.md](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"

生成 SDK：

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

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

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

______________________________________________________________________

功能能力映射

如果你需要实现特定功能，请查阅映射的参考文件：

| 功能 | 参考文件 | 关键概念 | | :------------------------------ | :----------------------------------------------------------- | :------------------------------------------------- | | 数据建模 | [reference/schema.md](reference/schema.md) | @table、@unique、@index、关系 | | 向量搜索 | [reference/search.md](reference/search.md) | Vector、@col(dataType: "vector")、嵌入 | | 全文搜索 | [reference/search.md](reference/search.md) | @searchable、movies_search | | 数据 upsert | [reference/operations.md](reference/operations.md) | _upsert 变更 | | 复杂筛选 | [reference/operations.md](reference/operations.md) | _or、_and、_not、eq、contains | | 事务 | [reference/operations.md](reference/operations.md) | @transaction、response 绑定 | | 环境配置 | [reference/config.md](reference/config.md) | dataconnect.yaml、connector.yaml | | 实时订阅 | [reference/realtime.md](reference/realtime.md) | @refresh、subscribe()、自动刷新 | | Cloud Functions 集成 | [reference/cloud_functions.md](reference/cloud_functions.md) | onMutationExecuted、触发事件 | | 数据填充与迁移 | [reference/data_seeding.md](reference/data_seeding.md) | seed_data.gql、_insertMany、Admin SDK 批量操作 | | 入门模板 | [templates.md](templates.md) | CRUD、用户拥有的资源、多对多、SDK 初始化 |

______________________________________________________________________

部署与 CLI

阅读 [reference/config.md](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. 编写 schema 和操作。
3. 将本地测试数据填充到 seed_data.gql。阅读 [reference/data_seeding.md](reference/data_seeding.md#local-prototyping-data-seeding)。
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。

示例

有关完整且可运行的 schema 和操作代码示例，请参阅 [examples.md](examples.md)。

有关可直接使用的入门模板（CRUD、用户拥有的资源、多对多、YAML 配置、SDK 初始化），请参阅 [templates.md](templates.md)。