Emular o Spanner localmente

A CLI gcloud oferece um emulador local na memória para desenvolver e testar seus aplicativos. Como o emulador armazena dados apenas na memória, ele perde todo o estado, incluindo dados, esquema e configurações, na reinicialização. O emulador oferece as mesmas APIs que o serviço de produção do Spanner e serve para desenvolvimento e testes locais, não para implantações de produção.

O emulador oferece suporte aos dialetos GoogleSQL e PostgreSQL. Ele é compatível com 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 oferece suporte a:

  • TLS/HTTPS, autenticação, Identity and Access Management (IAM), permissões ou papéis.
  • Nos modos de consulta PLAN ou PROFILE query, o plano de consulta retornado está vazio.
  • A instrução ANALYZE. O emulador aceita, mas ignora.
  • Qualquer uma das ferramentas de geração de registros de auditoria e monitoramento.
  • Proteção contra exclusão de banco de dados. O emulador aceita o campo enable_drop_protection, mas permite que os bancos de dados sejam descartados mesmo que essa propriedade esteja ativada.

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

  • As mensagens de erro podem ser diferentes entre o emulador e o serviço de produção.
  • 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é a conclusão.
  • O emulador oferece suporte à DML particionada e partitionQuery, mas não verifica se as instruções são particionáveis. Isso significa que uma instrução DML particionada ou partitionQuery pode ser executada no emulador, mas 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 README arquivo 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.

Executar o emulador usando a CLI gcloud

Para executar o emulador usando a Google Cloud CLI:

  1. Instale o componente cloud-spanner-emulator:

    gcloud components install cloud-spanner-emulator

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

    gcloud components update

  2. Inicie o emulador.

    gcloud emulators spanner start

    O emulador usa dois endpoints locais:

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

Executar o emulador usando o Docker

Para executar o emulador usando o Docker:

  1. Instale Docker no seu 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.

Configurar a CLI gcloud para usar o emulador

Para usar o emulador com a CLI gcloud, desative a autenticação e substitua o endpoint. Crie uma configuração separada da CLI gcloud 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/

  2. Depois de configurada, a CLI gcloud envia seus comandos 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

Alternar configurações

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

# To switch to default (production) configuration:
gcloud config configurations activate default

# To switch back to emulator configuration:
gcloud config configurations activate emulator

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 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#, especifique a emulatordetection opção 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. O exemplo a seguir mostra a string de conexão:

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