Estabeleça ligação ao Spanner através do adaptador do Cassandra

Esta página descreve o adaptador do Cassandra e explica como usar e associar o Spanner a partir dele.

O adaptador do Cassandra foi concebido para ser executado na mesma máquina que a sua aplicação. O adaptador expõe um ponto final no localhost que suporta o protocolo de rede do idioma de consulta do Cassandra (CQL). Traduz o protocolo de rede CQL em gRPC, o protocolo de rede Spanner. Com este proxy em execução local, um cliente do Cassandra pode estabelecer ligação a uma base de dados do Spanner.

Pode iniciar o adaptador do Cassandra das seguintes formas:

  • Em processamento com a sua aplicação Go
  • No processo com a sua aplicação Java
  • Como um processo autónomo
  • Num contentor Docker

Antes de começar

Antes de iniciar o adaptador do Cassandra, certifique-se de que fez a autenticação com uma conta de utilizador ou uma conta de serviço no computador onde o adaptador do Cassandra vai ser executado. Se estiver a usar uma conta de serviço, tem de saber a localização do ficheiro de chave JSON (o ficheiro de credenciais). Define a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para especificar o caminho das credenciais.

Para mais informações, consulte:

Associe o adaptador do Cassandra à sua aplicação

O adaptador do Cassandra requer as seguintes informações:

  • Nome do projeto
  • Nome da instância do Spanner
  • Base de dados à qual se associar

Se usar o Docker, precisa do caminho para um ficheiro de credenciais formatado em JSON (ficheiro de chave).

Java no processo

  1. Se estiver a usar uma conta de serviço para autenticação, certifique-se de que a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está definida para o caminho do ficheiro de credenciais.

  2. Para aplicações Java, pode associar o adaptador do Cassandra diretamente à aplicação adicionando google-cloud-spanner-cassandra como uma dependência ao seu projeto.

Para o Maven, adicione a seguinte nova dependência na secção <dependencies>: 

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-spanner-cassandra</artifactId>
    <version>0.7.0</version>
</dependency>

Para o Gradle, adicione o seguinte: 

dependencies {
    implementation 'com.google.cloud:google-cloud-spanner-cassandra:0.7.0'
}

  1. Modifique o CqlSessioncódigo de criação. Em vez de usar CqlSessionBuilder, use SpannerCqlSessionBuilder e forneça o URI da base de dados do Spanner: 
    
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.config.DefaultDriverOption;
import com.datastax.oss.driver.api.core.config.DriverConfigLoader;
import com.datastax.oss.driver.api.core.cql.ResultSet;
import com.datastax.oss.driver.api.core.cql.Row;
import com.google.cloud.spanner.adapter.SpannerCqlSession;
import java.net.InetSocketAddress;
import java.time.Duration;
import java.util.Random;

// This sample assumes your spanner database <my_db> contains a table <users>
// with the following schema:

// CREATE TABLE users (
//  id        INT64          OPTIONS (cassandra_type = 'int'),
//  active    BOOL           OPTIONS (cassandra_type = 'boolean'),
//  username  STRING(MAX)    OPTIONS (cassandra_type = 'text'),
// ) PRIMARY KEY (id);

class QuickStartSample {

