在本機模擬 Spanner

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

模擬器支援 GoogleSQL 和 PostgreSQL 方言。支援所有用戶端程式庫語言。您也可以搭配 Google Cloud 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 執行模擬器

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

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

   gcloud components install cloud-spanner-emulator
   

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

   gcloud components update
   

2. 啟動模擬器：

   gcloud emulators spanner start
   

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

   • 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)。 這些警告是預期行為，可以放心忽略。

使用 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#	3.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"
};