Data Connect 的 Firebase CLI 命令参考

借助 Firebase CLI，您可以通过命令行管理和配置 Firebase 产品和服务。

CLI 提供了一些命令，可用于执行各种 Data Connect任务，例如创建新的Data Connect 项目、初始化相应的本地工作目录、设置 Data Connect模拟器、列出Data Connect资源、 生成客户端 SDK 等。

设置命令

将 Data Connect 添加到 Firebase 项目

firebase init

使用 firebase init 设置新的本地项目配置。此工作流 会在 您的目录中创建或更新 Firebase 配置文件。

firebase init

firebase init 流程会引导您设置服务和数据库， 并选择性地安装 Data Connect 模拟器和 配置生成的 SDK。

服务和数据库设置

如果您选择 dataconnect 进行产品设置，CLI 会提示您输入新的服务名称和位置，以及是否关联现有 Cloud SQL for PostgreSQL 实例或创建新实例。

如果关联了现有实例，CLI 会检查兼容的设置，例如 IAM 身份验证和公共 IP 地址。

Local Emulator Suite 设置

CLI 流程提供设置模拟器，包括 Data Connect 模拟器。

Data Connect 模拟器命令

启动 Data Connect 模拟器

emulators:start/exec

firebase emulators:start/exec

使用 Local Emulator Suite 版本的 Data Connect 模拟器 ，在交互模式下使用 start，或在脚本驱动的非交互模式下使用 exec。

导出和导入本地 PostgreSQL 数据

为了支持本地原型设计和测试以及持续集成，您可以导出存储在本地数据库实例中的数据，并在开发迭代和测试运行之间导入数据。

导出内容会存储为本地 PostgreSQL 数据库的快照。

Data Connect 提供三种导出/导入方法：

  • 在 firebase.json 中配置自动导出/导入，以便在模拟器关闭和启动时提供快照备份
  • 使用 CLI 手动导出/导入
  • 使用 Data Connect VS Code 扩展程序界面手动导出/导入

在 firebase.json 中配置自动导出和导入

如需在开发会话之间备份数据，请在 firebase init 序列期间指定自动备份位置。此位置存储在 firebase.json 的 emulators.dataconnect.dataDir 字段中。您所做的任何数据更改都会在模拟器运行之间自动保存到此处，因此在本地测试和探索期间非常有用。

手动导出：emulators:export 和 emulators:start/exec --import

在 Data Connect 模拟器运行时，在单独的终端中， 运行 firebase emulators:export 命令以保存数据快照。 然后，您可以使用 --import 标志从该快照启动模拟器。

# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

手动导出/导入：Data Connect VS Code 扩展程序

在 Data Connect VS Code 扩展程序界面中，在模拟器运行时，使用导出模拟器数据 按钮导出数据以导出当前数据库内容。默认导出位置是项目目录根目录下的 exportedData 目录。

您可以使用 CLI 导入此数据，如上一部分所述。 您还可以在通过 VS Code 启动模拟器之前导入此数据，方法是点击配置模拟器 链接并设置导入路径 。

架构和连接器管理命令

本部分包含用于管理架构和连接器的命令的 CLI 参考信息。

如需了解与这些命令相关的操作用例和推荐做法，请参阅 架构和连接器管理指南。

部署架构和连接器

deploy

firebase deploy

此命令会为 Data Connect 服务部署资源，这些服务在 firebase.json中编入了索引。如有必要，系统会执行 架构迁移 和 连接器更新。

命令 说明

firebase deploy

标志 说明

–-only dataconnect

为此 项目的所有 Data Connect 服务部署架构和连接器，但不部署其他 Firebase 产品资源。

–-only dataconnect:serviceId

为指定的 Data Connect 服务部署架构和连接器。

–-only dataconnect:serviceId:connectorId

为指定的 Data Connect 服务部署单个连接器。

–-only dataconnect:serviceId:schema

为指定的 Data Connect 服务部署架构。

借助 –-only 标志，您可以传递以英文逗号分隔的值，以部署所需的任何资源子集。

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

列出 Data Connect 服务、架构和连接器

dataconnect:services:list

firebase dataconnect:services:list

此命令会输出有关在项目上部署的服务、架构和连接器的基本信息。

比较和迁移 SQL 架构

当您运行 firebase deploy 时，CLI 会在部署更新之前执行 SQL 架构 比较。您还可以使用一组 dataconnect:sql 命令直接执行比较和更新。

dataconnect:sql:diff

