在本機模擬 Spanner

Google Cloud CLI 提供記憶體內的本機模擬器，可用於開發及測試應用程式。由於模擬器只會將資料儲存在記憶體中，因此重新啟動時會遺失所有狀態，包括資料、結構定義和設定。模擬器提供與 Spanner 正式環境服務相同的 API，可用於本機開發和測試，而非正式環境部署。

模擬器支援 GoogleSQL 和 PostgreSQL 方言。支援用戶端程式庫的所有語言。您也可以搭配使用模擬器與 gcloud CLI 和 REST API。

模擬器也以開放原始碼專案的形式提供，可在 GitHub 取得。

注意： 如要使用 90 天免費試用執行個體探索 Spanner，請參閱「建立 Spanner 免費試用執行個體」。

限制和差異

模擬器不支援下列項目：

• TLS/HTTPS、驗證、Identity and Access Management (IAM)、權限或角色。
• 在 PLAN 或 PROFILE 查詢模式中，傳回的查詢計畫為空白。
• ANALYZE 陳述式。模擬器會接受但忽略該值。
• 任何稽核記錄和監控工具。
• 資料庫捨棄保護。模擬器接受 enable_drop_protection 欄位，但即使啟用這項屬性，仍允許捨棄資料庫。

模擬器與 Spanner 正式環境服務還有以下差異：

• 模擬器和正式環境服務的錯誤訊息可能不同。
• 模擬器的效能和擴充性不如正式版服務。
• 讀寫交易和結構定義變更會鎖定整個資料庫，直到完成為止。
• 模擬器支援分區 DML 和 partitionQuery，但不會驗證陳述式是否可分區。這表示分區 DML 或 partitionQuery 陳述式可能會在模擬器中執行，但在正式環境服務中失敗，並顯示無法分區的陳述式錯誤。

如需支援、不支援和部分支援的 API 和功能完整清單，請參閱 GitHub 中的 README 檔案。

執行模擬器的選項

執行模擬器的方法有兩種：

• gcloud CLI
• Docker

請選擇適合您應用程式開發和測試工作流程的方式。

注意： 如要瞭解其他執行模擬器的方式，請參閱 README。

使用 gcloud CLI 執行模擬器

如要使用 gcloud CLI 執行模擬器，請按照下列步驟操作：

1. 安裝 cloud-spanner-emulator 元件：

   gcloud components install cloud-spanner-emulator
   

   如果已安裝 gcloud CLI，請執行下列指令，確保所有元件都已更新：

   gcloud components update
   

2. 啟動模擬器：

   gcloud emulators spanner start
   

   模擬器會使用兩個本機端點：

   • gRPC 要求的 localhost:9010
   • REST 要求的 localhost:9020
   注意： 啟動模擬器時，您可能會看到幾則警告訊息，內容與 proto 註冊衝突 (例如 WARNING: proto: file "google/rpc/status.proto" is already registered) 或初始化前的記錄訊息 (WARNING: All log messages before absl::InitializeLog() is called are written to STDERR) 有關。這些警告訊息屬於正常現象，可以放心忽略。

使用 Docker 執行模擬器

如要使用 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 要求。

   注意： 啟動模擬器時，您可能會看到幾則警告訊息，內容與 proto 註冊衝突 (例如 WARNING: proto: file "google/rpc/status.proto" is already registered) 或初始化前的記錄訊息 (WARNING: All log messages before absl::InitializeLog() is called are written to STDERR) 有關。這些警告訊息屬於正常現象，可以放心忽略。

設定 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 config set api_endpoint_overrides/spanner 時，系統可能會顯示警告，指出屬性值與目前設定範圍外的網域相關聯。輸入 y 或 yes 確認提示並繼續。

2. 設定完成後，gcloud CLI 會將指令傳送至模擬器，而非正式版服務。請使用模擬器的執行個體設定建立執行個體，藉此驗證這項設定：

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

切換設定

如要在模擬器和預設設定之間切換，請執行：

# To switch to default (production) configuration:
gcloud config configurations activate default

# To switch back to emulator configuration:
gcloud config configurations activate emulator

搭配模擬器使用用戶端程式庫

您可以設定 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	1.15.0 以上版本
小茹	v1.13.0+

C 的其他操作說明

如果是 C# 用戶端程式庫，請在連線字串中指定 emulatordetection 選項。與其他用戶端程式庫不同，C# 預設會忽略 SPANNER_EMULATOR_HOST 環境變數。以下範例顯示連線字串：

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