Emular Spanner localmente

La CLI de gcloud proporciona un emulador local en memoria que puedes usar para desarrollar y probar tus aplicaciones. Como el emulador solo almacena datos en la memoria, al reiniciarse se pierde todo el estado, incluidos los datos, el esquema y las configuraciones. El emulador ofrece las mismas APIs que el servicio de producción de Spanner y está diseñado para el desarrollo y las pruebas locales, no para las implementaciones de producción.

El emulador admite los dialectos GoogleSQL y PostgreSQL. Admite todos los idiomas de las bibliotecas de cliente. También puedes usar el emulador con la CLI de Google Cloud y las APIs REST.

El emulador también está disponible como proyecto de código abierto en GitHub.

Limitaciones y diferencias

El emulador no admite lo siguiente:

  • TLS/HTTPS, autenticación, gestión de identidades y accesos, permisos o roles.
  • En los modos de consulta PLAN o PROFILE, el plan de consulta que se devuelve está vacío.
  • La instrucción ANALYZE. El emulador lo acepta, pero lo ignora.
  • Cualquiera de las herramientas de registro de auditoría y de monitorización.

El emulador también se diferencia del servicio de producción de Spanner en los siguientes aspectos:

  • Es posible que los mensajes de error no sean coherentes entre el emulador y el servicio de producción.
  • El rendimiento y la escalabilidad del emulador no son comparables a los del servicio de producción.
  • Las transacciones de lectura y escritura y los cambios de esquema bloquean toda la base de datos para que solo se pueda acceder a ella hasta que se completen.
  • Se admiten DML particionados y partitionQuery, pero el emulador no comprueba que las instrucciones sean particionables. Esto significa que una instrucción DML o partitionQuery particionada puede ejecutarse en el emulador, pero puede fallar en el servicio de producción con el error de instrucción no particionable.

Para ver una lista completa de las APIs y funciones que se admiten, no se admiten y se admiten parcialmente, consulta el archivo README en GitHub.

Opciones para ejecutar el emulador

Hay dos formas habituales de ejecutar el emulador:

Elige el método que mejor se adapte al desarrollo de tu aplicación y al flujo de trabajo de pruebas.

Configurar el emulador para gcloud CLI

Si usas Windows o macOS, antes de instalar el emulador, haz lo siguiente:

  • Instala los componentes de gcloud CLI en tu estación de trabajo:

    gcloud components install cloud-spanner-emulator

    Si la CLI de gcloud ya está instalada, ejecuta el siguiente comando para asegurarte de que todos sus componentes estén actualizados:

    gcloud components update

Crear y configurar el emulador con gcloud CLI

Para usar el emulador con la CLI de gcloud, debes inhabilitar la autenticación y anular el endpoint. Te recomendamos que crees una configuración de la CLI de gcloud independiente para poder cambiar rápidamente entre el emulador y el servicio de producción.

  1. Crea y activa una configuración de emulador:

      gcloud config configurations create emulator
  gcloud config set auth/disable_credentials true
  gcloud config set project your-project-id
  gcloud config set api_endpoint_overrides/spanner http://localhost:9020/

    Una vez configurados, los comandos de la CLI de gcloud se envían al emulador en lugar de al servicio de producción. Para comprobarlo, crea una instancia con la configuración de la instancia del emulador:

    gcloud spanner instances create test-instance \
  --config=emulator-config --description="Test Instance" --nodes=1

    Para cambiar entre el emulador y la configuración predeterminada, ejecuta lo siguiente:

    gcloud config configurations activate [emulator | default]

  2. Inicia el emulador con gcloud CLI.

Instalar el emulador en Docker

  1. Instala Docker en tu sistema y haz que esté disponible en la ruta del sistema.

  2. Obtén la imagen de emulador más reciente:

    docker pull gcr.io/cloud-spanner-emulator/emulator

  3. Ejecuta el emulador en Docker:

    docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator

    Este comando ejecuta el emulador y asigna los puertos del contenedor a los mismos puertos de tu host local. El emulador usa dos endpoints locales: localhost:9010 para las solicitudes gRPC y localhost:9020 para las solicitudes REST.

  4. Inicia el emulador con gcloud CLI.

Iniciar el emulador con gcloud CLI

Inicia el emulador con el comando gcloud emulators spanner:

gcloud emulators spanner start

El emulador usa dos endpoints locales:

  • localhost:9010 para solicitudes gRPC
  • localhost:9020 para solicitudes REST

Usar las bibliotecas de cliente con el emulador

Puedes usar las versiones admitidas de las bibliotecas de cliente con el emulador configurando la variable de entorno SPANNER_EMULATOR_HOST. Hay muchos modos de hacerlo. Por ejemplo:

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

O con gcloud env-init:

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

gcloud emulators spanner env-init > set_vars.cmd && set_vars.cmd

Cuando se inicia tu aplicación, la biblioteca cliente comprueba automáticamente si SPANNER_EMULATOR_HOST está en ejecución y se conecta al emulador si lo está.

Una vez que se haya configurado SPANNER_EMULATOR_HOST, puedes probar el emulador siguiendo las guías de inicio. Ignora las instrucciones relacionadas con la creación de proyectos, la autenticación y las credenciales, ya que no son necesarias para usar el emulador.

Versiones compatibles

En la siguiente tabla se indican las versiones de las bibliotecas de cliente que admiten el emulador.

Biblioteca de cliente Versión mínima
C++ v0.9.x+
C# v3.1.0+
Go v1.5.0+
Java v1.51.0+
Node.js v4.5.0 o versiones posteriores
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

Instrucciones adicionales para C#

En el caso de la biblioteca de cliente de C#, también debes especificar la opción emulatordetection en la cadena de conexión. A diferencia de las otras bibliotecas de cliente, C# ignora la variable de entorno SPANNER_EMULATOR_HOST de forma predeterminada. A continuación, se muestra un ejemplo de cadena de conexión:

var builder = new SpannerConnectionStringBuilder
{
    DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
    EmulatorDetection = "EmulatorOnly"
};