Conéctate a Spanner con el adaptador de Cassandra

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

El adaptador de Cassandra está diseñado para ejecutarse en la misma máquina que tu aplicación. El adaptador expone un extremo en localhost que admite el protocolo de cable de Cassandra Query Language (CQL). Traduce el protocolo de transferencia de CQL a gRPC, el protocolo de transferencia 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 maneras:

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

Antes de comenzar

Antes de iniciar el adaptador de Cassandra, asegúrate de haberte 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 usas una cuenta de servicio, debes conocer la ubicación del archivo de claves JSON (el archivo de credenciales). Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para especificar la ruta de acceso a las credenciales.

Para obtener más información, consulte:

Conecta 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 se conectará

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

Java in-process

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

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

En Maven, agrega la siguiente dependencia nueva en la sección <dependencies>: 

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

En Gradle, agrega lo siguiente: 

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

  1. Modifica tu código de creación de CqlSession. 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();
    }
  }
}

Pasa a la etapa de procesamiento

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

  1. Importa el paquete spanner del adaptador desde el cliente de Go de Spanner Cassandra en tu aplicación de 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 requerida:
go run cassandra_launcher.go \
-db "projects/my_project/instances/my_instance/databases/my_database"
  1. Reemplaza -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

En la siguiente lista, se incluyen las opciones de inicio que se usan con mayor frecuencia para el adaptador de Cassandra de Spanner:

  • -db <DatabaseUri>

Es 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>

Es la dirección del objeto de escucha del proxy del cliente. Define el extremo TCP en el que el cliente escucha las conexiones entrantes del cliente de Cassandra. Valor predeterminado:localhost:9042

  • -grpc-channels <NumGrpcChannels>

Es la cantidad de canales de gRPC que se usarán cuando se conecte 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, específicamente en el controlador de cliente de Cassandra para Java versión 4.

Aumenta el tiempo de espera de la solicitud

Un tiempo de espera de la solicitud de cinco segundos o más proporciona 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
    }
  }
}

Ajusta la agrupación de conexiones

Los parámetros de configuración predeterminados para la cantidad máxima de conexiones y la cantidad máxima de solicitudes simultáneas por conexión o host son adecuados para los entornos de desarrollo, pruebas y producción de bajo volumen o de etapa de pruebas. 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 grupo de nodos dentro del clúster de Cassandra.

Aumentar estos valores permite más conexiones simultáneas entre el cliente y la interfaz de Cassandra. Esto puede evitar el agotamiento del grupo de conexiones en condiciones de carga pesada.

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

Ajusta los canales de gRPC

El cliente de Spanner usa canales gRPC para la comunicación. Un canal de gRPC equivale aproximadamente a una conexión TCP. Un canal de gRPC puede controlar hasta 100 solicitudes simultáneas. Esto significa que una aplicación necesitará al menos tantos canales de gRPC como la cantidad de solicitudes simultáneas que ejecutará, dividida por 100.

Inhabilita el enrutamiento que tiene en cuenta el token

Es posible que los controladores que usan el balanceo de cargas compatible con tokens impriman una advertencia o no funcionen cuando se usa el adaptador de Cassandra. Dado que el adaptador de Cassandra se hace pasar por un solo nodo, no siempre funciona bien con los controladores que tienen conocimiento de los tokens y que esperan que haya al menos una cantidad 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 una política de equilibrio de carga de tipo round-robin, mientras que otros pueden fallar con un error. En el caso de los controladores que fallan con un error, debes inhabilitar la opción de reconocimiento de tokens o configurar la política de balanceo de cargas round-robin.

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

Fija 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 con el protocolo de cable CQL binario v4. Asegúrate de fijar PROTOCOL_VERSION a V4; de lo contrario, es posible que veas errores de conexión.

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

¿Qué sigue?