Conectarse a Spanner mediante el adaptador de Cassandra

En esta página se describe el adaptador de Cassandra y se explica cómo usarlo y conectar Spanner desde él.

El adaptador de Cassandra se ha diseñado para ejecutarse en la misma máquina que tu aplicación. El adaptador expone un endpoint en localhost que admite el protocolo de conexión de Cassandra Query Language (CQL). Traduce el protocolo de conexión de CQL a gRPC, el protocolo de conexión de Spanner. Con este proxy ejecutándose de forma local, un cliente de Cassandra puede conectarse a una base de datos de Spanner.

Puedes iniciar el adaptador de Cassandra de las siguientes formas:

  • En el proceso de tu aplicación Go
  • En el proceso de tu aplicación Java
  • Como proceso independiente
  • En un contenedor Docker

Antes de empezar

Antes de iniciar el adaptador de Cassandra, asegúrate de que te has autenticado con una cuenta de usuario o una cuenta de servicio en la máquina en la que se ejecutará el adaptador de Cassandra. Si utilizas una cuenta de servicio, debes saber la ubicación del archivo de clave JSON (el archivo de credenciales). Define la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para especificar la ruta de las credenciales.

Para obtener más información, consulta estos artículos:

Conectar el adaptador de Cassandra a tu aplicación

El adaptador de Cassandra requiere la siguiente información:

  • Nombre del proyecto
  • Nombre de la instancia de Spanner
  • Base de datos a la que conectarse

Si usas Docker, necesitas la ruta de un archivo de credenciales con formato JSON (archivo de clave).

Java en proceso

  1. Si usas una cuenta de servicio para la autenticación, asegúrate de que la variable de entorno GOOGLE_APPLICATION_CREDENTIALS esté definida en la ruta del archivo de credenciales.

  2. En el caso de las aplicaciones Java, puedes vincular el adaptador de Cassandra directamente a la aplicación añadiendo google-cloud-spanner-cassandra como dependencia a tu proyecto.

En Maven, añade la siguiente dependencia nueva en la sección <dependencies>: 

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

En Gradle, añade lo siguiente: 

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

  1. Modifique el CqlSession código de creación. En lugar de usar CqlSessionBuilder, usa SpannerCqlSessionBuilder y proporciona el URI de la base de datos de 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();
    }
  }
}

Ir en proceso

En el caso de las aplicaciones Go, debes hacer un cambio de una línea en el archivo de inicialización del clúster para integrar el cliente Go de Spanner Cassandra. Después, puede vincular el adaptador de Cassandra directamente a la aplicación.

  1. Importa el paquete spanner del adaptador del cliente de Go de Spanner Cassandra en tu aplicación Go.
import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"
  1. Modifica el código de creación del clúster para usar spanner.NewCluster en lugar de gocql.NewCluster y proporciona el URI de la base de datos de 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
}

Puedes configurar tu clúster como de costumbre después de conectarte a tu base de datos de Spanner.

Independiente

  1. Clona el repositorio:
git clone https://github.com/googleapis/go-spanner-cassandra.git
cd go-spanner-cassandra
  1. Ejecuta cassandra_launcher.go con la marca -db obligatoria:
go run cassandra_launcher.go \
-db "projects/my_project/instances/my_instance/databases/my_database"
  1. Sustituye -db por el URI de tu base de datos de Spanner.

Docker

Inicia el adaptador de Cassandra con el siguiente 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

La siguiente lista contiene las opciones de inicio más utilizadas para el adaptador de Spanner Cassandra:

  • -db <DatabaseUri>

El URI de la base de datos de Spanner (obligatorio). Especifica la base de datos de Spanner a la que se conecta el cliente. Por ejemplo, projects/YOUR_PROJECT/instances/YOUR_INSTANCE/databases/YOUR_DATABASE.

  • -tcp <TCPEndpoint>

Dirección del receptor proxy del cliente. Define el endpoint TCP en el que el cliente escucha las conexiones de cliente de Cassandra entrantes. Valor predeterminado:localhost:9042

  • -grpc-channels <NumGrpcChannels>

Número de canales gRPC que se van a usar al conectarse a Spanner. Valor predeterminado: 4

Por ejemplo, el siguiente comando inicia el adaptador de Cassandra en el puerto 9042 con las credenciales de la aplicación y conecta el adaptador a la base de datos 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

Recomendaciones

Las siguientes recomendaciones te ayudarán a mejorar tu experiencia con el adaptador de Cassandra. Estas recomendaciones se centran en Java, concretamente en el controlador de cliente de Cassandra para Java versión 4.

Aumentar el tiempo de espera de las solicitudes

Un tiempo de espera de cinco segundos o más ofrece una mejor experiencia con el adaptador de Cassandra que el valor predeterminado de dos segundos.

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

Ajustar el grupo de conexiones

Las configuraciones predeterminadas del número máximo de conexiones y del número máximo de solicitudes simultáneas por conexión o host son adecuadas para entornos de desarrollo, pruebas y producción o de staging de bajo volumen. Sin embargo, te recomendamos que aumentes estos valores, ya que el adaptador de Cassandra se hace pasar por un solo nodo, a diferencia de un conjunto de nodos de un clúster de Cassandra.

Si aumentas estos valores, se podrán establecer más conexiones simultáneas entre el cliente y la interfaz de Cassandra. De esta forma, se puede evitar que se agote el grupo de conexiones cuando haya mucha carga.

# 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
  }
}

Ajustar canales gRPC

El cliente de Spanner usa canales gRPC para comunicarse. Un canal gRPC equivale aproximadamente a una conexión TCP. Un canal gRPC puede gestionar hasta 100 solicitudes simultáneas. Esto significa que una aplicación necesitará al menos tantos canales gRPC como el número de solicitudes simultáneas que vaya a ejecutar, dividido entre 100.

Inhabilitar el enrutamiento con tokens

Es posible que los controladores que usan el balanceo de carga con reconocimiento de tokens muestren una advertencia o no funcionen al usar el adaptador de Cassandra. Como el adaptador de Cassandra se hace pasar por un solo nodo, no siempre funciona bien con controladores que reconocen tokens y que esperan que haya al menos un número de nodos igual al factor de replicación en el clúster. Algunos controladores pueden imprimir una advertencia (que se puede ignorar) y recurrir a algo parecido a una política de balanceo de carga de tipo round-robin, mientras que otros pueden fallar y mostrar un error. En el caso de los controladores que fallen con un error, debes inhabilitar la opción de reconocimiento de tokens o configurar la política de balanceo de carga de asignación cíclica.

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

Fijar la versión del protocolo en V4

El adaptador de Cassandra es compatible con cualquier controlador de cliente de Apache Cassandra de código abierto que cumpla el protocolo de conexión binario v4 de CQL. Asegúrate de fijar PROTOCOL_VERSION a V4. De lo contrario, es posible que se produzcan errores de conexión.

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

Siguientes pasos