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

Firebase SQL Connect 服务包含三个主要组件：

  • 具有自己的 SQL 架构的基础 PostgreSQL 数据库
  • SQL Connect 应用架构（在 .gql 文件中声明）
  • 多个连接器（在 .gql 文件中声明，在 connector.yaml 文件中配置）。

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

使用 CLI 部署 SQL Connect 服务时，您将迁移 SQL 架构，然后更新 SQL Connect 架构，再更新每个连接器。

重要的部署概念

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

架构部署

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

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

  • 严格模式验证要求数据库架构在应用架构更新之前与应用架构完全匹配。SQL Connect 架构中未使用的任何表或列都将从数据库中删除。

  • 兼容模式验证要求数据库架构在应用架构更新之前与应用架构兼容；任何删除架构、表或列的额外更改都是可选的。

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

    • 架构
    • 表
    • 列

连接器部署

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

SQL Connect 将连接器更新中的重大变更分析集成到 Firebase CLI 中。

CLI 会分析每个连接器相对于架构的更改，并针对可能改变客户端行为（消息为警告级别）或可能或将破坏（消息为破坏性级别）之前版本的客户端代码的连接器更改，发布一组评估消息。

例如：

  • 可能会改变客户端行为的连接器更改包括从查询中移除没有 @retired 架构注释的可为 null 字段。
  • 可能会或将要破坏客户端的连接器更改包括：将可为 null 的操作变量更改为没有默认值的非 null 变量，或将字段的数据类型更改为不兼容的类型（例如，从 String 更改为 Int）。

如需查看更全面的警告级和中断级场景列表，请参阅 CLI 参考指南。

按照部署工作流程操作

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

建议的部署流程包括：

  1. 列出当前已部署的 架构和连接器，并显示 firebase dataconnect:services:list。
  2. 管理所有架构更新。
    1. 使用 firebase dataconnect:sql:diff 检查 Cloud SQL 数据库与本地 SQL Connect 架构之间的 SQL 架构差异。
    2. 如果需要，请使用 dataconnect:sql:migrate 执行 SQL 架构迁移。
  3. 通过运行 firebase deploy 来执行架构和连接器部署，可以仅部署架构、仅部署连接器，也可以部署资源组合。

部署和管理 SQL Connect 资源

最好在执行部署之前验证生产资源。

firebase dataconnect:services:list

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

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

正常部署

firebase deploy --only dataconnect

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

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

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

--force 标志部署

firebase deploy --only dataconnect --force

如果您不担心连接器或 SQL 架构验证，可以重新运行该命令并添加 --force 以忽略这些验证。

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

部署所选资源

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

回滚部署

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

迁移数据库架构

如果您正在快速制作原型、尝试使用架构，并且知道架构更改具有破坏性，则可以计划使用 SQL 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"

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

更新连接器

运行 firebase deploy 时，CLI 会启动对适用连接器的更新，并发布适用的警告级（可能会影响客户端行为）和破坏级（可能或肯定会破坏）评估消息。

使用 CLI 管理连接器更新

在互动模式和非互动模式下，CLI 的行为略有不同。

正如您可能预料的那样，在互动模式下，CLI 会提示您接受所有消息。您可以使用 --force 标志替换并强制部署连接器。

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

在非互动模式下，只要没有严重程度为“中断”的评估，CLI 就会部署连接器。否则，脚本将退出并显示重大更改的日志。您可以通过设置 --force 标志来替换并部署。

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

如需了解详情，请参阅 CLI 参考指南。

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

Firebase 建议您在 SQL Connect 项目中遵循一些实践。

尽量减少重大变更

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

在处理新数据库时使用严格模式

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

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

当数据库中包含生产数据时，请使用兼容模式

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

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

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

接下来怎么做？