Emule o Spanner localmente

A CLI gcloud oferece um emulador local na memória que pode usar para desenvolver e testar as suas aplicações. Uma vez que o emulador armazena dados apenas na memória, todo o estado, incluindo dados, esquema e configurações, é perdido no reinício. O emulador oferece as mesmas APIs que o serviço de produção do Spanner e destina-se ao desenvolvimento e aos testes locais, não a implementações de produção.

O emulador suporta os dialetos GoogleSQL e PostgreSQL. É compatível com todos os idiomas das bibliotecas cliente. Também pode usar o emulador com a CLI Google Cloud 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 suporta o seguinte:

  • TLS/HTTPS, autenticação, gestão de identidade e de acesso, autorizações ou funções.
  • Nos PLAN ou PROFILE modos de consulta, o plano de consulta devolvido está vazio.
  • A ANALYZEdeclaração. O emulador aceita-o, mas ignora-o.
  • Qualquer uma das ferramentas de registo de auditoria e monitorização.

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

  • As mensagens de erro podem não ser consistentes entre o emulador e o serviço de produção.
  • O desempenho e a escalabilidade do emulador não são comparáveis ao serviço de produção.
  • As transações de leitura/escrita e as alterações ao esquema bloqueiam toda a base de dados para acesso exclusivo até serem concluídas.
  • A DML particionada e a partitionQuery são suportadas, mas o emulador não verifica se as declarações são particionáveis. Isto significa que uma DML ou uma declaração partitionQuery particionada pode ser executada no emulador, mas pode falhar no serviço de produção com o erro de declaração não particionável.

Para ver uma lista completa das APIs e funcionalidades suportadas, não suportadas e parcialmente suportadas, consulte o ficheiro README no GitHub.

Opções para executar o emulador

Existem duas formas comuns de executar o emulador:

Escolha a forma adequada ao seu desenvolvimento de aplicações e fluxo de trabalho de teste.

Configure o emulador para a CLI gcloud

Para utilizadores 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 cloud-spanner-emulator

    Se a CLI gcloud já estiver instalada, execute o seguinte comando para garantir que todos os respetivos componentes estão atualizados:

    gcloud components update

Crie e configure o emulador através da CLI gcloud

Para usar o emulador com a CLI gcloud, tem de desativar a autenticação e substituir o ponto final. Recomendamos que crie uma configuração da CLI gcloud separada para poder alternar rapidamente entre o emulador e o serviço de produção.

  1. Crie e ative uma configuração do 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 CLI gcloud são enviados para o emulador em vez do serviço de produção. Pode verificar isto criando 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 predefinida, execute:

    gcloud config configurations activate [emulator | default]

  2. Inicie o emulador através da CLI gcloud.

Instale o emulador no Docker

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

  2. Transfira a imagem do emulador mais recente:

    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

    Este comando executa o emulador e mapeia as portas no contentor para as mesmas portas no seu anfitrião local. O emulador usa dois pontos finais locais: localhost:9010 para pedidos gRPC e localhost:9020 para pedidos REST.

  4. Inicie o emulador através da CLI gcloud.

Inicie o emulador através da CLI gcloud

Inicie o emulador com o comando gcloud emulators spanner:

gcloud emulators spanner start

O emulador usa dois pontos finais locais:

  • localhost:9010 para pedidos gRPC
  • localhost:9020 para pedidos REST

Use as bibliotecas cliente com o emulador

Pode usar versões suportadas das bibliotecas cliente com o emulador definindo a variável de ambiente SPANNER_EMULATOR_HOST. Existem várias formas de o fazer. Por exemplo:

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Em alternativa, com gcloud env-init:

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

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

Quando a sua aplicação é iniciada, a biblioteca de cliente verifica automaticamente a existência de um SPANNER_EMULATOR_HOST e estabelece ligação ao emulador, se este estiver em execução.

Assim que SPANNER_EMULATOR_HOST estiver definido, pode testar o emulador seguindo os guias de introdução. Ignore as instruções relacionadas com a criação de projetos, a autenticação e as credenciais, uma vez que não são necessárias para usar o emulador.

Versões suportadas

A tabela seguinte indica as versões das bibliotecas cliente que suportam o emulador.

Biblioteca 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#, também tem de especificar a opção emulatordetection na string de ligação. Ao contrário das outras bibliotecas cliente, o C# ignora a variável de ambiente SPANNER_EMULATOR_HOST por predefinição. Segue-se um exemplo da string de ligação:

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