部署和管理 Data Connect 架构和连接器

Firebase Data Connect 服务有三个主要组件：

  • 具有自己的 SQL 架构的底层 PostgreSQL 数据库
  • Data Connect 应用架构（在 .gql 文件中声明）
  • 多个连接器（在 .gql 文件中声明）。

SQL 架构是数据的可信来源，Data Connect 架构是连接器查看这些数据的方式，连接器声明客户端可以用来访问这些数据的 API。

使用 CLI 部署 Data Connect 服务时，您需要先迁移 SQL 架构，然后更新 Data Connect 架构，最后更新每个连接器。

重要的部署概念

若要全面了解部署，请务必注意架构和连接器的关键概念。

架构部署

部署 Data Connect 架构会影响 Cloud SQL 数据库的 SQL 架构。无论您使用的是新数据库，还是需要以非破坏性方式调整现有数据库，Data Connect 都可以帮助您在部署期间迁移架构。

Data Connect 架构迁移有两种不同的架构验证模式：严格和兼容。

  • 严格模式验证要求数据库架构与应用架构完全匹配，然后才能更新应用架构。Data Connect 架构中未使用的任何表或列都将从数据库中删除。

  • 兼容模式验证要求数据库架构与应用架构兼容，然后才能更新应用架构；任何其他删除架构、表或列的更改都是可选的。

    兼容表示架构迁移只会影响应用架构中引用的表和列。数据库中未被应用架构使用的元素会保持不变。因此，部署后，您的数据库可能包含未使用的：

    • 架构
    • Tables
    • 列

连接器部署

Data Connect 查询和更改操作不是由客户端代码提交并在服务器上执行的。相反，在部署时，这些 Data Connect 操作会存储在服务器上，例如 Cloud Functions。这意味着，部署可能会中断现有用户。

遵循部署工作流

您可以在本地项目目录和 Firebase 控制台中处理 Data Connect 项目。

建议的部署流程包括：

  1. 使用 firebase dataconnect:services:list 列出当前部署的架构和连接器。
  2. 管理任何架构更新。
    1. 使用 firebase dataconnect:sql:diff 检查 Cloud SQL 数据库与本地 Data Connect 架构之间的 SQL 架构差异。
    2. 根据需要，使用 dataconnect:sql:migrate 执行 SQL 架构迁移。
  3. 通过运行 firebase deploy 执行架构和连接器部署，可以仅部署架构、仅部署连接器，也可以部署这两种资源的组合。

部署和管理 Data Connect 资源

建议您先验证生产环境资源，然后再执行部署。

firebase dataconnect:services:list

在本地项目目录中工作时，您通常会使用 firebase deploy 命令将架构和连接器部署到生产环境，并获得交互式反馈。

借助 --only dataconnect 标志，您可以使用任何 deploy 命令将 Data Connect 部署与项目中的其他产品分开。

正常部署

firebase deploy --only dataconnect

在此常规部署中，Firebase CLI 会尝试部署架构和连接器。

它用于验证新架构是否会破坏任何现有连接器。进行破坏性更改时，请遵循最佳实践。

它还会在更新 Data Connect 架构之前验证 SQL 架构是否已迁移。如果没有，系统会自动提示您完成迁移架构所需的所有步骤。

--force 标志部署

firebase deploy --only dataconnect --force

如果连接器或 SQL 架构验证都没有问题，您可以使用 --force 重新运行命令以忽略它们。

--force 部署仍会检查 SQL 架构是否与 Data Connect 架构匹配，并在发现不兼容时发出警告并提示。

部署所选资源

如需更精细地控制部署，请将 --only 标志与 serviceId 参数结合使用。如需仅部署特定服务的架构更改，请执行以下操作：

firebase deploy --only dataconnect:serviceId:schema

您还可以为指定的连接器和服务部署所有资源。

firebase deploy --only dataconnect:serviceId:connectorId

最后，您可以为单个服务部署架构和所有连接器。

firebase deploy --only dataconnect:serviceId

回滚部署

如需手动回滚，请检出代码的先前版本并进行部署。如果原始部署包含破坏性重大更改，您可能无法完全恢复任何已删除的数据。

迁移数据库架构

如果您要快速制作原型、试验架构，并且知道架构更改具有破坏性，则可以计划使用 Data Connect 工具来验证更改并监督更新方式。

比较 SQL 架构更改

您可以通过以下方式验证更改：

firebase dataconnect:sql:diff

您可以传递逗号分隔的服务列表。

该命令会将服务的本地架构与相应 Cloud SQL 数据库的当前架构进行比较。如果存在差异，则会输出用于修正差异的 SQL 命令

应用更改

当您对架构 Cloud SQL 实例的更改感到满意并准备好部署更改时，请发出 firebase dataconnect:sql:migrate 命令。系统会提示您批准更改。

firebase dataconnect:sql:migrate [serviceId]

在交互式环境中，系统会显示 SQL 迁移语句和操作提示。

在严格模式或兼容模式下进行迁移

在全新项目中，系统会应用默认的架构验证模式。migrate 命令的行为是应用应用架构所需的所有数据库架构更改，然后提示您批准用于删除架构、表或列的可选操作，以强制使数据库架构与应用架构完全匹配。

您可以通过修改 dataconnect.yaml 文件来调整此行为。取消注释 schemaValidation 键，并声明 COMPATIBLE，以便在迁移中仅应用必要的更改。

schemaValidation: "COMPATIBLE"

或者将行为设置为 STRICT，以便应用所有架构更改，并强制使数据库架构与应用架构保持一致。

schemaValidation: "STRICT"

如需了解详情，请参阅 Data Connect CLI 参考文档。

管理架构和连接器的最佳实践

Firebase 建议您在 Data Connect 项目中遵循一些做法。

尽量减少破坏性更改

  • Firebase 建议您将 Data Connect 架构和连接器文件保存在源代码控制系统中。
  • 请尽可能避免破坏性更改。破坏性更改的一些常见示例包括：
    • 从架构中移除字段
    • 将架构中可为 null 的字段设为不可为 null（即 Int -> Int!）
    • 重命名架构中的字段。
  • 如果您确实需要从架构中移除字段，请考虑将其拆分为多个部署，以尽可能降低影响：
    • 首先，移除连接器中对该字段的所有引用，然后部署更改。
    • 接下来，更新您的应用以使用新生成的 SDK。
    • 最后，移除架构 .gql 文件中的字段，迁移 SQL 架构，然后再次部署。

使用新数据库时，请使用严格模式

如果您将 Data Connect 与新数据库搭配使用，并积极开发应用架构，并且希望确保数据库架构与应用架构完全一致，则可以在 dataconnect.yaml 中指定 schemaValidation: "STRICT"。

这将确保系统也应用可选更改。

如果数据库中有生产数据，请使用兼容模式

如果您要更改包含生产数据的数据库，我们建议您在兼容模式下执行架构迁移，以确保不会丢弃现有数据。您可以在 dataconnect.yaml 中指定 schemaValidation: "COMPATIBLE"

在兼容模式下，系统只会将必要的架构迁移更改应用于您的数据库。

  • DROP SCHEMA、DROP TABLE 和 DROP COLUMN 被视为可选语句，系统不会为您的方案生成这些语句，即使您的数据库架构包含应用架构中未定义的架构、表或列也是如此。
  • 如果您的数据库表包含应用架构中未包含的非 null 列，系统会移除 NOT NULL 约束条件，以便您仍可使用定义的连接器将数据添加到表中。

后续步骤