在本地模拟 Spanner

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

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

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

注意 ：如需使用 90 天免费试用实例探索 Spanner，请参阅创建 Spanner 免费试用实例。

限制和差异

模拟器不支持以下内容：

• TLS/HTTPS、身份验证、Identity and Access Management、权限或角色。
• 在 PLAN 或 PROFILE 查询模式下，返回的查询计划为空。
• ANALYZE 语句。模拟器会接受该请求，但会忽略它。
• 任何审核日志记录和监控工具。

模拟器与 Spanner 生产服务还有以下不同：

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

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

运行模拟器的选项

您可以通过以下两种常用方式运行模拟器：

• gcloud CLI
• Docker

选择适合应用开发和测试工作流的方式。

注意 ：如需了解运行模拟器的更多方法，请参阅 README。

为 gcloud CLI 设置模拟器

对于 Windows 和 macOS 用户，在安装模拟器之前，请执行以下操作：

• 在您的工作站上安装 gcloud CLI 组件：

  gcloud components install
  

  如果您已安装 gcloud CLI，请运行以下命令，确保其所有组件都已更新：

  gcloud components update
  

使用 gcloud CLI 创建和配置模拟器

如需将模拟器与 gcloud CLI 搭配使用，您必须停用身份验证并替换端点。我们建议创建单独的 gcloud CLI 配置，以便您可以在模拟器和生产服务之间快速切换。

1. 创建并激活模拟器配置：

     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 CLI 命令发送到模拟器，而不是生产服务。您可以通过使用模拟器的实例配置创建实例来验证这一点：

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

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

   gcloud config configurations activate [emulator | default]
   

2. 使用 gcloud CLI 启动模拟器。

在 Docker 中安装模拟器

1. 在系统上安装 Docker，并使其可通过系统路径访问。

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

   docker pull gcr.io/cloud-spanner-emulator/emulator
   

3. 在 Docker 中运行模拟器：

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

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

4. 使用 gcloud CLI 启动模拟器。

使用 gcloud CLI 启动模拟器

使用 gcloud emulators spanner 命令启动模拟器：

gcloud emulators spanner start

模拟器使用两个本地端点：

• localhost:9010（适用于 gRPC 请求）
• localhost:9020，用于执行 REST 请求

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

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

重要提示 ：如果您使用的是 C#，请参阅 C#的其他说明。

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++ 使用入门

• C＃ 使用入门。您必须设置连接字符串选项。请参阅 C＃的其他说明。

• Go 使用入门

• Java 使用入门

• Node.js 使用入门

• PHP 使用入门

• Python 使用入门

• Ruby 使用入门

支持的版本

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

客户端库	最低版本
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"
};