O emulador do Datastore fornece a emulação local do ambiente de produção do Datastore. Use o emulador para desenvolver e testar seu aplicativo localmente. Além disso, com o emulador, é possível gerar índices para a instância de produção do Datastore e excluir índices desnecessários. Nesta página, são demonstradas a instalação e a execução do emulador, bem como a definição de variáveis de ambiente para conectar seu aplicativo ao emulador.
Problemas conhecidos
O emulador do Datastore não emula recursos introduzidos pelo Firestore no modo Datastore. Os comportamentos do emulador a seguir não correspondem ao modo Datastore:
- Por padrão, o emulador simula a consistência posterior. O Firestore no modo Datastore é altamente consistente.
- O emulador não permite consultas não ancestrais dentro de transações. O Firestore no modo Datastore não tem mais essa limitação.
Antes de começar
Para usar o emulador do Datastore, serão necessários:
- um JRE Java, versão 8 ou superior;
- A Google Cloud CLI
- um aplicativo criado com Bibliotecas de cliente do Google Cloud.
Instalação do emulador
O emulador do Datastore é um componente da CLI gcloud da
CLI do Google Cloud. 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 em um diretório de dados especificado e armazenando dados em local_db.bin. Por padrão, o emulador usa o diretório de dados ~/.config/gcloud/emulators/datastore/.
O arquivo local_db.bin persiste entre as sessões do emulador. Configure vários diretórios de dados e pense em cada um como uma instância local separada do Datastore. Para limpar o conteúdo de um arquivo local_db.bin, interrompa o emulador e exclua o arquivo manualmente.
Iniciar o emulador
Para iniciar o emulador, execute datastore start em um prompt de comando:
gcloud beta emulators datastore start [flags]
em que [flags] são argumentos de linha de comando opcionais fornecidos para a
CLI gcloud. Exemplo:
--data-dir=[DATA_DIR]altera o diretório de dados do emulador. O emulador cria o arquivo/WEB-INF/appengine-generated/local_db.bindentro de[DATA_DIR]ou, se disponível, usa um arquivo existente.--no-store-on-diskconfigura o emulador para que nenhum dado permaneça em disco na sessão.
Veja a lista completa de sinalizações opcionais na referência gcloud beta emulators datastore start.
Depois de o emulador ser iniciado, uma mensagem semelhante à seguinte será exibida:
...
[datastore] Dev App Server is now running.
Se quiser parar o emulador, digite Control-C no prompt de comando.
Como definir variáveis de ambiente
Depois de iniciar o emulador, é necessário definir variáveis de ambiente para que o aplicativo se conecte ao emulador em vez de ao banco de dados de produção do modo Datastore. Defina essas variáveis de ambiente na mesma máquina usada para executar o aplicativo.
Defina as variáveis de ambiente sempre que iniciar o emulador. As variáveis de ambiente dependem de números de portas atribuídos dinamicamente que podem ser alterados ao reiniciar o emulador.
Como definir automaticamente as variáveis
Se o aplicativo e o emulador forem executados na mesma máquina, defina as variáveis de ambiente automaticamente:
Linux/macOS
Execute env-init usando a substituição de comando:
$(gcloud beta emulators datastore env-init)
Windows
Crie e execute um arquivo de lote usando a saída de env-init:
gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd
Agora seu aplicativo se conectará ao emulador do Datastore.
Como definir manualmente as variáveis
Se o aplicativo e o emulador forem executados em máquinas diferentes, configure as variáveis de ambiente manualmente:
Execute o comando
env-init:gcloud beta emulators datastore env-init
Na máquina que executa o aplicativo, defina os valores e as variáveis de ambiente conforme indicado pela saída do comando
env-init. 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
Agora seu aplicativo se conectará ao emulador do Datastore. O ID do projeto e a porta fornecidos pelo comando serão diferentes do exemplo acima.
Atualizar e excluir índices
Ao executar o aplicativo pelo emulador, é possível gerar índices para a produção do Datastore e excluir os índices desnecessários. Saiba mais em Como usar a CLI gcloud.
Como remover variáveis de ambiente
Depois de usar o emulador, interrompa-o (Control-C) e remova as variáveis de ambiente para que seu aplicativo se conecte à produção do Datastore.
Como remover as variáveis automaticamente
Se o aplicativo e o emulador forem executados na mesma máquina, será possível remover as variáveis de ambiente automaticamente:
Linux/macOS
Execute env-unset usando a substituição de comando:
$(gcloud beta emulators datastore env-unset)
Windows
Crie e execute um arquivo de lote usando a saída de env-unset:
gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd
Agora o aplicativo se conectará ao banco de dados de produção do modo Datastore.
Como remover as variáveis manualmente
Se o aplicativo e o emulador forem executados em máquinas diferentes, remova as variáveis de ambiente manualmente:
Execute o comando
env-unset:gcloud beta emulators datastore env-unset
Na máquina que executa o aplicativo, remova as variáveis de ambiente conforme indicado pela saída do comando
env-unset. 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=
Agora o aplicativo se conectará ao banco de dados de produção do modo Datastore.