Ejecutar el emulador de Datastore

.

El emulador de Datastore ofrece una emulación local del entorno de producción de Datastore. Puedes usar el emulador para desarrollar y probar tu aplicación localmente. Además, el emulador puede ayudarte a generar índices para tu instancia de producción de Datastore y a eliminar los que no necesites. En esta página se explica cómo instalar el emulador, iniciarlo y definir variables de entorno para conectar tu aplicación con el emulador.

Problemas conocidos

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

  • El emulador simula la coherencia final de forma predeterminada. Firestore en modo Datastore tiene una coherencia inmediata.
  • El emulador no permite consultas que no sean de ancestros en las 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 flexibilizar algunas de las restricciones anteriores para Firestore en el modo Datastore.

  • El emulador simula consultas de no ancestros con coherencia inmediata.
  • El emulador permite realizar consultas que no son de ancestros en las transacciones.
  • El emulador elimina 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 en su lugar.

Antes de empezar

Para usar el emulador de Datastore, necesitas lo siguiente:

Instalar el emulador

El emulador de Datastore es un componente de la CLI de gcloud. 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 creando /WEB-INF/appengine-generated/local_db.bin en un directorio de datos especificado y almacenando datos en local_db.bin. De forma predeterminada, el emulador usa el directorio de datos ~/.config/gcloud/emulators/datastore/. El archivo local_db.bin se mantiene entre las sesiones del emulador. Puedes configurar varios directorios de datos y considerar cada uno de ellos como una instancia independiente del modo Datastore local. Para borrar el contenido de un archivo local_db.bin, detén el emulador y elimina el archivo manualmente.

Iniciar el emulador

Inicia el emulador ejecutando datastore start desde un símbolo del sistema:

gcloud beta emulators datastore start [flags]

donde [flags] son argumentos opcionales de la línea de comandos que se proporcionan a la CLI de gcloud. 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 en [DATA_DIR] o, si está disponible, usa un archivo que ya exista.

  • --no-store-on-disk configura el emulador para que no conserve ningún dato en el disco durante 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ía ver un mensaje similar al siguiente:

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

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

Configurar variables de entorno

Después de iniciar el emulador, debe definir variables de entorno para que su aplicación se conecte al emulador en lugar de a su base de datos en modo Datastore de producción. Define estas variables de entorno en la misma máquina que usas para ejecutar tu aplicación.

Debes definir las variables de entorno cada vez que inicies el emulador. Las variables de entorno dependen de los números de puerto asignados dinámicamente, que pueden cambiar cuando reinicies el emulador.

Definir las variables automáticamente

Si tu aplicación y el emulador se ejecutan en el mismo ordenador, puedes definir las variables de entorno automáticamente:

Linux o macOS

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

$(gcloud beta emulators datastore env-init)

Windows

Crea y ejecuta un archivo por lotes con la salida de env-init:

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

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

Definir las variables manualmente

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

  1. Ejecuta el comando env-init:

    gcloud beta emulators datastore env-init

  2. En la máquina que ejecuta tu aplicación, define las variables de entorno y los valores tal como se indica en el resultado del comando env-init. Por ejemplo:

    Linux o 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 ID del proyecto y el puerto que proporciona el comando serán diferentes de los del ejemplo anterior.

Actualizar y eliminar índices

Si ejecutas tu aplicación con el emulador, puedes generar índices para tu base de datos en modo Datastore de producción, así como eliminar los índices que no necesites. Consulta más información en el artículo Usar gcloud CLI.

Eliminar variables de entorno

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

Eliminar las variables automáticamente

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

Linux o macOS

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

$(gcloud beta emulators datastore env-unset)

Windows

Crea y ejecuta un archivo por lotes con la salida de env-unset:

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

Tu aplicación se conectará a tu base de datos en modo Datastore de producción.

Eliminar las variables manualmente

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

  1. Ejecuta el comando env-unset:

    gcloud beta emulators datastore env-unset

  2. En la máquina que ejecuta tu aplicación, elimina las variables de entorno según las indicaciones de la salida del comando env-unset. Por ejemplo:

    Linux o 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=

Tu aplicación se conectará a tu base de datos en modo Datastore de producción.