  public static void main(String[] args) {

    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "my-gcp-project";
    final String instanceId = "my-spanner-instance";
    final String databaseId = "my_db";

    final String databaseUri =
        String.format("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId);

    try (CqlSession session =
        SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
            .setDatabaseUri(databaseUri) // Set spanner database URI.
            .addContactPoint(new InetSocketAddress("localhost", 9042))
            .withLocalDatacenter("datacenter1")
            .withKeyspace(databaseId) // Keyspace name should be the same as spanner database name
            .withConfigLoader(
                DriverConfigLoader.programmaticBuilder()
                    .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                    .withDuration(
                        DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT, Duration.ofSeconds(5))
                    .build())
            .build()) {

      final int randomUserId = new Random().nextInt(Integer.MAX_VALUE);

      System.out.printf("Inserting user with ID: %d%n", randomUserId);

      // INSERT data
      session.execute(
          "INSERT INTO users (id, active, username) VALUES (?, ?, ?)",
          randomUserId,
          true,
          "John Doe");

      System.out.printf("Successfully inserted user: %d%n", randomUserId);
      System.out.printf("Querying user: %d%n", randomUserId);

      // SELECT data
      ResultSet rs =
          session.execute("SELECT id, active, username FROM users WHERE id = ?", randomUserId);

      // Get the first row from the result set
      Row row = rs.one();

      System.out.printf(
          "%d %b %s%n", row.getInt("id"), row.getBoolean("active"), row.getString("username"));

    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Aceda ao processo

Para aplicações Go, tem de fazer uma alteração de uma linha ao ficheiro de inicialização do cluster para integrar o cliente Go do Spanner Cassandra. Em seguida, pode associar o adaptador do Cassandra diretamente à aplicação.

  1. Importe o pacote spanner do adaptador do cliente Go do Spanner Cassandra na sua aplicação Go.
import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"
  1. Modifique o código de criação do cluster para usar spanner.NewCluster em vez de gocql.NewCluster e forneça o URI da base de dados do Spanner: 
    import (
	"fmt"
	"io"
	"math"
	"math/rand/v2"
	"time"

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

// This sample assumes your spanner database <your_db> contains a table <users>
// with the following schema:
//
// CREATE TABLE users (
//	id   	 	INT64          OPTIONS (cassandra_type = 'int'),
//	active    	BOOL           OPTIONS (cassandra_type = 'boolean'),
//	username  	STRING(MAX)    OPTIONS (cassandra_type = 'text'),
// ) PRIMARY KEY (id);

func quickStart(databaseURI string, w io.Writer) error {
	opts := &spanner.Options{
		DatabaseUri: databaseURI,
	}
	cluster := spanner.NewCluster(opts)
	if cluster == nil {
		return fmt.Errorf("failed to create cluster")
	}
	defer spanner.CloseCluster(cluster)

	// You can still configure your cluster as usual after connecting to your
	// spanner database
	cluster.Timeout = 5 * time.Second
	cluster.Keyspace = "your_db_name"

	session, err := cluster.CreateSession()

	if err != nil {
		return err
	}

	randomUserId := rand.IntN(math.MaxInt32)
	if err = session.Query("INSERT INTO users (id, active, username) VALUES (?, ?, ?)",
			       randomUserId, true, "John Doe").
		Exec(); err != nil {
		return err
	}

	var id int
	var active bool
	var username string
	if err = session.Query("SELECT id, active, username FROM users WHERE id = ?",
			       randomUserId).
		Scan(&id, &active, &username); err != nil {
		return err
	}
	fmt.Fprintf(w, "%d %v %s\n", id, active, username)
	return nil
}

Pode configurar o cluster como habitualmente depois de se ligar à base de dados do Spanner.

Autónomo

  1. Clone o repositório:
git clone https://github.com/googleapis/go-spanner-cassandra.git
cd go-spanner-cassandra
  1. Execute o comando cassandra_launcher.go com a flag -db necessária:
go run cassandra_launcher.go \
-db "projects/my_project/instances/my_instance/databases/my_database"
  1. Substitua -db pelo URI da sua base de dados do Spanner.

Docker

Inicie o adaptador do Cassandra com o seguinte comando.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
docker run -d -p 9042:9042 \
-e GOOGLE_APPLICATION_CREDENTIALS \
-v ${GOOGLE_APPLICATION_CREDENTIALS}:${GOOGLE_APPLICATION_CREDENTIALS}:ro \
gcr.io/cloud-spanner-adapter/cassandra-adapter \
-db DATABASE_URI

A lista seguinte contém as opções de arranque mais usadas para o adaptador do Spanner Cassandra:

  • -db <DatabaseUri>

O URI da base de dados do Spanner (obrigatório). Isto especifica a base de dados do Spanner à qual o cliente se liga. Por exemplo, projects/YOUR_PROJECT/instances/YOUR_INSTANCE/databases/YOUR_DATABASE.

  • -tcp <TCPEndpoint>

O endereço do ouvinte do proxy do cliente. Isto define o ponto final TCP onde o cliente ouve as ligações de clientes Cassandra recebidas. Predefinição:localhost:9042

  • -grpc-channels <NumGrpcChannels>

O número de canais gRPC a usar ao estabelecer ligação ao Spanner. Predefinição: 4

Por exemplo, o comando seguinte inicia o adaptador do Cassandra na porta 9042 com as credenciais da aplicação e liga o adaptador à base de dados projects/my_project/instances/my_instance/databases/my_database:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
docker run -d -p 9042:9042 \
-e GOOGLE_APPLICATION_CREDENTIALS \
-v ${GOOGLE_APPLICATION_CREDENTIALS}:${GOOGLE_APPLICATION_CREDENTIALS}:ro \
gcr.io/cloud-spanner-adapter/cassandra-adapter \
-db projects/my_project/instances/my_instance/databases/my_database

Recomendações

As seguintes recomendações ajudam a melhorar a sua experiência com o adaptador do Cassandra. Estas recomendações focam-se no Java, especificamente no controlador do cliente Cassandra para a versão 4 do Java.

Aumente o tempo limite de pedido

Um limite de tempo de pedido de cinco segundos ou mais oferece uma melhor experiência com o adaptador do Cassandra do que o valor predefinido de dois segundos.

# Sample application.conf: increases request timeout to five seconds
datastax-java-driver {
  basic {
    request {
      timeout = 5 seconds
    }
  }
}

Ajuste o conjunto de ligações

As configurações predefinidas para o número máximo de ligações e o número máximo de pedidos simultâneos por ligação ou anfitrião são adequadas para ambientes de desenvolvimento, testes e produção ou preparação de baixo volume. No entanto, recomendamos que aumente estes valores, uma vez que o adaptador do Cassandra faz-se passar por um único nó, ao contrário de um conjunto de nós no cluster do Cassandra.

O aumento destes valores permite mais ligações simultâneas entre o cliente e a interface do Cassandra. Isto pode evitar o esgotamento do conjunto de ligações sob carga elevada.

# Sample application.conf: increases maximum number of requests that can be
# executed concurrently on a connection
advanced.connection {
  max-requests-per-connection = 32000
  pool {
    local.size = 10
  }
}

Ajuste os canais gRPC

Os canais gRPC são usados pelo cliente do Spanner para comunicação. Um canal gRPC é aproximadamente equivalente a uma ligação TCP. Um canal gRPC pode processar até 100 pedidos simultâneos. Isto significa que uma aplicação precisa de, pelo menos, tantos canais gRPC quanto o número de pedidos concorrentes que a aplicação vai executar, dividido por 100.

Desative o encaminhamento com reconhecimento de tokens

Os controladores que usam o equilíbrio de carga com reconhecimento de tokens podem imprimir um aviso ou podem não funcionar quando usam o adaptador do Cassandra. Uma vez que o adaptador do Cassandra se faz passar por um único nó, o adaptador do Cassandra nem sempre funciona bem com controladores com reconhecimento de tokens que esperam que exista, pelo menos, um número de nós de fator de replicação no cluster. Alguns controladores podem imprimir um aviso (que pode ser ignorado) e usar uma alternativa, como a política de equilíbrio de round robin, enquanto outros controladores podem falhar com um erro. Para os controladores que falham com um erro, tem de desativar a opção de reconhecimento de tokens ou configurar a política de equilíbrio de carga rotativo.

# Sample application.conf: disables token-aware routing
metadata {
  token-map {
    enabled = false
  }
}

Fixe a versão do protocolo na V4

O adaptador do Cassandra é compatível com qualquer controlador de cliente do Apache Cassandra de código aberto compatível com o protocolo de rede binário v4 do CQL. Certifique-se de que fixa PROTOCOL_VERSION a V4. Caso contrário, pode ver erros de ligação.

# Sample application.conf: overrides protocol version to V4
datastax-java-driver {
  advanced.protocol.version = V4
}

O que se segue?