Datastore エミュレータの実行

Datastore エミュレータは、Datastore 本番環境のローカル エミュレーションを可能にします。 このエミュレータを使用して、アプリケーションを開発してローカルでテストすることができます。加えて、このエミュレータを使用すると、Cloud Datastore の本番環境インスタンス用のインデックスを生成し、不要なインデックスを削除することができます。このページでは、エミュレータのインストール、エミュレータの開始、およびアプリケーションをエミュレータに接続するための環境変数の設定について説明します。

既知の問題

デフォルトでは、Datastore エミュレータは Datastore モードの Firestore で導入された機能をエミュレートしません。次のデフォルト エミュレータの動作は、Datastore モードと一致しません。

  • デフォルトで、エミュレータは結果整合性をシミュレートします。Datastore モードの Firestore は強整合性に対応しています。
  • エミュレータでは、トランザクション内で祖先以外のクエリを使用できません。Datastore モードの Firestore にはこの制限はなくなりました。
  • エミュレータでは、IN!=NOT-IN クエリはサポートされていません。
  • エミュレータでは、COUNT(*) などの集約クエリはサポートされていません。

ただし、--use-firestore-in-datastore-mode フラグを使用すると、Datastore モードの Firestore に関する制限の一部が緩和されます。

  • エミュレータは、強整合性を持つ祖先以外のクエリをシミュレートします。
  • エミュレータでは、トランザクション内で祖先以外のクエリを使用できます。
  • エミュレータでは、トランザクション内のエンティティ グループ数に関する上限(最大 25 個)が解消されています。

Datastore モードの Firestore をエミュレートするには、代わりに gcloud emulators firestore start --database-mode=datastore-mode を使用します。

始める前に

Datastore エミュレータを使用するには、次のものが必要です。

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

Datastore エミュレータは gcloud CLI のコンポーネントです。gcloud components install コマンドを使用して、Datastore エミュレータをインストールします。

gcloud components install cloud-datastore-emulator

エミュレータ データ ディレクトリ

エミュレータは、指定されたデータ ディレクトリに /WEB-INF/appengine-generated/local_db.bin を作成し、local_db.bin にデータを格納して、Datastore のシミュレーションを行います。デフォルトでは、エミュレータはデータ ディレクトリ ~/.config/gcloud/emulators/datastore/ を使用します。local_db.bin ファイルは、エミュレータのセッションを通じて継続します。複数のデータ ディレクトリを設定し、それぞれを別々のローカル Datastore モードのインスタンスとして扱うことができます。local_db.bin ファイルの内容をクリアするには、エミュレータを停止して、ファイルを手動で削除します。

エミュレータの開始

コマンド プロンプトで datastore start を実行してエミュレータを起動します。

gcloud emulators datastore start [flags]

ここで、[flags] は gcloud CLI に渡されるオプションのコマンドライン引数です。次に例を示します。

  • --data-dir=[DATA_DIR] で、エミュレータのデータ ディレクトリを変更します。エミュレータは、[DATA_DIR] の内部に /WEB-INF/appengine-generated/local_db.bin ファイルを作成するか、既存のファイルが使用可能な場合にはそれを使用します。

  • --no-store-on-disk で、エミュレータ セッション用のデータをディスクに残さないようにエミュレータを構成します。

オプション フラグの一覧については、gcloud beta emulators datastore start のリファレンスをご覧ください。

エミュレータを開始すると、次のようなメッセージが表示されます。

...
[datastore] Dev App Server is now running.

エミュレータを停止するには、コマンド プロンプトで Ctrl+C を入力します。

環境変数の設定

エミュレータを開始したら、アプリケーションが本番環境用の Datastore モードのデータベースではなくエミュレータに接続するように環境変数を設定する必要があります。これらの環境変数は、アプリケーションの実行に使用するものと同じマシン上で設定します。

環境変数はエミュレータを開始するたびに設定する必要があります。環境変数は、動的に割り当てられるポート番号に依存しています。この番号は、エミュレータを再起動するたびに変わる可能性があります。

変数の自動設定

アプリケーションとエミュレータが同じマシン上で動作している場合は、次のようにして環境変数を自動的に設定できます。

Linux / macOS

コマンド代入を使用して env-init を実行します。

$(gcloud beta emulators datastore env-init)

Windows

env-init からの出力を使用してバッチファイルを作成、実行します。

gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd

これで、アプリケーションが Datastore エミュレータに接続します。

変数の手動設定

アプリケーションとエミュレータが別々のマシン上で動作している場合は、次のようにして環境変数を手動で設定します。

  1. env-init コマンドを実行します。

    gcloud beta emulators datastore env-init
  2. アプリケーションを実行するマシンで、env-init コマンドの出力結果に基づいて環境変数と値を設定します。例:

    Linux / macOS
    export DATASTORE_DATASET=my-project-id
    export DATASTORE_EMULATOR_HOST=::1:8432
    export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
    export DATASTORE_HOST=http://::1:8432
    export DATASTORE_PROJECT_ID=my-project-id
    Windows
    set DATASTORE_DATASET=my-project-id
    set DATASTORE_EMULATOR_HOST=::1:8432
    set DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
    set DATASTORE_HOST=http://::1:8432
    set DATASTORE_PROJECT_ID=my-project-id

これで、アプリケーションが Datastore エミュレータに接続します。 コマンドで提供されるプロジェクト ID とポートは、上記の例とは異なることに注意してください。

インデックスの更新と削除

エミュレータを使用してアプリケーションを実行すると、本番環境用の Datastore モード データベースのインデックスを生成でき、不要なインデックスを削除することもできます。詳細については、gcloud CLI の使用をご覧ください。

環境変数の削除

エミュレータの使用が終わったら、アプリケーションが本番環境用の Datastore モード データベースに接続するように、エミュレータを停止して(Ctrl+C)、環境変数を削除します。

変数の自動削除

アプリケーションとエミュレータが同じマシン上で動作している場合は、次のようにして環境変数を自動的に削除できます。

Linux / macOS

コマンド代入を使用して env-unset を実行します。

$(gcloud beta emulators datastore env-unset)

Windows

env-unset からの出力を使用してバッチファイルを作成、実行します。

gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd

これで、アプリケーションが本番環境用の Datastore モード データベースに接続するようになります。

変数の手動削除

アプリケーションとエミュレータが別々のマシン上で動作している場合は、次のようにして環境変数を手動で削除します。

  1. env-unset コマンドを実行します。

    gcloud beta emulators datastore env-unset
  2. アプリケーションを実行するマシンで、env-unset コマンドの出力結果に基づいて環境変数を削除します。例:

    Linux / macOS
    unset DATASTORE_DATASET
    unset DATASTORE_EMULATOR_HOST
    unset DATASTORE_EMULATOR_HOST_PATH
    unset DATASTORE_HOST
    unset DATASTORE_PROJECT_ID
    Windows
    set DATASTORE_DATASET=
    set DATASTORE_EMULATOR_HOST=
    set DATASTORE_EMULATOR_HOST_PATH=
    set DATASTORE_HOST=
    set DATASTORE_PROJECT_ID=

これで、アプリケーションが本番環境用の Datastore モード データベースに接続するようになります。