Usa el emulador de Cloud Spanner

El SDK de Cloud proporciona un emulador local en la memoria, que puedes usar para desarrollar y probar tus aplicaciones de forma gratuita sin crear un proyecto de GCP o una cuenta de facturación. Como el emulador almacena datos solo en la memoria, no se conservarán en las ejecuciones. El emulador ofrece las mismas API que el servicio de producción de Cloud Spanner y está diseñado para el desarrollo y las pruebas locales, no para la implementación en producción.

El emulador es compatible con todos los lenguajes de las bibliotecas cliente. También puedes usar el emulador con la herramienta de línea de comandos de gcloud y las API de REST.

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

Limitaciones y diferencias

El emulador no admite lo siguiente:

El emulador también se diferencia del servicio de producción de Cloud Spanner de las siguientes maneras:

  • 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 con el servicio de producción.
  • Las transacciones de lectura o de escritura y los cambios de esquema bloquearán toda la base de datos para obtener acceso exclusivo hasta que se completen.
  • El DML particionado y la consulta de partición son compatibles, pero el emulador no verifica si las declaraciones se pueden particionar. Esto significa que una declaración de DML particionado o de consulta de partición podría ejecutarse en el emulador, pero puede fallar en el servicio de producción con un error de declaración no particionable.

Para obtener una lista completa de las API y características compatibles, no compatibles y parcialmente compatibles, consulta el archivo README de GitHub.

Instala y ejecuta el emulador

Las dos formas más comunes de ejecutar el emulador son con gcloud CLI y Docker. Puedes elegir la forma adecuada para el desarrollo de tu aplicación y el flujo de trabajo de prueba.

CLI de gcloud

  1. Instala el SDK de Cloud.

  2. Para los usuarios de Windows y MacOS, el emulador requiere que Docker esté instalado en tu sistema y disponible en la ruta del sistema.

  3. Actualiza gcloud para obtener la última versión:

    gcloud components update
    
  4. Inicia el emulador:

    gcloud beta emulators spanner start
    

    Si el emulador aún no está instalado, se te solicitará que realices la descarga y la instalación del objeto binario para el emulador.

    De forma predeterminada, el emulador aloja dos extremos locales: localhost:9010 para las solicitudes de gRPC y localhost:9020 para las solicitudes de REST.

    Para obtener más detalles sobre este comando, consulta emuladores spanner de gcloud.

Docker

  1. Asegúrate de que Docker esté instalado en tu sistema y 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. Inicia el emulador:

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

    Este comando ejecuta el emulador y asigna los puertos en el contenedor a los mismos puertos en tu host local. Tendrás dos extremos locales: localhost:9010 para solicitudes de gRPC y localhost:9020 para solicitudes REST.

Usa la CLI de gcloud con el emulador

Para usar el emulador con gcloud, debes inhabilitar la autenticación y anular el extremo.

Te recomendamos crear una configuración de gcloud por separado, para que puedas cambiar entre el emulador y el servicio de producción con rapidez. Para crear y activar una configuración de emulador, ejecuta lo siguiente:

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 configurado, tus comandos de gcloud se enviarán al emulador en lugar del servicio de producción. Para verificar esto, 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]

Usa las bibliotecas cliente con el emulador

Puedes usar versiones compatibles de las bibliotecas cliente con el emulador mediante la configuración de la variable de entorno SPANNER_EMULATOR_HOST. Hay muchas maneras 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 beta emulators spanner env-init)

Windows

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

Cuando se inicia la aplicación, la biblioteca cliente busca SPANNER_EMULATOR_HOST automáticamente y se conecta al emulador si se está ejecutando.

Una vez que SPANNER_EMULATOR_HOST esté establecido, puedes probar el emulador. Para ello, sigue las guías de introducción a continuación. Puedes ignorar las instrucciones relacionadas con la creación, la autenticación y las credenciales de proyectos, ya que estas no son necesarias para usar el emulador.

Versiones compatibles

En la siguiente tabla, se muestran las versiones de las bibliotecas cliente que son compatibles con el emulador.

Biblioteca 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+
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

Instrucciones adicionales para C#

Para la biblioteca cliente de C#, también debes especificar la opción emulatordetection en la string de conexión. A diferencia de las otras bibliotecas cliente, C# ignora la variable de entorno SPANNER_EMULATOR_HOST de forma predeterminada. Estos son los pasos que debe seguir:

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