Teste o modo Datastore com o emulador do Firestore

A CLI do Google Cloud oferece um emulador local na memória para o Firestore que pode usar para testar a sua aplicação do Firestore no modo Datastore. Pode usar o emulador com todas as bibliotecas cliente do modo Datastore. Deve usar o emulador apenas para testes locais.

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

Não use o emulador para implementações de produção. Uma vez que o emulador armazena dados apenas na memória, não mantém os dados entre execuções.

Instale 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 as funcionalidades mais recentes:

    gcloud components update

Execute o emulador

  1. Execute o seguinte comando para iniciar o emulador:

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

    O emulador imprime o anfitrião e o número da porta onde está a ser executado.

    Por predefinição, o emulador tenta usar 127.0.0.1:8080. Para associar o emulador a um anfitrião e uma porta específicos, use a flag --host-port opcional, 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 parar o emulador.

Estabeleça ligação ao emulador

Para ligar uma biblioteca cliente e uma app ao emulador, defina a variável de ambiente DATASTORE_EMULATOR_HOST. Quando esta variável de ambiente está definida, as bibliotecas de cliente ligam-se automaticamente ao emulador.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Importe entidades para o emulador

A funcionalidade de importação do emulador permite-lhe carregar entidades a partir de um conjunto de ficheiros de exportação de entidades para o emulador. Os ficheiros de exportação de entidades podem ser provenientes de uma exportação da base de dados do modo Datastore ou de uma instância do emulador.

Pode importar entidades para o emulador de duas formas. A primeira é adicionar a flag import-data ao comando de início do emulador. O segundo método consiste em enviar um pedido de importação POST para o emulador. Pode usar o comando curl ou uma ferramenta semelhante. Consulte os seguintes exemplos.

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.

Sinalização da CLI

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

where:

  • [PROJECT_ID] é o ID do seu projeto.

  • [DATABASE] é o caminho da base de dados. Por exemplo, um projeto com uma base de dados predefinida teria o seguinte aspeto:

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

  • [EXPORT_DIRECTORY] é o caminho para o ficheiro overall_export_metadata dos seus ficheiros de exportação de entidades. Por exemplo:

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

Exporte entidades no emulador

A funcionalidade de exportação do emulador permite-lhe guardar entidades no emulador num conjunto de ficheiros de exportação de entidades. Em seguida, pode usar uma operação de importação para carregar as entidades nos ficheiros de exportação de entidades para a base de dados do modo Datastore ou para uma instância do emulador.

Pode exportar entidades do emulador de duas formas. A primeira é adicionar a flag export-on-exit ao comando de início do emulador. O segundo método consiste em enviar um pedido de exportação POST para o emulador. Pode usar o comando curl ou uma ferramenta semelhante. Consulte os seguintes exemplos.

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.

Sinalização da CLI

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

where:

  • [PROJECT_ID] é o ID do seu projeto.

  • [DATABASE_PATH] é o caminho da base de dados. Por exemplo, um projeto com uma base de dados predefinida teria o seguinte aspeto:

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

  • [EXPORT_DIRECTORY] especifica o diretório onde o emulador guarda os ficheiros de exportação de entidades. Este diretório não pode conter já um conjunto de ficheiros de exportação de entidades. Por exemplo:

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

Persista os dados no emulador

Por predefinição, o emulador do Firestore não persiste os dados no disco. Para persistir os dados do emulador, execute o seguinte comando para usar as flags de importação e exportação para carregar e guardar os dados em instâncias do emulador:

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

Reponha os dados do emulador

O emulador do Firestore inclui um ponto final REST para repor todos os dados no emulador. Pode usar este ponto final para limpar dados entre testes sem encerrar o emulador.

Para repor todos os dados no emulador, execute uma operação HTTP POST no seguinte ponto final, substituindo HOST e PORT pelo anfitrião e pela porta que selecionou, e substituindo PROJECT_ID pelo seu próprio ID do projeto:

http://HOST:PORT/reset

Ajuste o anfitrião e a porta se o emulador não usar 127.0.0.1:8080. O seu código deve aguardar a confirmação REST de que a reposição terminou ou falhou.

Pode realizar esta operação a partir da shell com curl:

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

Como o emulador difere da produção

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

Simultaneidade e consistência

O emulador suporta apenas a concorrência pessimista e a consistência forte. O emulador não suporta definições de simultaneidade otimista e consistência eventual.

Transações

O emulador não tenta imitar o comportamento das transações observado na produção. Usa uma abordagem de bloqueio simples e não tenta replicar os vários modos de simultaneidade oferecidos no ambiente de produção.

Quando estiver a testar funcionalidades que envolvem várias escritas simultâneas num documento, o emulador pode demorar a concluir os pedidos de escrita. O emulador pode demorar até 30 segundos a libertar os bloqueios. Se precisar de ajustar os intervalos de tempo limite do teste, faça-o.

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

Índices

O emulador não acompanha os índices compostos e, em vez disso, executa qualquer consulta válida. Certifique-se de que testa a sua app com uma instância real do modo Datastore para determinar os índices de que precisa.

Limites

O emulador não aplica todos os limites aplicados na produção. Por exemplo, o emulador pode permitir transações que seriam rejeitadas como demasiado grandes pelo serviço de produção. Certifique-se de que conhece os limites documentados e que cria a sua app para os evitar proativamente.

O que se segue?