Usar o cliente Go do Cassandra para se conectar ao Spanner Omni

O cliente Go do Cassandra para Spanner conecta aplicativos escritos para o banco de dados Apache Cassandra com o Spanner. O cliente trabalha com o Spanner Omni da mesma forma que trabalha com o Spanner. Como o Spanner oferece suporte nativo ao protocolo de transmissão do Cassandra v4, esse cliente permite que aplicativos Go que usam o driver gocql ou aplicativos e ferramentas que não são Go, como cqlsh, se conectem a um banco de dados do Spanner.

Esse cliente funciona como um proxy TCP local. Ele intercepta os bytes brutos do protocolo Cassandra que um driver ou uma ferramenta cliente envia. Em seguida, ele encapsula esses bytes e os metadados necessários em mensagens gRPC para se comunicar com o Spanner Omni. O cliente traduz as respostas do Spanner Omni de volta para o formato de fio do Cassandra e as envia de volta para o driver ou ferramenta de origem.

Este documento mostra como integrar o cliente ao Spanner Omni usando um dos seguintes métodos:

  • Dependência no processo: use esse método para aplicativos Go que já usam o driver gocql. Essa abordagem incorpora o cliente ao processo do aplicativo para modificações mínimas no código.

  • Proxy sidecar: use esse método para aplicativos que não são Go ou ao usar ferramentas externas do Cassandra, como cqlsh. Essa abordagem executa o cliente como um processo independente.

Para mais informações sobre como o Apache Cassandra funciona com o Spanner, consulte a interface do Cassandra.

Quando usar o cliente Go do Spanner Cassandra

Esse cliente é útil nos seguintes cenários:

  • Use o Spanner com refatoração mínima. Você quer usar o Spanner como back-end do seu aplicativo Go, mas prefere continuar usando a API gocql para acesso aos dados.

  • Use ferramentas do Cassandra que não são do Go. Você quer se conectar ao Spanner usando ferramentas padrão do Cassandra, como cqlsh, ou aplicativos escritos em outras linguagens que usam drivers do Cassandra.

Usar o cliente como uma dependência no processo

Os aplicativos Go se conectam ao Spanner Omni integrando o cliente Go do Spanner Cassandra como uma dependência no processo. Essa abordagem incorpora a lógica de proxy diretamente no aplicativo, o que simplifica a arquitetura de implantação, removendo a necessidade de um processo separado. Essa configuração também oferece performance ideal, evitando um salto de rede extra e serialização e desserialização extras dos dados.

Para usar o cliente como uma dependência no processo, faça o seguinte:

  • Importe o pacote do Spanner no seu aplicativo Go:

    import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"

  • Modifique o código de criação do cluster. Em vez de usar gocql.NewCluster, use spanner.NewCluster e forneça as seguintes opções específicas do Spanner Omni:

    Texto simples

    O exemplo a seguir mostra como estabelecer uma conexão de texto simples com o Spanner Omni:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.UsePlainText = true

  cluster := spanner.NewCluster(opts)
  // ...
}

    TLS

    O exemplo a seguir mostra como estabelecer uma conexão TLS com o Spanner Omni:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"

  cluster := spanner.NewCluster(opts)
  // ...
}

    mTLS

    O exemplo a seguir mostra como estabelecer uma conexão mTLS com o Spanner Omni:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

  cluster := spanner.NewCluster(opts)
  // ...
}

    Substitua:

    • DATABASE_ID: o ID do banco de dados do Spanner Omni. Por exemplo, test-db.

    • ENDPOINT: o endpoint da sua instância do Spanner Omni, por exemplo, localhost:15000.

    • PATH_TO_CA_CRT: o caminho para o arquivo de certificado de CA.

    • PATH_TO_CLIENT_CERT: o caminho para o arquivo de certificado do cliente.

    • PATH_TO_CLIENT_KEY: o caminho para o arquivo da chave do cliente.

Implantar o cliente como um proxy secundário

Implantar o cliente Go do Spanner Cassandra como um proxy sidecar é uma opção eficaz para aplicativos e ferramentas que não são Go, como cqlsh, para se conectar ao Spanner Omni usando drivers padrão do Cassandra. Esse método executa o cliente como um proxy TCP independente que intercepta o tráfego do protocolo de transmissão do Cassandra e o converte em gRPC para comunicação com o Spanner Omni.

Essa configuração é útil quando você precisa usar ferramentas externas do Cassandra ou evitar fazer modificações diretas no código do aplicativo.

É possível executar o proxy sidecar das seguintes maneiras:

Executar localmente com o comando run do Go

Executar o proxy sidecar como um processo local do código-fonte é útil para ambientes de desenvolvimento e teste em que você quer iterar rapidamente no aplicativo e na configuração de proxy.

  1. Clone o repositório:

    git clone https://github.com/googleapis/go-spanner-cassandra.git

  2. Altere para o diretório do repositório:

    cd go-spanner-cassandra

  3. Execute cassandra_launcher.go com a flag -db obrigatória e as seguintes flags específicas do Spanner Omni:

    Texto simples

    Para executar com comunicação de texto simples, execute o seguinte comando:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -usePlainText

    TLS

    Para executar com uma conexão TLS, execute o seguinte comando:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

    Para executar com uma conexão mTLS, execute o seguinte comando:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

Executar com uma imagem Docker pré-criada

Recomendamos executar o proxy sidecar como um aplicativo contêinerizado usando uma imagem Docker pré-criada para ambientes de produção, porque ele oferece um ambiente de execução consistente e isolado.

  1. Extraia a imagem do repositório oficial do registro:

    docker pull gcr.io/cloud-spanner-adapter/cassandra-adapter

  2. Execute a imagem com as flags necessárias:

    Texto simples

    Para executar com comunicação de texto simples, execute o seguinte comando:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -usePlainText

    TLS

    Para executar com uma conexão TLS, execute o seguinte comando:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

    Para executar com uma conexão mTLS, execute o seguinte comando:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY