Emula Spanner de forma local

La Google Cloud CLI proporciona un emulador local en la memoria para desarrollar y probar tus aplicaciones. Como el emulador almacena datos solo en la memoria, pierde todo el estado, incluidos los datos, el esquema y los parámetros de configuración, cuando se reinicia. El emulador ofrece las mismas APIs que el servicio de producción de Spanner y sirve 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 la gcloud 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, Identity and Access Management (IAM), permisos o roles
  • En los modos de consulta PLAN o PROFILE, el plan de consulta que se devuelve 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
  • Protección contra la eliminación de bases de datos. El emulador acepta el campo enable_drop_protection, pero permite que se borren las bases de datos incluso si esta propiedad está habilitada.

El emulador también difiere del servicio de producción de Spanner de las siguientes maneras:

  • Los mensajes de error pueden diferir entre el emulador y el servicio de producción.
  • El rendimiento y la escalabilidad del emulador no se comparan 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 el acceso exclusivo hasta que se completen.
  • El emulador admite DML particionado y partitionQuery, pero no verifica que las declaraciones sean particionables. Esto significa que una declaración DML o partitionQuery particionada podría ejecutarse en el emulador, pero 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 que sea adecuada para el desarrollo de tu aplicación y el flujo de trabajo de prueba.

Ejecuta el emulador con gcloud CLI

Para ejecutar el emulador con gcloud CLI, sigue estos pasos:

  1. Instala el componente cloud-spanner-emulator:

    gcloud components install cloud-spanner-emulator

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

    gcloud components update

  2. Inicia el emulador:

    gcloud emulators spanner start

    El emulador usa dos extremos locales:

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

Ejecuta el emulador con Docker

Para ejecutar el emulador con Docker, sigue estos pasos:

  1. Instala Docker en tu sistema y haz que esté disponible en la ruta de acceso 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.

Configura gcloud CLI para usar el emulador

Para usar el emulador con gcloud CLI, inhabilita la autenticación y anula el extremo. Crea una configuración de gcloud CLI independiente para cambiar con rapidez entre el emulador y el servicio de producción.

  1. Crea y activa una configuración del 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/

  2. Después de configurarla, gcloud CLI envía tus comandos al emulador en lugar de al servicio de producción. Para verificarlo, crea una instancia con la configuración de instancia del emulador:

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

Configuraciones de conmutadores

Para alternar entre el emulador y tu configuración predeterminada, ejecuta lo siguiente:

# To switch to default (production) configuration:
gcloud config configurations activate default

# To switch back to emulator configuration:
gcloud config configurations activate emulator

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 verifica automáticamente si existe SPANNER_EMULATOR_HOST y se conecta al emulador si se está ejecutando.

Una vez que se haya configurado 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

Para la biblioteca cliente de C#, especifica 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. En el siguiente ejemplo, se muestra la cadena de conexión:

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