Executar o emulador do Datastore

O emulador do Datastore oferece uma emulação local do ambiente de produção do Datastore. Pode usar o emulador para desenvolver e testar a sua aplicação localmente. Além disso, o emulador pode ajudar a gerar índices para a sua instância de produção do Datastore e eliminar índices desnecessários. Esta página explica como instalar o emulador, iniciar o emulador e definir variáveis de ambiente para associar a sua aplicação ao emulador.

Problemas conhecidos

Por predefinição, o emulador do Datastore não emula as funcionalidades introduzidas pelo Firestore no modo Datastore. Os seguintes comportamentos do emulador predefinidos não correspondem ao modo Datastore:

  • Por predefinição, o emulador simula a consistência eventual. O Firestore no modo Datastore é fortemente consistente.
  • O emulador não permite consultas não descendentes em transações. O Firestore no modo Datastore já não tem esta limitação.
  • O emulador não suporta consultas IN, != e NOT-IN.
  • O emulador não suporta consultas de agregação, como COUNT(*).

No entanto, a flag --use-firestore-in-datastore-mode ajuda a flexibilizar algumas das restrições acima para o Firestore no modo Datastore.

  • O emulador simula consultas não descendentes fortemente consistentes.
  • O emulador permite consultas não descendentes em transações.
  • O emulador remove a limitação de 25 grupos de entidades numa transação.

Para emular o Firestore no modo Datastore, use gcloud emulators firestore start --database-mode=datastore-mode em alternativa.

Antes de começar

Para usar o emulador do Datastore, precisa do seguinte:

Instalar o emulador

O emulador do Datastore é um componente da CLI gcloud. Use o comando gcloud components install para instalar o emulador do Datastore:

gcloud components install cloud-datastore-emulator

Diretórios de dados do emulador

O emulador simula o Datastore criando /WEB-INF/appengine-generated/local_db.bin num diretório de dados especificado e armazenando dados em local_db.bin. Por predefinição, o emulador usa o diretório de dados ~/.config/gcloud/emulators/datastore/. O ficheiro local_db.bin persiste entre sessões do emulador. Pode configurar vários diretórios de dados e considerar cada um como uma instância do modo Datastore local separada. Para limpar o conteúdo de um ficheiro, pare o emulador e elimine o ficheiro manualmente.local_db.bin

A iniciar o emulador

Inicie o emulador executando datastore start numa linha de comandos:

gcloud beta emulators datastore start [flags]

onde [flags] são argumentos opcionais da linha de comandos fornecidos à CLI gcloud. Por exemplo:

  • --data-dir=[DATA_DIR] altera o diretório de dados do emulador. O emulador cria o ficheiro /WEB-INF/appengine-generated/local_db.bin em [DATA_DIR] ou, se estiver disponível, usa um ficheiro existente.

  • --no-store-on-disk configura o emulador para não persistir dados no disco para a sessão do emulador.

Consulte a referência gcloud beta emulators datastore start para ver a lista completa de flags opcionais.

Depois de iniciar o emulador, deve ver uma mensagem semelhante à seguinte:

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

Para parar o emulador, escreva Control-C na linha de comandos.

Definir variáveis de ambiente

Depois de iniciar o emulador, tem de definir variáveis de ambiente para que a sua aplicação se ligue ao emulador em vez da base de dados do modo Datastore de produção. Defina estas variáveis de ambiente na mesma máquina que usa para executar a sua aplicação.

Tem de definir as variáveis de ambiente sempre que iniciar o emulador. As variáveis de ambiente dependem dos números de porta atribuídos dinamicamente que podem mudar quando reinicia o emulador.

Definir automaticamente as variáveis

Se a sua aplicação e o emulador forem executados na mesma máquina, pode definir as variáveis de ambiente automaticamente:

Linux / macOS

Execute env-init através da substituição de comandos:

$(gcloud beta emulators datastore env-init)

Windows

Crie e execute um ficheiro de comandos usando o resultado de env-init:

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

A sua aplicação vai agora estabelecer ligação ao emulador do Datastore.

Definir manualmente as variáveis

Se a sua aplicação e o emulador forem executados em máquinas diferentes, defina as variáveis de ambiente manualmente:

  1. Execute o comando env-init:

    gcloud beta emulators datastore env-init

  2. Na máquina que executa a sua aplicação, defina as variáveis de ambiente e os valores conforme indicado pela saída do comando env-init. Por exemplo:

    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

A sua aplicação vai agora estabelecer ligação ao emulador do Datastore. Tenha em atenção que o ID do projeto e a porta fornecidos pelo comando vão diferir do exemplo acima.

Atualizar e eliminar índices

Ao executar a sua aplicação através do emulador, pode gerar índices para a base de dados do modo Datastore de produção, bem como eliminar índices desnecessários. Saiba mais em Usar a CLI gcloud.

Remover variáveis de ambiente

Depois de terminar de usar o emulador, pare-o (Control-C) e remova as variáveis de ambiente para que a sua aplicação se ligue à base de dados do modo Datastore de produção.

Remover automaticamente as variáveis

Se a sua aplicação e o emulador forem executados na mesma máquina, pode remover as variáveis de ambiente automaticamente:

Linux / macOS

Execute env-unset através da substituição de comandos:

$(gcloud beta emulators datastore env-unset)

Windows

Crie e execute um ficheiro de comandos usando o resultado de env-unset:

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

A sua aplicação vai agora estabelecer ligação à base de dados do modo Datastore de produção.

Remover manualmente as variáveis

Se a sua aplicação e o emulador forem executados em máquinas diferentes, remova as variáveis de ambiente manualmente:

  1. Execute o comando env-unset:

    gcloud beta emulators datastore env-unset

  2. Na máquina que executa a sua aplicação, remova as variáveis de ambiente conforme indicado no resultado do comando env-unset. Por exemplo:

    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=

A sua aplicação vai agora estabelecer ligação à base de dados do modo Datastore de produção.