Ejecutar el emulador de Datastore

El emulador de Datastore permite la emulación local del entorno de producción de Datastore. Puedes usar el emulador para desarrollar y probar tus aplicaciones de forma local. Además, el emulador puede ayudarte a generar índices para tus instancias de producción de Datastore y borrar los índices que no necesites. Esta página te explicará cómo instalar el emulador, cómo iniciarlo y cómo configurar variables del entorno para que se pueda conectar con tus aplicaciones.

Problemas conocidos

De forma predeterminada, el emulador de Datastore no emula las funciones que presenta Firestore en el modo Datastore. Los siguientes comportamientos predeterminados del emulador no coinciden con el modo Datastore:

  • El emulador simula la coherencia eventual de forma predeterminada. Firestore en modo Datastore tiene coherencia sólida.
  • El emulador no permite consultas no principales dentro de transacciones. Firestore en modo Datastore ya no tiene esta limitación.
  • El emulador no admite consultas IN, != ni NOT-IN.
  • El emulador no admite consultas de agregación como COUNT(*).

Sin embargo, la marca --use-firestore-in-datastore-mode ayuda a disminuir algunas de las restricciones anteriores para Firestore en modo Datastore.

  • El emulador simula consultas no principales de coherencia sólida.
  • El emulador permite consultas no principales dentro de transacciones.
  • El emulador quita la limitación de 25 grupos de entidades en una transacción.

Para emular Firestore en modo Datastore, usa gcloud emulators firestore start --database-mode=datastore-mode.

Antes de comenzar

Para usar el emulador de Datastore, necesitas lo siguiente:

Instala el emulador

El emulador de Datastore es un componente de gcloud CLI. Usa el comando gcloud components install para instalar el emulador de Datastore:

gcloud components install cloud-datastore-emulator

Directorios de datos del emulador

El emulador simula Datastore mediante la creación de /WEB-INF/appengine-generated/local_db.bin en un directorio de datos especificado y el almacenamiento de datos en local_db.bin. De forma predeterminada, el emulador usa el directorio de datos ~/.config/gcloud/emulators/datastore/. El archivo local_db.bin persiste entre las sesiones del emulador. Puedes configurar varios directorios de datos y considerar a cada uno como una instancia independiente y local en modo Datastore. Para borrar el contenido de un archivo local_db.bin, detén el emulador y borra el archivo de forma manual.

Inicia el emulador

Para iniciar el emulador ejecuta datastore start desde el símbolo del sistema:

gcloud emulators datastore start [flags]

En el ejemplo anterior, [flags] son argumentos opcionales de la línea de comandos proporcionados a gcloud CLI. Por ejemplo:

  • --data-dir=[DATA_DIR] cambia el directorio de datos del emulador. El emulador crea el archivo /WEB-INF/appengine-generated/local_db.bin dentro de [DATA_DIR] o, si está disponible, usa un archivo existente.

  • --no-store-on-disk configura el emulador a fin de que no conserve ningún dato en el disco para la sesión del emulador.

Consulta la referencia de gcloud beta emulators datastore start para ver la lista completa de marcas opcionales.

Después de iniciar el emulador, deberías ver un mensaje similar a este:

...
[datastore] Dev App Server is now running.

Para detener el emulador, escribe Control-C en el símbolo del sistema.

Configura variables de entorno

Después de iniciar el emulador, debes establecer variables de entorno para que tu aplicación se conecte a él en lugar de a la base de datos de producción en modo Datastore. Configura estas variables de entorno en la misma máquina que usaste para ejecutar tu aplicación.

Es necesario que configures las variables del entorno cada vez que inicias el emulador. Las variables de entorno dependen de los números de puerto asignados de forma dinámica, que pueden cambiar cuando reinicias el emulador.

Configura las variables de forma automática

Si tu aplicación y el emulador se ejecutan en la misma máquina, puedes configurar las variables del entorno de forma automática:

Linux/macOS

Ejecuta env-init con la sustitución de comandos:

$(gcloud beta emulators datastore env-init)

Windows

Crea y ejecuta un archivo por lotes con el resultado de env-init:

gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd

Tu aplicación se conectará al emulador de Datastore.

Configura las variables de forma manual

Si tu aplicación y el emulador se ejecutan en máquinas diferentes, configura las variables de entorno de forma manual:

  1. Ejecuta el comando env-init:

    gcloud beta emulators datastore env-init

  2. En la máquina que ejecuta tu aplicación, configura las variables de entorno y los valores según lo que indica el resultado del comando env-init. Por ejemplo:

    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

Tu aplicación se conectará al emulador de Datastore. Ten en cuenta que el puerto y el ID del proyecto que proporciona el comando serán distintos a los del ejemplo anterior.

Actualiza y borra índices

Cuando ejecutas tu aplicación con el emulador, puedes generar índices para tu base de datos de producción en modo Datastore, además de borrar índices innecesarios. Obtén más información en Usa gcloud CLI.

Quita variables de entorno

Cuando termines de usar el emulador, detenlo (Control-C) y quita las variables de entorno para que tu aplicación se conecte a tu base de datos de producción en modo Datastore.

Quita las variables de forma automática

Si tu aplicación y el emulador se ejecutan en la misma máquina, puedes quitar las variables del entorno de forma automática:

Linux/macOS

Ejecuta env-unset con la sustitución de comandos:

$(gcloud beta emulators datastore env-unset)

Windows

Crea y ejecuta un archivo por lotes mediante el resultado de env-unset:

gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd

Ahora la aplicación se conectará a la base de datos de producción en modo Datastore.

Quita las variables de forma manual

Si tu aplicación y el emulador se ejecutan en máquinas diferentes, quita las variables de entorno de forma manual:

  1. Ejecuta el comando env-unset:

    gcloud beta emulators datastore env-unset

  2. En la máquina que ejecuta tu aplicación, quita las variables de entorno como lo indica el resultado del comando env-unset. Por ejemplo:

    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=

Ahora la aplicación se conectará a la base de datos de producción en modo Datastore.