Emula Spanner de forma local

gcloud CLI proporciona un emulador local en la memoria, que puedes usar para desarrollar y probar tus aplicaciones con una instancia de prueba gratuita sin crear un proyecto de Google Cloud ni una cuenta de facturación. Como el emulador almacena datos solo en la memoria, se pierde todo el estado, incluidos los datos, el esquema y las configuraciones, cuando se reinicia. 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 lenguajes de las bibliotecas cliente. También puedes usar el emulador con Google Cloud CLI y las APIs 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:

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

El emulador también se diferencia del servicio de producción de 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 bloquean toda la base de datos para obtener acceso exclusivo hasta que se completen.
  • El DML particionado y partitionQuery son compatibles, pero el emulador no verifica si las declaraciones se pueden particionar. Esto significa que una declaración de DML particionado o partitionQuery podría ejecutarse en el emulador, pero podría fallar en el servicio de producción con el 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.

Opciones para ejecutar el emulador

Existen dos formas comunes de ejecutar el emulador:

Elige la forma adecuada para el desarrollo de tu aplicación y el flujo de trabajo de prueba.

Configura el emulador para la CLI de gcloud

Para los usuarios de Windows y macOS, antes de instalar el emulador, haz lo siguiente:

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

    gcloud components install

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

    gcloud components update

Crea y configura el emulador con gcloud CLI

Para usar el emulador con gcloud CLI, debes inhabilitar la autenticación y anular el extremo. Te recomendamos crear una configuración de gcloud CLI independiente para que puedas 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, tus comandos de gcloud CLI se envían 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]

  2. Inicia el emulador con la CLI de gcloud.

Instala 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 más reciente del emulador:

    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 extremos locales: localhost:9010 para las solicitudes de gRPC y localhost:9020 para las solicitudes de REST.

  4. Inicia el emulador con la CLI de gcloud.

Inicia el emulador con la CLI de gcloud

Inicia el emulador con el comando gcloud emulators spanner:

gcloud emulators spanner start

El emulador usa dos extremos locales:

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

Usa las bibliotecas cliente con el emulador

Puedes usar las versiones compatibles de las bibliotecas cliente con el emulador si configuras la variable de entorno SPANNER_EMULATOR_HOST. Existen 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 emulators spanner env-init)

Windows

gcloud 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 se configure SPANNER_EMULATOR_HOST, puedes probar el emulador siguiendo las guías de introducción. Ignora las instrucciones relacionadas con la creación, la autenticación y las credenciales del proyecto, ya que no son necesarias para usar el emulador.

Versiones compatibles

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

Biblioteca cliente Versión mínima
C++ v0.9.x+
C# v3.1.0+
Comienza a usarlo 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#

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

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