Emula Spanner de forma local

La gcloud 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 de GoogleSQL y PostgreSQL. Admite todos los lenguajes de las bibliotecas cliente. También puedes usar el emulador con la Google Cloud CLI y API de REST.

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

Nota: Para explorar Spanner con una instancia de prueba gratuita de 90 días, consulta Crea una instancia de prueba gratuita de Spanner.

Limitaciones y diferencias

El emulador no admite lo siguiente:

• TLS/HTTPS, autenticación, Identity and Access Management (IAM), permisos o funciones
• En los modos de consulta PLAN o PROFILE query modes, el plan de consulta que se muestra está vacío.
• La sentencia ANALYZE. El emulador la acepta, pero la ignora.
• Cualquiera de los registros de auditoría y las herramientas de supervisión
• Protección contra eliminación de bases de datos El emulador acepta el campo enable_drop_protection, pero permite que se eliminen las bases de datos, incluso si esta propiedad está habilitada.

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

• Es posible que los mensajes de error difieran 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 obtener acceso exclusivo hasta que se completen.
• El emulador admite el DML particionado y partitionQuery, pero no verifica que las sentencias se puedan particionar. Esto significa que una sentencia de DML particionado o de partitionQuery podría ejecutarse en el emulador, pero fallar en el servicio de producción con el error de sentencia no particionable.

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

Opciones para ejecutar el emulador

Existen dos formas comunes de ejecutar el emulador:

• CLI de gcloud
• Docker

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

Nota: Para obtener más formas de ejecutar el emulador, consulta el README.

Ejecuta el emulador con gcloud CLI

Para ejecutar el emulador con Google Cloud CLI, haz lo siguiente:

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
   Nota: Cuando inicias el emulador, es posible que veas varios mensajes de advertencia sobre conflictos de registro de proto (como WARNING: proto: file "google/rpc/status.proto" is already registered) o mensajes de registro antes de la inicialización (WARNING: All log messages before absl::InitializeLog() is called are written to STDERR). Estas advertencias son esperadas y se pueden ignorar sin problemas.

Ejecuta el emulador con Docker

Para ejecutar el emulador con Docker, haz lo siguiente:

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

   Nota: Cuando inicias el emulador, es posible que veas varios mensajes de advertencia sobre conflictos de registro de proto (como WARNING: proto: file "google/rpc/status.proto" is already registered) o mensajes de registro antes de la inicialización (WARNING: All log messages before absl::InitializeLog() is called are written to STDERR). Estas advertencias son esperadas y se pueden ignorar sin problemas.

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 la CLI de gcloud independiente para 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/
   

   Nota: Cuando ejecutas gcloud config set api_endpoint_overrides/spanner, es posible que recibas una advertencia de que el valor de la propiedad está asociado con un dominio fuera del universo de configuración actual. Escribe y o yes para confirmar el mensaje y continuar.

2. Una vez configurada, gcloud CLI envía tus comandos 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
   

Cambia las configuraciones

Para cambiar entre el emulador y la 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 versiones compatibles de las bibliotecas cliente con el emulador configurando la variable de entorno SPANNER_EMULATOR_HOST. Existen muchas maneras de hacerlo. Por ejemplo:

**Importante:** Si usas C#, consulta las instrucciones adicionales para C#.

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

Una vez que se configura 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.

• Primeros pasos con C++

• Primeros pasos con C#. Debes configurar las opciones de string de conexión. Consulta las instrucciones adicionales para C#.

• Comenzar en Go

• Comenzar en Java

• Comenzar en Node.js

• Comenzar en PHP

• Comenzar en Python

• Comenzar en Ruby

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 emulatordetection opción 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 el string de conexión:

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