firebase dataconnect:sql:diff

此命令会将服务的本地架构与相应 Cloud SQL 数据库的当前架构进行比较。它会输出将运行以将数据库迁移到新架构的命令。

命令 说明

firebase dataconnect:sql:diff

标志/参数 说明

serviceId

指定服务。如果省略，则输出 firebase.json 中所有服务的差异。

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

此命令会将本地架构更改应用于服务的 Cloud SQL 数据库。

当您使用默认 dataconnect.yaml文件设置新的本地 Data Connect 项目时，dataconnect:sql:migrate 命令 的行为是先提示您进行任何必需的更改，然后提示您进行任何可选 的更改，然后再执行更改。您可以修改此行为，以始终 包含或忽略可选更改，方法是更新您的 dataconnect.yaml 配置，如以严格模式或兼容模式迁移架构中所述

在交互式环境中，CLI 会显示每个迁移 SQL 语句（以及它是否具有破坏性），并提示您进行要应用的更改。 传递 --force 标志相当于接受所有提示。

在非交互式环境中：

  • 如果没有 --force，则只会进行非破坏性更改。如果有破坏性更改，CLI 会中止，并且不会进行任何更改。
  • 如果有 --force，则会进行所有更改。如果这包括任何破坏性更改，系统会输出这些更改，并提示您是否要继续，除非提供了 --force 标志。
命令 说明

firebase dataconnect:sql:migrate

标志 说明

serviceId

迁移指定服务的数据库。如果您的项目只有一个服务，系统会推断出 serviceId。

–-force

自动接受提示。

与其他 --only 标志一样，您可以提供多个以英文逗号分隔的服务。

以严格模式或兼容模式迁移架构

Data Connect 架构迁移有两种不同的架构验证 模式：严格模式和兼容模式。严格模式验证要求数据库架构与应用架构完全匹配，然后才能部署应用架构。兼容模式验证要求数据库架构与应用架构兼容，这意味着数据库中未被应用架构使用的元素将保持不变。

架构和连接器管理指南介绍了这些架构验证模式以及架构迁移的最佳实践

验证模式使用 dataconnect.yaml 文件中的 schemaValidation 键进行定义。如果未指定 schemaValidation，CLI 会应用兼容的更改，并在执行任何严格的更改之前提示您。请参阅 配置参考。

管理对连接器的更改

当您运行 firebase deploy 时，CLI 会启动适用连接器的 更新。CLI 会分析每个连接器的更改，并针对可能导致旧版客户端代码中出现意外行为（消息为警告级别）或中断（消息为中断级别）的连接器更改发布一组评估消息。

影响评估 场景
警告级别（线路兼容，可能会更改行为）
  • 从查询中移除可为 null 的字段，且没有 @retired 注解。
中断级别（线路不兼容，可能会中断客户端）
  • 将可为 null 的变量更改为不可为 null，且没有默认 值。
  • 将字段的数据类型更改为与 JSON 兼容的类型 （例如，将 Int 更改为 Float）。
  • 将不可为 null 的列更改为可为 null。
  • 移除可为 null 的变量，且没有 @retired 注解。
  • 移除具有默认值的不可为 null 的变量，且没有 @retired 注解。
中断级别（线路不兼容，将 中断客户端）
  • 移除操作，且没有 @retired 注解。
  • 从查询中移除不可为 null 的字段，且没有 @retired 注解。
  • 添加不可为 null 的变量，且没有默认值。
  • 将字段的数据类型更改为不兼容的类型（例如，将 String 更改为 Int）。
  • 移除不可为 null 的变量，且没有默认值，也没有 @retired 注解。

在交互式环境中，CLI 会显示每个连接器评估，并提示您进行要应用的更改。传递 --force 标志相当于接受所有评估。

在非交互式环境中：

  • 如果仅出现警告级别评估（可能会更改行为），则所有连接器都将部署，并且警告将记录到终端。
  • 如果出现任何中断级别评估，则不会部署任何连接器，并且警告将记录到终端。您可以使用 --force 标志替换。

审核授权代码

Data Connect 会分析 您的连接器代码，帮助您审核授权策略，具体方法是当您使用 firebase deploy 从 Firebase CLI 部署到服务器时。您可以使用此审核来帮助您查看代码库。

部署连接器时，CLI 会输出连接器中现有、修改和新操作代码的评估。

对于修改和新操作，当您在新操作中使用某些访问权限级别时，或者当您修改现有操作以使用这些访问权限级别时，CLI 会发出警告并提示您进行确认。

