Introdução ao adaptador Spanner Cassandra

1. Introdução

O Spanner é um serviço de banco de dados totalmente gerenciado, escalonável horizontalmente e distribuído globalmente, ótimo para cargas de trabalho relacionais e não relacionais.

A interface do Cassandra do Spanner permite aproveitar a infraestrutura totalmente gerenciada, escalonável e altamente disponível do Spanner usando ferramentas e sintaxe conhecidas do Cassandra.

O que você vai aprender

  • Como configurar uma instância e um banco de dados do Spanner.
  • Como converter o esquema e o modelo de dados do Cassandra.
  • Como implantar e configurar gravações duplas para dados recebidos.
  • Como exportar dados históricos em massa do Cassandra para o Spanner.
  • Como validar dados para garantir a integridade deles durante o processo de migração.
  • Como apontar seu aplicativo para o Spanner em vez do Cassandra.

O que é necessário

  • Um projeto do Google Cloud conectado a uma conta de faturamento.
  • Acesso a uma máquina com a CLI gcloud instalada e configurada ou use o Google Cloud Shell.
  • Um navegador, como o Chrome ou o Firefox

2. Configuração e requisitos

Criar um projeto do GCP

Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
  • O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
  • Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Configuração de faturamento

Em seguida, siga o guia do usuário para gerenciar o faturamento e ative o faturamento no console do Cloud. Novos usuários do Google Cloud estão qualificados para o programa de US$300 de avaliação sem custos. Para evitar cobranças além deste tutorial, encerre a instância do Spanner no final do codelab seguindo a "Etapa 9: Limpeza".

Iniciar o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

55efc1aaa7a4d3ad.png

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

7ffe5cbb04455448.png

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

A seguir

Em seguida, você vai implantar o cluster do Cassandra.

3. Implantar o cluster do Cassandra (Origin)

Neste codelab, vamos configurar um cluster Cassandra de nó único no Compute Engine.

1. Criar uma VM do GCE para o Cassandra

Para criar uma instância, use o comando gcloud compute instances create.

gcloud compute instances create cassandra-origin \
--machine-type=e2-medium \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB

2. Instalar o Cassandra

# Install Java (Cassandra dependency)
sudo apt-get update
sudo apt-get install -y openjdk-11-jre-headless

# Add Cassandra repository
echo "deb [https://debian.cassandra.apache.org](https://debian.cassandra.apache.org) 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl [https://downloads.apache.org/cassandra/KEYS](https://downloads.apache.org/cassandra/KEYS) | sudo apt-key add -

# Install Cassandra
sudo apt-get update
sudo apt-get install -y cassandra

3. Criar um keyspace e uma tabela

Vamos usar um exemplo de tabela de usuários e criar um keyspace chamado "analytics".

cd ~/apache-cassandra
bin/cqlsh <your-localhost-ip? 9042  #starts the cql shell

Dentro do cqlsh:

-- Create keyspace (adjust replication for production)
CREATE KEYSPACE analytics WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};

-- Use the keyspace
USE analytics;

-- Create the users table
CREATE TABLE users (
    id  int PRIMARY KEY,
    active  boolean,
    username  text,
);

-- Exit cqlsh
EXIT;

Deixe a sessão SSH aberta ou anote o endereço IP dessa VM (hostname -I).

A seguir

Agora, configure uma instância e um banco de dados do Cloud Spanner.

4. Criar uma instância e um banco de dados do Spanner (destino)

No Spanner, uma instância é um cluster de recursos de computação e armazenamento que hospeda um ou mais bancos de dados do Spanner. Você vai precisar de pelo menos uma instância para hospedar um banco de dados do Spanner para este codelab.

Verificar a versão do SDK do gcloud

Antes de criar uma instância, verifique se o SDK gcloud no Google Cloud Shell foi atualizado para a versão necessária: SDK gcloud 493.0.0. Para encontrar a versão do SDK do gcloud, siga o comando abaixo.

$ gcloud version | grep Google

Confira um exemplo de saída:

Google Cloud SDK 489.0.0

Se a versão que você está usando for anterior à 493.0.0 (489.0.0 no exemplo anterior), atualize o SDK Google Cloud executando o seguinte comando:

sudo apt-get update \
  && sudo apt-get --only-upgrade install google-cloud-cli-anthoscli google-cloud-cli-cloud-run-proxy kubectl google-cloud-cli-skaffold google-cloud-cli-cbt google-cloud-cli-docker-credential-gcr google-cloud-cli-spanner-migration-tool google-cloud-cli-cloud-build-local google-cloud-cli-pubsub-emulator google-cloud-cli-app-engine-python google-cloud-cli-kpt google-cloud-cli-bigtable-emulator google-cloud-cli-datastore-emulator google-cloud-cli-spanner-emulator google-cloud-cli-app-engine-go google-cloud-cli-app-engine-python-extras google-cloud-cli-config-connector google-cloud-cli-package-go-module google-cloud-cli-istioctl google-cloud-cli-anthos-auth google-cloud-cli-gke-gcloud-auth-plugin google-cloud-cli-app-engine-grpc google-cloud-cli-kubectl-oidc google-cloud-cli-terraform-tools google-cloud-cli-nomos google-cloud-cli-local-extract google-cloud-cli-firestore-emulator google-cloud-cli-harbourbridge google-cloud-cli-log-streaming google-cloud-cli-minikube google-cloud-cli-app-engine-java google-cloud-cli-enterprise-certificate-proxy google-cloud-cli

Ativar a API Spanner

No Cloud Shell, verifique se o ID do projeto está configurado. Use o primeiro comando abaixo para encontrar o ID do projeto configurado. Se o resultado não for o esperado, o segundo comando abaixo vai definir o correto.

gcloud config get-value project
gcloud config set project [YOUR-DESIRED-PROJECT-ID]

Configure a região padrão como us-central1. Você pode mudar para uma região diferente com suporte às configurações regionais do Spanner.

gcloud config set compute/region us-central1

Ative a API Spanner:

gcloud services enable spanner.googleapis.com

Criar a instância do Spanner

Nesta seção, você vai criar uma instância de teste sem custo financeiro ou uma instância provisionada. Neste codelab, o ID da instância do adaptador do Spanner Cassandra usado é cassandra-adapter-demo, definido como variável SPANNER_INSTANCE_ID usando a linha de comando export. Opcionalmente, você pode escolher seu próprio nome de ID de instância.

Criar uma instância de teste sem custo financeiro do Spanner

Uma instância de teste sem custo financeiro do Spanner de 90 dias está disponível para qualquer pessoa com uma Conta do Google que tenha o faturamento do Cloud ativado no projeto. Você não vai receber cobranças a menos que escolha fazer upgrade da instância de teste sem custo financeiro para uma paga. O Spanner Cassandra Adapter é compatível com a instância de teste sem custo financeiro. Se você se qualificar, crie uma instância de teste sem custo financeiro abrindo o Cloud Shell e executando este comando:

export SPANNER_INSTANCE_ID=cassandra-adapter-demo
export SPANNER_REGION=regional-us-central1
gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"

Saída de comando:

$ gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"
Creating instance...done.

Crie o banco de dados

Quando a instância estiver em execução, você poderá criar o banco de dados. O banco de dados é onde você define o esquema. Também é possível controlar quem tem acesso ao banco de dados, configurar a criptografia personalizada, configurar o otimizador e definir o período de retenção.

O banco de dados será criado na instância com o ID SPANNER_INSTANCE_ID.

Para criar um banco de dados, use a ferramenta de linha de comando gcloud:

export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID

Resposta ao comando:

$ gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID
Creating database...done.

5. Migrar o esquema e o modelo de dados do Cassandra para o Spanner

A fase inicial e crucial da transição de dados de um banco de dados do Cassandra para o Spanner envolve a transformação do esquema do Cassandra para se alinhar aos requisitos estruturais e de tipo de dados do Spanner.

Para simplificar esse processo complexo de migração de esquema, o Spanner oferece uma ferramenta de código aberto valiosa, conhecida como ferramenta de esquema do Spanner Cassandra.

Ferramenta de esquema do Spanner Cassandra

A ferramenta de esquema do Spanner Cassandra é uma ferramenta autônoma de código aberto para avaliação do Spanner e migração de esquema. A função principal dele é construir automaticamente um esquema do Spanner com base nas definições encontradas em um esquema do Cassandra. Ao analisar as estruturas de tabelas do Cassandra, os tipos de dados e as configurações de chaves primárias, a ferramenta gera definições de tabelas do Spanner equivalentes, reduzindo significativamente o esforço manual normalmente envolvido na tradução de esquemas.

Exportar esquema do Cassandra

Antes de usar a ferramenta de esquema do Spanner Cassandra, a primeira etapa concreta é extrair o esquema do cluster atual do Cassandra. Para isso, conecte-se ao cluster do Cassandra usando cqlsh e exporte o esquema do Cassandra:

cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql

Nesse comando, [IP] precisa ser substituído pelo endereço IP ou nome do host de um dos nós no cluster do Cassandra. A parte -e DESC SCHEMA do comando instrui o cqlsh a descrever todo o esquema do cluster do Cassandra. A saída desse comando, que contém as instruções CREATE KEYSPACE e CREATE TABLE, é redirecionada para um arquivo chamado orig_schema.cql.

