Como usar o emulador do Cloud Spanner (Beta)

O SDK do Cloud fornece um emulador local na memória, que você pode usar para desenvolver e testar seus aplicativos gratuitamente sem criar um projeto do GCP ou uma conta de faturamento. Como o emulador armazena dados apenas na memória, ele não mantém os dados nas execuções. O emulador oferece as mesmas APIs que o serviço de produção do Cloud Spanner e destina-se ao desenvolvimento e teste locais, não para implantações de produção.

O emulador é compatível com todas as linguagens das bibliotecas de cliente, exceto C# (compatibilidade disponível em breve). Você também pode usar o emulador com a ferramenta de linha de comando gcloud 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 Cloud 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.

Como instalar e executar o emulador

As duas maneiras mais comuns de executar o emulador são com o gcloud CLI e o Docker. Escolha o modo apropriado para para o desenvolvimento do aplicativo e teste do fluxo de trabalho.

CLI da gcloud

  1. Instale o SDK do Cloud.

  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 o gcloud para acessar a versão mais recente:

    gcloud components update
    
  4. Inicie o emulador.

    gcloud beta 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. Certifique-se de que o Docker esteja instalado no seu sistema e esteja disponível no caminho do sistema.

  2. Receba 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.

Como usar a CLI do 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

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

Biblioteca de cliente Versão mínima
C++ v0.9.x+
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+

Para usar o emulador com bibliotecas de cliente, defina 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 beta emulators spanner env-init)

Windows

gcloud beta 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.