在本機模擬 Spanner

gcloud CLI 提供記憶體內的本機模擬器，可用於開發及測試應用程式。由於模擬器只會將資料儲存在記憶體中，因此重新啟動後，所有狀態 (包括資料、結構定義和設定) 都會遺失。模擬器提供的 API 與 Spanner 生產服務相同，適用於本機開發和測試，不適用於生產部署。

模擬器支援 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#	3.1.0 以上版本
Go	v1.5.0 以上版本
Java	v1.51.0 以上版本
Node.js	4.5.0 以上版本
PHP	v1.25.0 以上
Python	1.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"
};