运行 Datastore 模拟器

Datastore 模拟器可在本地模拟 Datastore 生产环境。 您可以使用该模拟器在本地开发和测试应用。此外,该模拟器有助于为 Datastore 生产实例生成索引,以及删除不必要的索引。本页面将指导您安装模拟器、启动模拟器,并设置环境变量,以便将应用连接到模拟器。

已知问题

默认情况下,Datastore 模拟器不会模拟 Datastore 模式 Firestore 引入的功能。以下默认模拟器行为与 Datastore 模式不匹配:

  • 默认情况下,模拟器会模拟最终一致性。Datastore 模式 Firestore 具有高度一致性。
  • 模拟器不允许事务内的非祖先查询。Datastore 模式 Firestore 不再具有此限制。
  • 模拟器不支持 IN!=NOT-IN 查询。
  • 模拟器不支持 COUNT(*) 等聚合查询。

不过,--use-firestore-in-datastore-mode 标志有助于放宽 Datastore 模式 Firestore 的上述一些限制。

  • 模拟器会模拟高度一致的非祖先查询。
  • 模拟器允许事务内的非祖先查询。
  • 模拟器取消了事务中实体组数不得超过 25 个的限制。

如需模拟 Datastore 模式 Firestore,请改为使用 gcloud emulators firestore start --database-mode=datastore-mode

准备工作

如需使用 Datastore 模拟器,您需要具备以下条件:

安装模拟器

Datastore 模拟器是 gcloud CLI 的一个组件。使用 gcloud components install 命令安装 Datastore 模拟器:

gcloud components install cloud-datastore-emulator

模拟器数据目录

该模拟器通过在指定的数据目录中创建 /WEB-INF/appengine-generated/local_db.bin 并将数据存储在 local_db.bin 中来模拟 Datastore。默认情况下,该模拟器使用数据目录 ~/.config/gcloud/emulators/datastore/local_db.bin 文件会在模拟器的会话之间持久保留。您可以设置多个数据目录,并将每个目录视为一个单独的本地 Datastore 模式实例。如需清除 local_db.bin 文件的内容,请停止模拟器并手动删除该文件。

启动模拟器

在命令提示符中执行 datastore start 来启动模拟器:

gcloud emulators datastore start [flags]

其中 [flags] 是提供给 gcloud CLI 的可选命令行参数。例如:

  • --data-dir=[DATA_DIR] 用于更改模拟器的数据目录。模拟器在 [DATA_DIR] 内创建 /WEB-INF/appengine-generated/local_db.bin 文件,或者使用现有文件(如有)。

  • --no-store-on-disk 用于将模拟器配置为不在磁盘上持久保留模拟器会话的任何数据。

如需查看可选标志的完整列表,请参阅 gcloud beta emulators datastore start 参考文档。

启动模拟器后,您应该看到类似于以下内容的消息:

...
[datastore] Dev App Server is now running.

要停止模拟器,请在命令提示符下按下 Control-C。

设置环境变量

启动模拟器后,您需要设置环境变量,以便将应用连接到模拟器,而不是连接到 Datastore 模式生产数据库。请在用于运行应用的同一台机器上设置这些环境变量。

每次启动模拟器时都需要设置环境变量。 环境变量取决于动态分配的端口号,当您重启模拟器时,端口号可能会更改。

自动设置变量

如果您的应用和模拟器在同一机器上运行,您可以自动设置环境变量:

Linux/macOS

使用命令运行 env-init

$(gcloud beta emulators datastore env-init)

Windows

使用 env-init 的输出结果创建并运行批处理文件:

gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd

您的应用现在将连接到 Datastore 模拟器。

手动设置变量

如果您的应用和模拟器在不同的机器上运行,请手动设置环境变量:

  1. 运行 env-init 命令:

    gcloud beta emulators datastore env-init
  2. 在运行您的应用的机器上,按照 env-init 命令的输出结果设置环境变量和值。例如:

    Linux/macOS
    export DATASTORE_DATASET=my-project-id
    export DATASTORE_EMULATOR_HOST=::1:8432
    export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
    export DATASTORE_HOST=http://::1:8432
    export DATASTORE_PROJECT_ID=my-project-id
    Windows
    set DATASTORE_DATASET=my-project-id
    set DATASTORE_EMULATOR_HOST=::1:8432
    set DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
    set DATASTORE_HOST=http://::1:8432
    set DATASTORE_PROJECT_ID=my-project-id

您的应用现在将连接到 Datastore 模拟器。 请注意,该命令提供的项目 ID 和端口与上述示例不同。

更新和删除索引

通过使用模拟器运行应用,您可以为 Datastore 模式生产数据库生成索引,还可以删除不必要的索引。如需了解详情,请参阅使用 gcloud CLI

移除环境变量

使用完模拟器后,停止模拟器 (Control-C) 并移除环境变量,以便将应用连接到 Datastore 模式生产数据库。

自动移除变量

如果您的应用和模拟器在同一台机器上运行,您可以自动移除环境变量:

Linux/macOS

使用命令运行 env-unset

$(gcloud beta emulators datastore env-unset)

Windows

使用 env-unset 的输出结果创建并运行批处理文件:

gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd

您的应用现在将连接到 Datastore 模式生产数据库。

手动移除变量

如果您的应用和模拟器在不同机器上运行,请手动移除环境变量:

  1. 运行 env-unset 命令:

    gcloud beta emulators datastore env-unset
  2. 在运行您的应用的机器上,按照 env-unset 命令的输出结果移除环境变量。例如:

    Linux/macOS
    unset DATASTORE_DATASET
    unset DATASTORE_EMULATOR_HOST
    unset DATASTORE_EMULATOR_HOST_PATH
    unset DATASTORE_HOST
    unset DATASTORE_PROJECT_ID
    Windows
    set DATASTORE_DATASET=
    set DATASTORE_EMULATOR_HOST=
    set DATASTORE_EMULATOR_HOST_PATH=
    set DATASTORE_HOST=
    set DATASTORE_PROJECT_ID=

您的应用现在将连接到 Datastore 模式生产数据库。