O conteúdo desse arquivo orig_schema.cql representa essencialmente um modelo textual do seu esquema do Cassandra. O conteúdo do arquivo orig_schema.cql vai ficar assim:

CREATE KEYSPACE analytics WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}  AND durable_writes = true;

CREATE TABLE analytics.users (
    id int PRIMARY KEY,
    active boolean,
    username text
) WITH additional_write_policy = '99p'
    AND allow_auto_snapshot = true
    AND bloom_filter_fp_chance = 0.01
    AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
    AND cdc = false
    AND comment = ''
    AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
    AND compression = {'chunk_length_in_kb': '16', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
    AND memtable = 'default'
    AND crc_check_chance = 1.0
    AND default_time_to_live = 0
    AND extensions = {}
    AND gc_grace_seconds = 864000
    AND incremental_backups = true
    AND max_index_interval = 2048
    AND memtable_flush_period_in_ms = 0
    AND min_index_interval = 128
    AND read_repair = 'BLOCKING'
    AND speculative_retry = '99p';

Clone o repositório

Para usar a ferramenta de esquema do Spanner Cassandra, a próxima etapa envolve a obtenção do código-fonte da ferramenta. Isso é feito clonando o repositório hospedado no GitHub. Clone a ferramenta de esquema do Spanner Cassandra do GitHub digitando o seguinte comando no Cloud Shell:

git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git

Em seguida, mude para o diretório "spanner-cassandra-schema-tool", onde você vai executar o comando.

cd spanner-cassandra-schema-tool

Instalar dependências

A ferramenta de esquema do Spanner Cassandra é escrita na linguagem de programação Go. Para garantir que a ferramenta funcione corretamente, ela depende de alguns módulos externos do Go (bibliotecas). Essas dependências precisam ser baixadas e gerenciadas antes que você possa executar a ferramenta. No diretório spanner-cassandra-schema-tool, execute o seguinte comando:

go mod download

Configurar as credenciais do Google Cloud

Essa ferramenta usa as Application Default Credentials (ADC) como a origem de credenciais para se conectar aos bancos de dados do Spanner. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo da chave da conta de serviço.

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

Substitua /path/to/your/service-account-file.json pelo caminho real para o arquivo de chave da conta de serviço transferido por download. A definição dessa variável de ambiente garante que a ferramenta de esquema do Spanner Cassandra possa ser autenticada com segurança no seu projeto do Google Cloud e na instância do Spanner.

Uso

Depois que as dependências forem instaladas e as credenciais do Google Cloud forem configuradas, você poderá executar a ferramenta de esquema do Spanner Cassandra para gerar o esquema do Spanner a partir do arquivo de esquema do Cassandra exportado. Navegue até o diretório spanner-cassandra-schema-tool no terminal ou no Cloud Shell e execute o comando go run a seguir:

go run schema_converter.go \
    --project $PROJECT_ID \
    --instance $SPANNER_INSTANCE_ID \
    --database $SPANNER_DATABASE \
    --cql orig_schema.cql \
    --dry-run

A execução com a opção --dry-run gera apenas o esquema. Revise e refine o mapeamento de tipo de dados e as colunas de chave primária geradas pela ferramenta. Verifique se os tipos de dados do Spanner representam com precisão o intervalo, a precisão e a semântica dos tipos de banco de dados do Cassandra correspondentes.

Essa ferramenta mapeia os tipos do Cassandra para os tipos do Spanner, conforme documentado em Tipos de dados do Cassandra compatíveis.

A saída do comando vai ficar assim:

.....

[Converted Spanner statement]
CREATE TABLE users (
 id INT64 NOT NULL OPTIONS (cassandra_type = 'int'),
 active BOOL OPTIONS (cassandra_type = 'boolean'),
 username STRING(MAX) OPTIONS (cassandra_type = 'text'),
) PRIMARY KEY (id)
----------------------------------------------
Writing converted Spanner schema to: schema.txt
Dry run enabled. Skipping schema execution.
Schema conversion completed!

Caso você também queira que o esquema seja aplicado automaticamente ao Spanner, execute o cli sem a opção --dry-run.

7B2FCQSrtHfveuc.png

Verifique no console do Google Cloud se as tabelas e a tabela de metadados existem no banco de dados do Cloud Spanner.

6. Configurar gravações duplas para dados recebidos

[TODO]

7. Exportar dados históricos em massa

[TODO]

8. Valide seus dados

[TODO]

9. Apontar o aplicativo para o Spanner (mudança)

Depois de validar meticulosamente a precisão e a integridade dos dados após a fase de migração, a etapa principal é fazer a transição do foco operacional do aplicativo do sistema legados do Cassandra para o banco de dados do Google Cloud Spanner recém-preenchido. Esse período crítico de transição é comumente chamado de mudança.

A fase de transição marca o momento em que o tráfego do aplicativo ativo é redirecionado do cluster original do Cassandra e conectado diretamente à infraestrutura robusta e escalonável do Spanner. Essa transição demonstra a facilidade com que os aplicativos podem aproveitar o poder do Spanner, especialmente ao usar a interface do Spanner Cassandra.

Com a interface do Spanner Cassandra, o processo de transição é simplificado. Isso envolve principalmente a configuração dos seus aplicativos clientes para usar o cliente Spanner Cassandra nativo para todas as interações de dados. Em vez de se comunicar com o banco de dados do Cassandra (origem), os aplicativos vão começar a ler e gravar dados diretamente no Spanner (destino). Essa mudança fundamental na conectividade geralmente é alcançada pelo uso do SpannerCqlSessionBuilder, um componente-chave da biblioteca Spanner Cassandra Client que facilita o estabelecimento de conexões com a instância do Spanner. Isso redireciona todo o fluxo de tráfego de dados do aplicativo para o Spanner.

Para aplicativos Java que já usam a biblioteca cassandra-java-driver, a integração do cliente Java do Spanner Cassandra requer apenas pequenas mudanças na inicialização de CqlSession.

Como conseguir a dependência google-cloud-spanner-cassandra

Para começar a usar o cliente Spanner Cassandra, primeiro é necessário incorporar a dependência dele ao seu projeto. Os artefatos google-cloud-spanner-cassandra são publicados no Maven Central, com o ID de grupo com.google.cloud. Adicione a nova dependência abaixo à seção <dependencies> no projeto Java. Confira um exemplo simplificado de como incluir a dependência google-cloud-spanner-cassandra:

<!-- native Spanner Cassandra Client -->
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-cassandra</artifactId>
    <version>0.2.0</version>
  </dependency>
</dependencies>

Mudar a configuração de conexão para se conectar ao Spanner

Depois de adicionar a dependência necessária, a próxima etapa é mudar a configuração da conexão para se conectar ao banco de dados do Spanner.

Um aplicativo típico que interage com um cluster do Cassandra geralmente emprega um código semelhante ao seguinte para estabelecer uma conexão:

CqlSession session = CqlSession.builder()
        .addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
        .withLocalDatacenter("datacenter1")
        .withAuthCredentials("username", "password")
        .build();

Para redirecionar essa conexão ao Spanner, é necessário modificar a lógica de criação de CqlSession. Em vez de usar diretamente o CqlSessionBuilder padrão do cassandra-java-driver, use o SpannerCqlSession.builder() fornecido pelo cliente Spanner Cassandra. Confira um exemplo ilustrativo de como modificar o código de conexão:

String databaseUri = "projects/<your-gcp-project>/instances/<your-spanner-instance>/databases/<your-spanner-database>";

CqlSession session = SpannerCqlSession.builder()
        .setDatabaseUri(databaseUri)
        .addContactPoint(new InetSocketAddress("localhost", 9042))
        .withLocalDatacenter("datacenter1")
        .build();

Ao instanciar o CqlSession usando SpannerCqlSession.builder() e fornecer o databaseUri correto, seu aplicativo vai estabelecer uma conexão pelo cliente Spanner Cassandra com o banco de dados de destino do Spanner. Essa mudança fundamental garante que todas as operações de leitura e gravação subsequentes realizadas pelo seu aplicativo sejam direcionadas e atendidas pelo Spanner, concluindo efetivamente a transição inicial. Nesse ponto, o aplicativo deve continuar funcionando conforme o esperado, agora com a escalabilidade e a confiabilidade do Spanner.

Under the Hood: How the Spanner Cassandra Client Operates

O cliente Spanner Cassandra atua como um proxy TCP local, interceptando os bytes brutos do protocolo Cassandra enviados por um driver ou uma ferramenta de cliente. Em seguida, ele agrupa esses bytes com os metadados necessários em mensagens gRPC para comunicação com o Spanner. As respostas do Spanner são convertidas de volta para o formato de transmissão do Cassandra e enviadas de volta para o driver ou a ferramenta de origem.

26D34akkBHcMFFe.png

Quando tiver certeza de que o Spanner está veiculando todo o tráfego corretamente, você poderá:

  • Pare as gravações duplas.
  • Desative o cluster original do Cassandra.

10. Limpeza (opcional)

Para limpar, acesse a seção Spanner do Console do Cloud e exclua a instância cassandra-adapter-demo que criamos no codelab.

76D34akkJRcMFMr.png

Excluir o banco de dados Cassandra (se instalado localmente ou persistido)

Se você instalou o Cassandra fora de uma VM do Compute Engine criada aqui, siga as etapas adequadas para remover os dados ou desinstalar o Cassandra.

11. Parabéns!

A seguir