Probar el modo Datastore con el emulador de Firestore

La CLI de Google Cloud proporciona un emulador local en memoria de Firestore que puedes usar para probar tu aplicación de Firestore en el modo de Datastore. Puedes usar el emulador con todas las bibliotecas de cliente del modo Datastore. Solo debes usar el emulador para hacer 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 las implementaciones de producción. Como el emulador solo almacena datos en la memoria, no conserva los datos entre ejecuciones.

Instalar el emulador

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

  1. Instala gcloud CLI.

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

    gcloud components update

Ejecutar el emulador

  1. Ejecuta el siguiente comando para iniciar el emulador:

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

    El emulador muestra el host y el número de puerto en los que se está ejecutando.

    De forma predeterminada, el emulador intenta usar 127.0.0.1:8080. Para vincular el emulador a un host y un puerto específicos, usa la marca opcional --host-port y sustituye 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.

Conectarse al emulador

Para conectar una biblioteca de cliente y una aplicación al emulador, define la variable de entorno DATASTORE_EMULATOR_HOST. Cuando se define esta variable de entorno, las bibliotecas de cliente se conectan automáticamente al emulador.

export DATASTORE_EMULATOR_HOST="HOST:PORT"

Importar 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 proceder de una exportación de tu base de datos en modo Datastore o de una instancia de emulador.

Puedes importar entidades al emulador de dos formas. La primera es añadir la marca import-data al comando de inicio del emulador. El segundo método consiste en 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 otro puerto.

Marca de 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 una base de datos predeterminada tendría el siguiente aspecto:

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

  • [EXPORT_DIRECTORY] es la ruta 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"}

Exportar entidades en el emulador

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

Puedes exportar entidades del emulador de dos formas. La primera es añadir la marca export-on-exit al comando de inicio del emulador. El segundo método consiste en 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 otro puerto.

Marca de 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 una base de datos predeterminada tendría el siguiente aspecto:

    {"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 ya un conjunto de archivos de exportación de entidades. Por ejemplo:

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

Conservar los datos en el emulador

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

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

Borrar datos del emulador

El emulador de Firestore incluye un endpoint REST para restablecer todos los datos del emulador. Puedes usar este endpoint 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 endpoint. Sustituye HOST y PORT por el host y el puerto que hayas seleccionado, y PROJECT_ID por tu ID de 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 se ha completado o ha fallado.

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

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

Diferencias entre el emulador y la producción

El emulador intenta replicar fielmente el comportamiento del servicio de producción, pero tiene algunas limitaciones importantes.

Simultaneidad y coherencia

El emulador solo admite la simultaneidad pesimista y la coherencia fuerte. El emulador no admite la configuración de concurrencia optimista y coherencia final.

Transacciones

El emulador no intenta imitar el comportamiento de las transacciones que se observa en producción. Utiliza un enfoque de bloqueo sencillo y no intenta reflejar los distintos modos de simultaneidad que se ofrecen en el entorno de producción.

Cuando pruebes funciones que impliquen varias escrituras simultáneas en un documento, es posible que el emulador tarde en completar las solicitudes de escritura. El emulador puede tardar hasta 30 segundos en liberar los bloqueos. Si necesitas ajustar los intervalos de tiempo de espera de la prueba, hazlo.

El emulador tampoco intenta imitar todos los límites de producción, como los límites de tiempo de espera y de tamaño, que implican transacciones. Si pruebas funciones que dependen de estos límites de producción, te recomendamos que utilices un entorno de producción en lugar de un emulador.

Índices

El emulador no monitoriza los índices compuestos, sino que ejecuta cualquier consulta válida. Asegúrate de probar tu aplicación con una instancia real del modo Datastore para determinar qué índices necesitas.

Límites

El emulador no aplica todos los límites que se aplican en producción. Por ejemplo, el emulador puede permitir transacciones que el servicio de producción rechazaría por ser demasiado grandes. Familiarízate con los límites documentados y diseña tu aplicación para evitarlos de forma proactiva.

Siguientes pasos