在本地模拟 Spanner

gcloud CLI 提供了一个本地内存模拟器,您可以使用该模拟器来免费开发和测试应用,而无需创建 Google Cloud 项目或结算账号。由于模拟器仅将数据存储在内存中,因此所有状态(包括数据、架构和配置)都会在重启时丢失。模拟器提供与 Spanner 生产服务相同的 API,旨在用于本地开发和测试,而不是用于生产部署。

模拟器同时支持 GoogleSQL 和 PostgreSQL 方言。它支持 客户端库。您还可以将模拟器与 Google Cloud CLIREST API 搭配使用。

该模拟器还是 GitHub 中的开源项目。

限制和差异

模拟器不支持以下内容:

模拟器与 Spanner 生产服务的不同之处在于 方法:

  • 模拟器和生产服务的错误消息可能不一致。
  • 模拟器的性能和可伸缩性无法与生产服务相比。
  • 读写事务和架构更改将锁定整个数据库以进行独占访问,直到任务完成。
  • 支持分区 DML分区查询,但模拟器不会进行检查以确保语句可分区。这意味着分区 DML 或分区查询语句可能在模拟器中运行,但可能会在生产服务中失败,并出现不可分区语句错误。

如需查看支持、不支持和部分支持的 API 和功能的完整列表,请参阅 GitHub 中的 README 文件。

安装并运行模拟器

运行模拟器的最常用方法是使用 gcloud CLIDocker。您可以选择适合应用开发和测试工作流的方式。

gcloud CLI

  1. 安装 gcloud CLI

  2. 对于 Windows 和 MacOS 用户,模拟器要求在系统上安装 Docker 并可通过系统路径访问。

  3. 更新 gcloud 以获取最新版本:

    gcloud components update
  4. 启动模拟器:

    gcloud emulators spanner start

    如果尚未安装模拟器,系统会提示您下载并安装模拟器的二进制文件。

    默认情况下,模拟器会托管两个本地端点:localhost:9010用于 gRPC 请求,localhost:9020 用于 REST 请求。

    如需详细了解此命令,请参阅 cloud emulators spanner

Docker

  1. 确保您的系统上安装了 Docker,并且可通过系统路径访问。

  2. 获取最新的模拟器映像:

    docker pull gcr.io/cloud-spanner-emulator/emulator
  3. 启动模拟器:

    docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator
    

    此命令运行模拟器,将容器中的端口映射到本地主机上的相同端口。您将有两个本地端点:用于 gRPC 请求的 localhost:9010 和用于 REST 请求的 localhost:9020

将 gcloud CLI 与模拟器搭配使用

要将模拟器与 gcloud 配合使用,您必须停用身份验证并替换端点。

我们建议创建单独的 gcloud 配置,以便您可以在模拟器和生产服务之间快速切换。要创建并激活模拟器配置,请运行以下命令:

gcloud config configurations create emulator
  gcloud config set auth/disable_credentials true
  gcloud config set project your-project-id
  gcloud config set api_endpoint_overrides/spanner http://localhost:9020/

配置完成后,系统会将您的 gcloud 命令发送到模拟器,而不是生产服务。您可以通过使用模拟器的实例配置创建实例来验证这一点:

gcloud spanner instances create test-instance \
   --config=emulator-config --description="Test Instance" --nodes=1

要在模拟器和默认配置之间切换,请运行以下命令:

gcloud config configurations activate [emulator | default]

将客户端库与模拟器搭配使用

通过设置 SPANNER_EMULATOR_HOST 环境变量,您可以将客户端库的受支持的版本与模拟器搭配使用。为此,可以采用多种方法。例如:

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

或使用 gcloud env-init

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

gcloud emulators spanner env-init > set_vars.cmd && set_vars.cmd

应用启动时,客户端库会自动检查 SPANNER_EMULATOR_HOST 并连接到模拟器(如果其正在运行)。

设置 SPANNER_EMULATOR_HOST 后,您可以按照以下入门指南测试模拟器。您可以忽略与项目创建、身份验证和凭据相关的说明,因为使用模拟器不需要这些步骤。

支持的版本

下表列出了支持模拟器的客户端库的版本。

客户端库 最低版本
C++ v0.9.x+
C# v3.1.0+
Go v1.5.0+
Java v1.51.0+
Node.js v4.5.0+
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

C# 的其他说明

对于 C# 客户端库,您还必须在连接字符串中指定 emulatordetection 选项。与其他客户端库不同,C# 默认会忽略 SPANNER_EMULATOR_HOST 环境变量。下面展示了执行此操作的方法:

var builder = new SpannerConnectionStringBuilder
{
    DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
    EmulatorDetection = "EmulatorOnly"
};