Testar o modo Datastore usando o emulador do Firestore

A Google Cloud CLI oferece um emulador local na memória para o Firestore, que pode ser usado para testar o aplicativo do Firestore no modo Datastore. Você pode usar o emulador com todas as bibliotecas de cliente do modo Datastore. Use o emulador apenas para testes locais.

Use gcloud emulators firestore com --database-mode=datastore-mode para testar o comportamento do Firestore no modo Datastore.

Não use o emulador para implantações de produção. Como o emulador armazena dados apenas na memória, ele não mantém os dados nas execuções.

Instalar o emulador

Para instalar o emulador do Firestore, instale e atualize a CLI gcloud:

  1. Instale a CLI gcloud.

  2. Atualize a instalação da CLI gcloud para receber os recursos mais recentes:

    gcloud components update

Executar o emulador

  1. Execute o seguinte comando para iniciar o emulador:

    gcloud emulators firestore start --database-mode=datastore-mode

    O emulador imprime o host e o número da porta em que está sendo executado.

    Por padrão, o emulador tenta usar 127.0.0.1:8080. Para vincular o emulador a um host e uma porta específicos, use a flag opcional --host-port, substituindo HOST e PORT:

    gcloud emulators firestore start --database-mode=datastore-mode --host-port=HOST:PORT

  2. Use o atalho de teclado Control + C para interromper o emulador.

Conectar-se ao emulador

Para conectar uma biblioteca de cliente e um app ao emulador, defina a variável de ambiente DATASTORE_EMULATOR_HOST. Quando essa variável de ambiente é definida, as bibliotecas de cliente se conectam automaticamente ao emulador.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Importar entidades para o emulador

O recurso de importação do emulador permite carregar entidades de um conjunto de arquivos de exportação da entidade no emulador. Os arquivos de exportação da entidade podem ser provenientes de uma exportação do banco de dados do modo Datastore ou de uma instância do emulador.

É possível importar entidades para o emulador de duas maneiras. A primeira é adicionar a flag import-data ao comando de inicialização do emulador. O segundo método é enviar uma solicitação de importação POST ao emulador. Use curl ou uma ferramenta semelhante. Consulte os exemplos a seguir.

Protocolo

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:import \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE", "export_directory":"EXPORT_DIRECTORY"}'
Modifique localhost:8080 se o emulador usar uma porta diferente.

Flag da CLI

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY

em que:

  • [PROJECT_ID] é o ID do projeto;

  • [DATABASE] é o caminho do banco de dados. Por exemplo, um projeto com o banco de dados padrão seria assim:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] é o caminho para o arquivo overall_export_metadata dos seus arquivos de exportação de entidade. Exemplo:

    {"export_directory":"/home/user/myexports/2024-03-26T19:39:33_443/2024-03-26T19:39:33_443.overall_export_metadata"}

Exportar entidades no emulador

O recurso de exportação do emulador permite salvar entidades no emulador em um conjunto de arquivos de exportação da entidade. Em seguida, use uma operação de importação para carregar as entidades nos arquivos de exportação da entidade no banco de dados do modo Datastore ou em uma instância do emulador.

É possível exportar entidades do emulador de duas maneiras. A primeira é adicionar a flag export-on-exit ao comando de inicialização do emulador. O segundo método é enviar uma solicitação de exportação POST ao emulador. Use curl ou uma ferramenta semelhante. Consulte os exemplos a seguir.

Protocolo

curl -X POST http://localhost:8080/emulator/v1/projects/PROJECT_ID:export \
-H 'Content-Type: application/json' \
-d '{"database":"DATABASE_PATH", "export_directory":"EXPORT_DIRECTORY"}'
Modifique localhost:8080 se o emulador usar uma porta diferente.

Flag da CLI

gcloud emulators firestore start --database-mode=datastore-mode --export-on-exit=EXPORT_DIRECTORY

em que:

  • [PROJECT_ID] é o ID do projeto;

  • [DATABASE_PATH] é o caminho do banco de dados. Por exemplo, um projeto com o banco de dados padrão seria assim:

    {"database":"projects/myProject/databases/"}

  • [EXPORT_DIRECTORY] especifica o diretório em que o emulador salvará os arquivos de exportação da entidade. Esse diretório não pode conter um conjunto de arquivos de exportação da entidade. Exemplo:

    {"export_directory":"/home/user/myexports/2024-03-26/"}

Persistir dados no emulador

Por padrão, o emulador do Firestore não mantém os dados no disco. Para manter os dados do emulador, execute o comando a seguir para usar flags de importação e exportação para carregar e salvar os dados em instâncias do emulador:

gcloud emulators firestore start --database-mode=datastore-mode --import-data=EXPORT_DIRECTORY --export-on-exit=EXPORT_DIRECTORY

Redefinir dados do emulador

O emulador do Firestore inclui um endpoint REST para redefinir todos os dados no emulador. Você pode usar esse endpoint para limpar dados entre testes sem desligar o emulador.

Para redefinir todos os dados no emulador, execute uma operação HTTP POST no endpoint a seguir, substituindo HOST e PORT pelo host e pela porta selecionados e PROJECT_ID pelo ID do projeto:

http://HOST:PORT/reset

Ajuste o host e a porta se o emulador não usar 127.0.0.1:8080. O código precisa aguardar a confirmação REST de que a redefinição foi concluída ou falhou.

Você pode executar essa operação no shell usando curl:

$ curl -X POST "http://HOST:PORT/reset"

Qual é a diferença entre o emulador do e a produção?

O emulador tenta replicar fielmente o comportamento do serviço de produção, com algumas limitações notáveis.

Concorrência e consistência

O emulador oferece suporte apenas à concorrência pessimista e à consistência forte. O emulador não oferece suporte à concorrência otimista e às configurações de consistência posterior.

Transações

O emulador não tenta imitar o comportamento de transação visto na produção. Ele usa uma abordagem de bloqueio simples e não tenta espelhar os vários modos de simultaneidade oferecidos no ambiente de produção.

Quando você está testando recursos que envolvem várias gravações simultâneas em um documento, o emulador pode demorar para concluir solicitações de gravação. Pode levar até 30 segundos para o emulador liberar os bloqueios. Se você precisar ajustar os intervalos de tempo limite do teste, faça isso.

O emulador também não tenta imitar todos os limites de produção, como tempos limite e limites de tamanho, que envolvem transações. Se você testar recursos que dependem desses limites de produção, recomendamos que use um ambiente de produção em vez de um emulador.

Índices

Por padrão, o emulador não rastreia índices compostos. Em vez disso, ele executa consultas válidas.

Para testar se os requisitos de índice composto são atendidos, inicie o emulador com as flags --require-indexes e --index-file. Quando você inicia o emulador com essas flags, ele verifica e rejeita consultas que exigem um índice composto que não está definido no arquivo de índice especificado.

gcloud emulators firestore start --database-mode=datastore-mode --require-indexes --index-file=./index.yaml

Consulte Configurar índices do Datastore com index.yaml para mais informações sobre o formato index-file.

Limites

O emulador não impõe todos os limites aplicados na produção. Por exemplo, o emulador pode permitir transações que são rejeitadas por serem muito grandes pelo serviço de produção. Verifique se você conhece os limites documentados e se desenvolve o app para evitá-los de maneira proativa.

A seguir