Prueba el modo Datastore con el emulador de Firestore

Google Cloud CLI proporciona un emulador local en la memoria para Firestore que puedes usar para probar tu aplicación de Firestore en modo Datastore. Puedes usar el emulador con todas las bibliotecas cliente del modo Datastore. Debes usar el emulador solo para pruebas locales.

Usa gcloud emulators firestore con --database-mode=datastore-mode para probar el comportamiento de Firestore en modo Datastore.

No uses el emulador para implementaciones de producción. No se conservarán los datos de las ejecuciones, dado que el emulador almacena datos solamente en la memoria.

Instala el emulador

Para instalar el emulador de Firestore, instala y actualiza la gcloud CLI:

  1. Instala la CLI de gcloud.

  2. Actualiza tu instalación de gcloud CLI para obtener las funciones más recientes:

    gcloud components update

Ejecuta el emulador

  1. Ejecuta el siguiente comando para iniciar el emulador

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

    El emulador imprime el host y el número de puerto donde se esté ejecutando.

    De forma predeterminada, el emulador intenta usar 127.0.0.1:8080. Para vincular el emulador a un host y puerto específicos, usa la marca opcional --host-port, que reemplaza a HOST y PORT:

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

  2. Usa la combinación de teclas Control + C para detener el emulador.

Cómo conectarse al emulador

Para conectar una biblioteca cliente y una app al emulador, configura la variable de entorno DATASTORE_EMULATOR_HOST. Cuando se establece esta variable de entorno, las bibliotecas cliente se conectan automáticamente al emulador.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Importa entidades al emulador

La función de importación del emulador te permite cargar entidades de un conjunto de archivos de exportación de entidades en el emulador. Los archivos de exportación de entidades pueden provenir de una exportación de tu base de datos en modo Datastore o de una instancia del emulador.

Puedes importar entidades al emulador de dos maneras. El primero es agregar la marca import-data al comando de inicio del emulador. El segundo método es enviar una solicitud de importación POST al emulador. Puedes usar curl o una herramienta similar. Consulta los siguientes ejemplos.

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"}'
Modifica localhost:8080 si el emulador usa un puerto diferente.

Marca de la CLI

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

Donde:

  • [PROJECT_ID] es el ID de tu proyecto.

  • [DATABASE] es la ruta de la base de datos. Por ejemplo, un proyecto con la base de datos predeterminada se vería de la siguiente manera:

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

  • [EXPORT_DIRECTORY] es la ruta de acceso al archivo overall_export_metadata de los archivos de exportación de tu entidad. Por ejemplo:

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

Exporta entidades en el emulador

La función de exportación del emulador te permite guardar entidades en el emulador en un conjunto de archivos de exportación de entidades. Puedes usar una operación de importación para cargar las entidades en los archivos de exportación de entidades en tu base de datos en modo Datastore o en una instancia del emulador.

Puedes exportar entidades desde el emulador de dos maneras. El primero es agregar la marca export-on-exit a tu comando de inicio del emulador. El segundo método es enviar una solicitud de exportación POST al emulador. Puedes usar curl o una herramienta similar. Consulta los siguientes ejemplos.

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"}'
Modifica localhost:8080 si el emulador usa un puerto diferente.

Marca de la CLI

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

Donde:

  • [PROJECT_ID] es el ID de tu proyecto.

  • [DATABASE_PATH] es la ruta de la base de datos. Por ejemplo, un proyecto con la base de datos predeterminada se vería de la siguiente manera:

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

  • [EXPORT_DIRECTORY] especifica el directorio en el que el emulador guarda los archivos de exportación de entidades. Este directorio no debe contener otro conjunto de archivos de exportación de entidades. Por ejemplo:

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

Cómo conservar datos en el emulador

De forma predeterminada, el emulador de Firestore no conserva datos en el disco. Para conservar los datos del emulador, ejecuta el siguiente comando para usar marcas de importación y exportación para cargar y guardar los datos en todas las instancias del emulador:

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

Restablece los datos del emulador

El emulador de Firestore incluye un extremo de REST para restablecer todos los datos del emulador. Puedes usar este extremo para borrar datos entre pruebas sin cerrar el emulador.

Para restablecer todos los datos del emulador, realiza una operación HTTP POST en el siguiente extremo, reemplaza HOST y PORT por el host y el puerto que seleccionaste, y reemplaza PROJECT_ID por tu propio ID del proyecto:

http://HOST:PORT/reset

Ajusta el host y el puerto si el emulador no usa 127.0.0.1:8080. Tu código debe esperar la confirmación de REST de que el restablecimiento finalizó o falló.

Puedes realizar esta operación desde la shell con curl:

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

Diferencias entre el emulador y el entorno de producción

El emulador intenta replicar de la mejor manera posible el comportamiento del servicio de producción, salvo las excepciones que se indican a continuación.

Simultaneidad y coherencia

El emulador solo admite concurrencia pesimista y coherencia estricta. El emulador no admite la configuración de simultaneidad optimista ni de coherencia eventual.

Transacciones

El emulador no implementa todos los comportamientos de transacciones que se ven en producción. Cuando pruebas funciones que implican varias escrituras simultáneas en un documento, es posible que el emulador tarde en completar las solicitudes de escritura. En algunos casos, los bloqueos pueden tardar hasta 30 segundos en liberarse. Te recomendamos ajustar los tiempos de espera de la prueba según sea necesario.

Índices

El emulador no realiza un seguimiento de los índices compuestos y, en su lugar, ejecuta cualquier consulta válida. Asegúrate de probar tu app en una instancia real del modo Datastore para determinar qué índices necesitas.

Límites

El emulador no aplica todos los límites que se implementan en producción. Por ejemplo, es posible que el emulador permita transacciones que el servicio de producción rechazaría debido a su gran tamaño. Asegúrate de conocer los límites documentados y de diseñar tu app para evitarlos de forma proactiva.

¿Qué sigue?