Emular o Spanner localmente

A CLI gcloud fornece um emulador local na memória, que pode ser usado para desenvolver e testar seus aplicativos com uma instância de teste gratuita sem criar um projeto do Google Cloud ou uma conta de faturamento. Como o emulador armazena dados apenas na memória, todo o estado, incluindo dados, esquema e configurações, é perdido na reinicialização. O emulador oferece as mesmas APIs que o serviço de produção do Spanner e destina-se ao desenvolvimento e teste locais, não para implantações de produção.

O emulador oferece suporte aos dialetos GoogleSQL e PostgreSQL. Ele oferece suporte a todas as linguagens das bibliotecas de cliente. Também é possível usar o emulador com a Google Cloud CLI e as APIs REST.

O emulador também está disponível como um projeto de código aberto no GitHub.

Limitações e diferenças

O emulador não é compatível com:

O emulador também é diferente do serviço de produção do Spanner das seguintes maneiras:

  • As mensagens de erro entre o emulador e o serviço de produção podem não ser consistentes.
  • O desempenho e a escalonabilidade do emulador não são comparáveis ao serviço de produção.
  • As transações de leitura e gravação e as alterações de esquema bloqueiam todo o banco de dados para acesso exclusivo até que sejam concluídas.
  • A DML particionada e o partitionQuery são compatíveis, mas o emulador não verifica se as instruções são particionáveis. Isso significa que uma instrução DML ou partitionQuery particionada pode ser executada no emulador, mas pode falhar no serviço de produção com o erro de instrução não particionável.

Para ver uma lista completa de APIs e recursos compatíveis, incompatíveis e parcialmente compatíveis, consulte o arquivo README no GitHub.

Opções para executar o emulador

Há duas maneiras comuns de executar o emulador:

Escolha a maneira apropriada para o fluxo de trabalho de desenvolvimento e teste do aplicativo.

Configurar o emulador para a CLI gcloud

Para usuários do Windows e macOS, antes de instalar o emulador, faça o seguinte:

  • Instale os componentes da CLI gcloud na sua estação de trabalho:

    gcloud components install

    Se a gcloud CLI já estiver instalada, execute o comando abaixo para garantir que todos os componentes estejam atualizados:

    gcloud components update

Criar e configurar o emulador usando a CLI gcloud

Para usar o emulador com a CLI do gcloud, desative a autenticação e substitua o endpoint. Recomendamos que você crie uma configuração da CLI do gcloud separada para alternar rapidamente entre o emulador e o serviço de produção.

  1. Crie e ative uma configuração 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/

    Depois de configurados, os comandos da gcloud CLI são enviados ao emulador em vez do serviço de produção. Para verificar isso, crie uma instância com a configuração da instância do emulador:

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

    Para alternar entre o emulador e a configuração padrão, execute:

    gcloud config configurations activate [emulator | default]

  2. Inicie o emulador usando a CLI gcloud.

Instalar o emulador no Docker

  1. Instale o Docker no sistema e disponibilize-o no caminho do sistema.

  2. Consiga a imagem mais recente do emulador:

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

  3. Execute o emulador no Docker:

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

    Esse comando executa o emulador e mapeia as portas no contêiner para as mesmas portas no host local. O emulador usa dois endpoints locais: localhost:9010 para solicitações gRPC e localhost:9020 para solicitações REST.

  4. Inicie o emulador usando a CLI gcloud.

Iniciar o emulador usando a CLI gcloud

Inicie o emulador usando o comando gcloud emulators spanner:

gcloud emulators spanner start

O emulador usa dois endpoints locais:

  • localhost:9010 para solicitações gRPC
  • localhost:9020 para solicitações REST

Como usar as bibliotecas de cliente com o emulador

Você pode usar versões compatíveis das bibliotecas de cliente com o emulador configurando a variável de ambiente SPANNER_EMULATOR_HOST. Há muitas maneiras de fazer isso: Exemplo:

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Ou com gcloud env-init:

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

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

Quando o aplicativo é iniciado, a biblioteca de cliente verifica automaticamente se há SPANNER_EMULATOR_HOST e se conecta ao emulador se ele estiver em execução.

Depois que SPANNER_EMULATOR_HOST for definido, você poderá testar o emulador seguindo os guias de primeiros passos. Ignore as instruções relacionadas à criação, autenticação e credenciais do projeto, já que elas não são necessárias para usar o emulador.

Versões compatíveis

A tabela a seguir lista as versões das bibliotecas de cliente compatíveis com o emulador.

Biblioteca de cliente Versão 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+

Instruções adicionais para C#

Para a biblioteca de cliente C#, você também precisa especificar a opção emulatordetection na string de conexão. Ao contrário das outras bibliotecas de cliente, C# ignora a variável de ambiente SPANNER_EMULATOR_HOST por padrão. Confira abaixo um exemplo de string de conexão:

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