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 rede 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 atua como um proxy TCP local. Ele intercepta os bytes brutos do protocolo do Cassandra enviados por um driver ou uma ferramenta cliente. 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 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 a 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 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:

    Comunicação em 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.ExperimentalHost = true
  opts.UsePlainText = true

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

    Conexão 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.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"

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

    Conexão 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.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

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

Implantar o cliente como um proxy sidecar

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, se conectarem 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 rede 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 na configuração do aplicativo e do 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. Substitua o valor de -db pelo nome do banco de dados do Spanner Omni:

  • Para comunicação em texto simples, execute o seguinte:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • Para uma conexão TLS, execute o seguinte:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • Para uma conexão mTLS, execute o seguinte:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

Executar com uma imagem do Docker predefinida

Recomendamos executar o proxy sidecar como um aplicativo em contêiner 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:

    Comunicação em texto simples

    Para comunicação em texto simples, execute o seguinte comando:

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

    Conexão TLS

    Para 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 -experimentalHost -caCertificate PATH_TO_CA_CRT

    Conexão mTLS

    Para 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 -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY