Firebase Data Connect 使用入门

提示： 加入 Firebase Data Connect 非公开预览版计划，详细了解 Firebase 的首个 SQL 解决方案。您将有机会抢先试用此产品，并获得有关 Firebase 为打造现代化应用开发体验而采取的全新举措的第一手信息。可在 Firebase Data Connect 产品页面进行注册。

预览版 ：Firebase Data Connect 目前处于非公开预览版阶段，这意味着该产品不在任何服务等级协议 (SLA) 或弃用政策的涵盖范围内，并且可能会以不向后兼容的方式更改。在整个非公开预览版阶段，Data Connect 及其文档将得到更新和改进。产品的非公开预览版不得在正式版应用中使用。

注意 ：如需访问 Firebase Data Connect 服务以及本指南中提到的大多数工具和来源，您需要注册非公开预览版计划。

在本快速入门中，您将学习如何完成以下操作：

• 将 Firebase Data Connect 添加到您的 Firebase 项目。
• 设置包含 Visual Studio Code 扩展程序的开发环境，以使用生产实例。
• 然后，我们会介绍如何执行以下操作：
  • 为电子邮件应用创建架构并部署到生产环境。
  • 为架构定义查询和变更。
  • 将最终原型部署到生产环境中。

前提条件

如需使用本快速入门，您需要做好以下准备。

• Linux、macOS 或 Windows
• Visual Studio Code

将 Data Connect 添加到您的项目并创建数据源

1. 如果您尚未创建 Firebase 项目，请先创建一个。
   1. 在 Firebase 控制台中，点击添加项目，然后按照屏幕上的说明操作。

2. 将您的项目升级为 Blaze 方案。这让您可以创建一个 Cloud SQL for PostgreSQL 实例。

   注意 ：虽然您在 Blaze 升级中设置了结算，但在预览版期间，您无需为 Data Connect 或默认 Cloud SQL for PostgreSQL 配置的用量付费。

3. 前往 Firebase 控制台的“Data Connect”部分，然后按照产品设置工作流操作。

4. 请为您的 CloudSQL for PostgreSQL 数据库选择一个位置。

5. 请记下项目、服务和数据库的名称及 ID，以便稍后确认。

6. 按照剩下的设置流程操作，然后点击完成。

   注意 ：完成 Cloud SQL for PostgreSQL 实例的预配最多可能需要 20 分钟。

选择并设置开发环境

首先，在 Visual Studio Code 中对应用进行原型设计。

您也可以选择安装本地 PostgreSQL 数据库，使用 Data Connect 模拟器进行本地开发。本快速入门指南的末尾将介绍此设置。

Data Connect 支持两种原型设计开发体验：

• 如果您是 Web 或 Kotlin Android 开发者，则可以在连接到 Cloud SQL for PostgreSQL 实例的同时，在本地对架构和操作进行原型设计，或（可选）在本地运行 PostgreSQL。

• 如果您是Web 开发者，则可以使用 IDX 在 IDX 工作区中进行原型设计，具体方法是：使用 PostgreSQL 的预配置 IDX 模板、带 Data Connect 模拟器的 VS Code 扩展程序，以及为您设置的快速入门代码。

VS Code 开发

如果您想在本地进行开发，而不是使用 IDX，请设置 Firebase VS Code 扩展程序，以帮助您快速迭代开发。

1. 为本地项目创建一个新目录。
2. 在新目录中打开 VS Code。
3. 从 Firebase 存储下载以 VSIX 软件包形式捆绑的扩展程序。
4. 在 VS Code 中，从 View 菜单中选择 Extensions。
5. 在扩展程序面板标题栏中，点击菜单图标 more_horiz，然后按照 Install from VSIX... 操作。

注意 ：该扩展程序包含 Marketplace GraphQL 语法突出显示扩展程序。您安装的其他 GraphQL 扩展程序可能会与 VSIX 文件中捆绑的 GraphQL 支持相冲突。

IDX 开发

IDX 是针对 Web 应用开发进行了优化的环境。如果您是 Kotlin Android 开发者，请按照 VS Code 开发标签页上的步骤操作。

要设置 Data Connect IDX 模板，请执行以下操作：

1. 在 Project IDX 网站上访问模板。
2. 按照设置流程操作。

设置本地项目

注意 ：如果您未使用 IDX，请按照本部分中的步骤操作。

按照常规说明安装 CLI。

然后，启用 Firebase Data Connect 实验。

firebase experiments:enable dataconnect

注意： 如果您使用的是现有 CLI 安装，请务必更新到最新版本。

如需设置本地项目，请初始化您的项目目录。

设置项目目录

初始化您的项目目录。

在 VS Code 左侧面板中，点击 Firebase 图标以打开 Firebase VS Code 扩展程序界面。

在 Firebase 扩展程序界面中：

1. 确保您已登录。
2. 使用 Google Cloud 控制台确认 Data Connect 设置流程（包括数据库预配）已完成。
3. 点击 Run firebase init 按钮。
4. 在 VS Code 下面板中查看 Terminal（终端）标签页以获取提示。
5. 选择 Data Connect 作为在此目录中使用的功能。
6. 出现提示时，提供您之前在控制台中创建的 Data Connect 项目的 ID。

此流程将在您的本地工作目录中创建 firebase.json 和 .firebaserc 文件，以及 dataconnect 子目录（包括重要的 dataconnect.yaml 和 connector.yaml 文件）。

创建 Data Connect 架构和查询

您的设置已完成。现在，我们可以开始使用 Data Connect 进行开发了。

开始使用 GraphQL 为用户和电子邮件建模。您将更新以下位置中的来源：

• /dataconnect/schema/schema.gql
• /dataconnect/default-connector/queries.gql

开始开发架构

在 Firebase 项目目录中，记下 dataconnect 文件夹。您可以在此处使用 GraphQL 为 Cloud SQL 数据库定义数据模型。

在 /dataconnect/schema/schema.gql 文件中，开始定义包含用户和电子邮件的架构。

用户

在 Data Connect 中，GraphQL 字段映射到列。用户拥有 uid、name 和电子邮件地址 address。Data Connect 可识别多种原始数据类型：String 和 Date。

复制以下代码段或取消对文件中的相应行的注释。

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

默认情况下，如果 UUID id 键未提供，Firebase Data Connect 将添加该键。不过，在这种情况下，您希望我的 uid 作为主键，您可以通过 @table(key: "uid") 指令执行此操作。

电子邮件

现在您拥有了用户，可以对电子邮件进行建模了。您可以在此处添加电子邮件数据的典型字段（或列）。这一次，我们省略了添加主键的操作，因为您可以依靠 Data Connect 来管理它。

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   sent: Date!
   text: String!
   from: User!
}

请注意，from 字段会映射到 User 类型。Data Connect 了解这是 Email 和 User 之间的关系，并将为您管理此关系。

将架构部署到生产环境

由于您使用 Firebase VS Code 扩展程序来处理生产数据库，因此需要先部署架构，然后才能继续操作。

注意 ：预配 Cloud SQL for PostgreSQL 实例最多可能需要 20 分钟。在实例准备就绪之前，您将无法进行部署。在部署架构之前，请使用 Google Cloud 控制台确认 Data Connect 设置流程（包括数据库预配）已完成。

1. 您可以使用 Firebase VS Code 扩展程序进行部署。
   • 在扩展程序界面中的“Firebase Data Connect”面板下，点击部署。

2. 或者，您也可以使用 Firebase CLI。

   firebase deploy
   

3. 在扩展程序或 CLI 流程中，您可能需要审核架构更改并批准可能具有破坏性的修改。系统会提示您执行以下操作：

   • 使用 firebase dataconnect:sql:diff 查看架构更改
   • 如果您对更改感到满意，请通过 firebase dataconnect:sql:migrate 启动的流程应用这些更改。

执行变更以将数据添加到表中

在 VS Code 编辑器面板中，您可以看到 CodeLens 按钮显示在 /dataconnect/schema/schema.gql 中的 GraphQL 类型之上。

开发时查询和变更

与这些 CodeLens 按钮关联的未命名操作是快速且实用的操作，在本例中，这些操作是将数据添加到表中。Data Connect 使用 GraphQL 变更来描述如何以及谁可以对数据库执行操作。使用此按钮可创建用于快速实现数据种子的开发时操作。

由于您已将架构部署到生产环境，因此您可以使用 schema.gql 中的添加数据 CodeLens 按钮和生成的文件中的 Run (Production) 按钮，在后端执行这些操作。

如需将记录添加到 User 和 Email 表中，请执行以下操作：

1. 在 schema.gql 中，点击 User 类型声明上方的添加数据按钮。
2. 在生成的 User_insert.gql 文件中，为三个字段硬编码数据。
3. 点击 Run (Production) 按钮。
   
4. 重复前面的步骤，将记录添加到 Email 表，并按照生成的 Email_insert 变更中的提示，在 fromUid 字段中提供用户的 uid。

编写查询以列出电子邮件

而最有趣的部分是查询。作为开发者，您习惯于编写 SQL 查询而不是 GraphQL 查询，因此一开始您可能会感觉略有不同。然而，GraphQL 比原始 SQL 更为简洁和类型安全。我们的 VS Code 扩展程序还简化了开发体验

开始修改 /dataconnect/default-connector/queries.gql 文件。如果您想获取所有电子邮件，请使用这样的查询。

# File `/dataconnect/default-connector/queries.gql`

query ListEmails @auth(level: NO_ACCESS) {
  emails {
    id, subject, text, sent
    from {
      name
    }
  }
}

使用附近的 CodeLens 按钮执行查询。

这里一个真正令人兴奋的功能是能够像处理图表一样处理数据库的关系。由于电子邮件地址包含引用用户的 from 字段，因此您可以嵌套到该字段并获取用户的相关信息。

将完成的原型部署到生产环境

您已完成开发迭代。现在，您可以通过 Firebase 扩展程序界面或 Firebase CLI 将架构、数据和查询部署到服务器，就像使用架构一样。

部署后，您的 Data Connect 服务即可处理来自客户端的操作。Cloud SQL for PostgreSQL 实例将使用其最终部署的生成架构和数据进行更新。

（可选）在本地安装 PostgreSQL

在本地安装 PostgreSQL 并将其与模拟器集成后，您可以在完全本地的开发环境中设计原型。

您可以安装 PostgreSQL 的新实例，也可以使用现有实例。

安装 PostgreSQL

按照适用于您的平台的说明安装 PostgreSQL 15.x 版。

注意 ：请务必记下用户名和密码，以备日后访问。

• macOS。下载并安装 Postgres.app。
• Windows：使用 PostgreSQL 下载页面中的 EDB 安装程序。
• Docker：拉取并运行 pgvector/pgvector:15 映像，其中包含 PostgreSQL 15.x 和矢量支持。
• Linux：我们建议将 Docker 与上述映像搭配使用，但您也可以按照常见发行版的替代说明进行操作。

请记下安装过程中的主机名、端口、用户名和密码以及相关参数输出。

如需连接到 PostgreSQL 实例，模拟器需要：

• 这些设置配置参数
• dataconnect.yaml 中的数据库名称，以及在本地实例中初始化的相应名称的数据库。

使用连接字符串更新 .firebaserc

使用您的本地 PostgreSQL 配置详细信息（包括本地 PostgreSQL 用户名和密码）将连接字符串添加到 .firebaserc 文件中的以下键。

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

连接到您的本地 PostgreSQL 实例

完成此配置后，如需连接到您的本地数据库，请执行以下操作：

1. 在 VS Code 的左侧面板中，点击 Firebase 图标以打开 Firebase VS Code 扩展程序界面。
2. 点击 Connect to Local PostgreSQL 按钮。

后续步骤

提示： 本演示是否让您有兴趣参与非公开预览版计划？如果是这样，请在 Firebase Data Connect 产品页面进行注册。