Firebase SQL Connect（原名 Firebase Data Connect）是一项关系型数据库服务，使用 Cloud SQL for PostgreSQL，配合 GraphQL schema、自动生成的查询/变更以及类型安全的 SDK。注意：该产品已由 Firebase Data Connect 更名为 Firebase SQL Connect，资料中所有关于“Data Connect”或“Firebase Data Connect”的说明同样适用于 SQL Connect。
一、用途 用于设计并部署基于 PostgreSQL 的安全 Firebase SQL Connect 后端，适合在设计带表与关系的 schema 时使用。
二、项目结构 dataconnect/ 目录包含：dataconnect.yaml（服务配置）、seed_data.gql（仅本地使用的原型/测试数据）、schema/schema.gql（数据模型，使用带 @table 的类型）、connector/connector.yaml（连接器配置与 SDK 生成）、connector/queries.gql（查询）、connector/mutations.gql（变更）。
三、验证工具
- 审查 GraphQL Schema：包括用户定义和自动生成的扩展（位于 .dataconnect/schema/main/）。
- 验证操作：运行 npx -y firebase-tools@latest dataconnect:compile 针对 schema 进行校验。
四、操作策略：GraphQL 与原生 SQL 默认始终使用原生 GraphQL。原生 SQL 缺乏类型安全并绕过 schema 强制结构，仅在用户明确要求或任务需要高级数据库特性时使用。
- 原生 GraphQL（默认）：适用于几乎所有用例，包括标准 CRUD、基本过滤/排序、简单关系连接，需要完整类型安全；使用自动生成字段（movie_insert、movies），具备强类型与 schema 强制。
- 原生 SQL（高级）：适用于 PostgreSQL 扩展（如 PostGIS）、窗口函数（RANK()）、复杂聚合或高度调优的子查询；通过 _select、_execute 等使用原始 SQL 字符串字面量，要求严格的位置参数（$1），无类型安全。
五、开发工作流
- 定义数据模型（schema/schema.gql）：定义 GraphQL 类型、表和关系（映射到 Postgres schema）。参考 reference/schema.md 了解 @table、@col、@default、关系（@ref、一对多、多对多）、数据类型（UUID、Vector、JSON 等）。
- 定义授权操作（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 了解原生 SQL 操作（通过 _select、_selectFirst、_execute 嵌入原始 SQL；位置参数 $1、$2 的严格规则、引号与 CTE；PostGIS、窗口函数等高级 PostgreSQL 特性）。
- 在应用中使用类型安全 SDK：在 connector.yaml 中配置 SDK 生成，可生成 javascriptSdk、kotlinSdk、swiftSdk 等，指定 outputDir 与 package。使用 npx -y firebase-tools@latest dataconnect:sdk:generate 生成 SDK。平台特定说明参见 reference/sdk_web.md（Web/TypeScript）、reference/sdk_android.md（Android/Kotlin）、reference/sdk_ios.md（iOS/Swift）、reference/sdk_admin_node.md（Admin/Node.js）、reference/sdk_flutter.md（Flutter/Dart）。
六、功能与参考文件映射 数据建模：reference/schema.md（@table、@unique、@index、Relations）；向量搜索：reference/search.md（Vector、@col(dataType: "vector")、embeddings）；全文搜索：reference/search.md（@searchable、movies_search）；上插数据：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 初始化：运行 npx -y firebase-tools@latest init dataconnect。本地开发：启动模拟器 npx -y firebase-tools@latest emulators:start --only dataconnect；编写 schema 与操作；将本地测试数据写入 seed_data.gql；运行 dataconnect:compile 或 dataconnect:sdk:generate 进行验证；在应用中使用操作并构建。部署到 Cloud SQL：运行 npx -y firebase-tools@latest deploy --only dataconnect。
八、示例 完整可用的 schema 与操作代码示例参见 examples.md；即用型入门模板（CRUD、用户拥有的资源、多对多、YAML 配置、SDK 初始化）参见 templates.md。