系统始终会针对以下情况显示警告和提示：

  • PUBLIC

并且，当您不使用 auth.uid 通过过滤条件扩充以下访问权限级别时，系统会针对这些访问权限级别显示警告和提示：

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

如需详细了解授权，请参阅 授权和证明指南。

SDK 命令

生成 SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

此命令会生成在 connector.yaml 中声明的类型化 SDK。

另请参阅有关使用 Web SDK、 Android SDK 和 iOS SDK 的指南。

命令 说明

firebase dataconnect:sdk:generate

标志 说明

–-watch

使进程保持运行，并在您保存 对架构和连接器 GQL 文件所做的更改时生成新的 SDK。

如果生成失败，错误将输出到 stdout，生成的代码 不会更改，并且命令将继续运行。

–-only connectorId:platform

仅为单个平台和单个连接器生成 SDK。

借助 –only 标志，您可以传递以英文逗号分隔的值。

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

Cloud SQL 管理命令

授予 Cloud SQL 的 SQL 角色

Data Connect 在 Cloud SQL 上托管的您自己的 PostgreSQL 实例之上运行。SQL 角色命令可帮助您管理数据库表中的权限。

dataconnect:sql:setup

firebase dataconnect:sql:setup

此命令会配置数据库中表的初始全局权限。

默认数据库预配和管理流程假定您的项目 使用新的（绿地）数据库，并且当您调用 firebase deploy 时， Data Connect 会显示要进行的数据库架构更改，并在您批准后 执行任何迁移。如果这是您首选的流程，dataconnect:sql:setup 会提示您授予权限，包括 superuser 架构所有权。

对于现有（棕地）数据库，您可能拥有自己的迁移架构的工作流，并希望自行维护架构所有权。如果这 是您首选的流程，请务必在 dataconnect:sql:setup 提示中拒绝 Data Connect是否应为您处理 SQL 迁移。拒绝后，Data Connect 将仅对您的数据库表具有 read 和 write 访问权限，但架构所有权和迁移 仍将由您负责。

如需了解更多讨论和用例，请参阅 管理服务和数据库。

dataconnect:sql:grant

firebase dataconnect:sql:grant

在某些情况下，您可能需要直接访问数据库 以查询或更新 Data Connect 应用生成的数据。为此，您需要将本部分中定义的某个角色授予所需的用户或服务账号。

如需详细了解授予的角色，请参阅 PostgreSQL 用户角色。

角色 SQL 角色 权限 用法 可授予
读取者 firebasereader_<db_name>_<schema_name> 对数据库的只读权限。

可以对指定架构中的所有表执行 SELECT 操作。		 非常适合需要检索数据但不需要修改数据的用户或服务。 是
写入者 firebasewriter_<db_name>_<schema_name> 对数据库的读写权限。

可以对架构中的所有表执行 SELECT、INSERT、UPDATE、DELETE 和 TRUNCATE 操作。		 适合需要在数据库中修改数据的用户或服务。 是
所有者 firebaseowner_<db_name>_<schema_name> 架构所有者。

对架构中的所有表和序列拥有所有权限。		 此角色与 IAM roles/cloudsql.client 角色结合使用，可授予对数据库执行迁移的权限。

例如，在调用 firebase dataconnect:sql:migrate 时。		 是
超级用户 cloudsqlsuperuser 内置超级用户角色，对数据库拥有完整权限。

除了所有者权限之外，它还可以创建架构、删除架构、安装扩展程序以及执行任何其他管理任务。

通过以“firebasesuperuser”身份登录 CLI 进行访问。		 需要安装扩展程序、创建初始架构以及向其他用户授予任何可授予的 SQL 角色。

如果非管理员用户需要超级用户权限，迁移将失败，并提示用户让数据库管理员（即具有 roles/cloudsql.admin 的用户）运行具有特权的 SQL 命令。		 授予具有 roles/cloudsql.admin 的用户，无法直接从 Firebase CLI 授予
命令 说明

firebase dataconnect:sql:grant

标志/参数 说明

-R, --role role

要授予的 SQL 角色，可以是所有者、写入者或读取者。

-E, --email email_address

要授予角色的用户或服务账号的电子邮件地址。

全局选项

以下全局选项适用于所有命令：

  • --json 将 CLI 输出切换为 JSON，以便供其他工具解析。
  • --noninteractive 和 --interactive 会根据需要替换对非 TTY 环境的自动检测。