Cloud Spanner エミュレータの使用

Cloud SDK にはローカルなインメモリのエミュレータが用意されています。このエミュレータを使用すると、GCP プロジェクトや請求先アカウントを作成することなく、アプリケーションを開発してテストできます。エミュレータはメモリにのみデータを格納するため、再起動するとデータ、スキーマ、構成など、すべての状態が失われます。エミュレータは、Cloud Spanner の本番環境サービスと同じ API を提供し、本番環境へのデプロイではなく、ローカルでの開発とテストを目的として作られています。

エミュレータは、クライアント ライブラリのすべての言語をサポートしています。エミュレータは gcloud コマンドライン ツールREST API でも使用できます。

エミュレータは、GitHub でオープンソース プロジェクトとしても利用できます。

制限事項と相違点

エミュレータでは、次の機能はサポートされていません。

  • TLS/HTTPS、認証、IAM、権限、ロール。
  • PLAN または PROFILE クエリモードNORMAL のみがサポートされます。
  • 監査ログとモニタリング ツール。

また、エミュレータは、次の点で Cloud Spanner 本番環境サービスと異なります。

  • エミュレータと本番環境サービスでエラー メッセージが一致しない場合があります。
  • エミュレータのパフォーマンスとスケーラビリティは、本番環境サービスと同等ではありません。
  • 読み取り/書き込みトランザクションとスキーマ変更は、完了するまでデータベース全体を排他的にのみアクセスできるようにロックします。
  • パーティション化 DMLパーティション クエリはサポートされていますが、エミュレータはステートメントが分割可能かどうかは確認しません。つまり、パーティション化 DML またはパーティション クエリ ステートメントがエミュレータで実行される場合でも、本番環境ではパーティション化できないステートメント エラーにより失敗する可能性があります。

サポートされている、サポートされていない、部分的にサポートされている API と機能の完全なリストについては、GitHub の README ファイルをご覧ください。

エミュレータのインストールと実行

エミュレータを実行する最も一般的な方法は、gcloud CLIDocker を使用する方法です。アプリケーションの開発とテストのワークフローに適した方法を選択できます。

gcloud CLI

  1. Cloud SDK をインストールします

  2. Windows と MacOS でエミュレータを使用する場合は、システムに Docker をインストールし、システムパスで使用できるようにする必要があります。

  3. gcloud を更新して最新バージョンを取得します。

    gcloud components update
    
  4. Emulator を起動します。

    gcloud emulators spanner start
    

    エミュレータがまだインストールされていない場合、エミュレータ用のバイナリをダウンロードしてインストールするように求められます。

    デフォルトでは、エミュレータは 2 つのローカル エンドポイント(gRPC リクエストの場合は localhost:9010、REST リクエストの場合は localhost:9020)をホストします。

    このコマンドの詳細については、gcloud emulators spanner をご覧ください。

Docker

  1. Docker がシステムにインストールされ、システムパスで使用可能であることを確認してください。

  2. 最新のエミュレータ イメージを取得します。

    docker pull gcr.io/cloud-spanner-emulator/emulator
    
  3. Emulator を起動します。

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

    このコマンドはエミュレータを実行し、コンテナ内のポートをローカルホスト上の同じポートにマッピングします。ローカル エンドポイントには、gRPC リクエスト用の localhost:9010 と REST リクエスト用の localhost:9020 の 2 つがあります。

エミュレータで 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"
};