Emular o Spanner localmente

A gcloud CLI fornece um emulador local na memória, que você pode usar para desenvolver e testar aplicativos gratuitamente sem criar um projeto do Google Cloud ou do Google Cloud. À medida que 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 às APIs GoogleSQL e PostgreSQL dialetos. Ele oferece suporte a todas as linguagens das bibliotecas de cliente. Você também pode usar o emulador com o Google Cloud CLI e 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 a Consulta de partição 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 particionada ou uma consulta de partição pode ser executada no emulador, mas pode falhar no serviço de produção com um 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.

Instalar e executar o emulador

As duas maneiras mais comuns de executar o emulador são usando a CLI gcloud e Docker. Escolha o método apropriado para o desenvolvimento do aplicativo e o fluxo de trabalho de teste.

CLI da gcloud

  1. Instale a CLI da gcloud.

  2. Para usuários do Windows e MacOS, o emulador exige que o Docker esteja instalado no sistema e disponível no caminho do sistema.

  3. Atualize gcloud para conseguir a versão mais recente:

    gcloud components update

  4. Inicie o emulador.

    gcloud emulators spanner start

    Se o emulador não estiver instalado, você será solicitado a fazer download e instalar o binário para o emulador.

    Por padrão, o emulador hospeda dois endpoints locais: localhost:9010 para solicitações gRPC e localhost:9020 para solicitações REST.

    Para mais detalhes sobre esse comando, consulte gcloud emulators spanner.

Docker

  1. Verifique se o Docker está instalado no seu sistema e disponível no caminho do sistema.

  2. Consiga a imagem mais recente do emulador:

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

  3. Inicie o emulador.

    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. Você terá dois endpoints locais: localhost:9010 para solicitações gRPC e localhost:9020 para solicitações REST.

Usar a CLI gcloud com o emulador

Para usar o emulador com o gcloud, desative a autenticação e substitua o endpoint.

Recomendamos que você crie uma configuração do gcloud separada para alternar rapidamente entre o emulador e o serviço de produção. Para criar e ativar uma configuração de emulador, execute:

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 do gcloud serã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]

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 abaixo. Você pode ignorar 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. Veja como fazer isso:

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