Usa el cliente de Java de Cassandra para conectarte a Spanner Omni

El cliente de Java de Cassandra para Spanner conecta las aplicaciones escritas para la base de datos de Apache Cassandra con Spanner. El cliente funciona con Spanner Omni de la misma manera que con Spanner.

Como Spanner admite de forma nativa el protocolo de conexión de Cassandra v4, el cliente de Java de Cassandra de Spanner traduce el protocolo de conexión de Cassandra a la API de gRPC de Spanner. Esto te permite migrar tus aplicaciones de Cassandra a Spanner con cambios mínimos en el código.

En este documento, se muestra cómo integrar el cliente con Spanner Omni mediante uno de los siguientes métodos:

Para obtener más información, consulta la interfaz de Cassandra en la documentación de Spanner.

Cuándo usar el cliente de Java de Cassandra de Spanner

Este cliente es útil en las siguientes situaciones:

  • Usa Spanner con una refactorización mínima. Quieres usar Spanner como backend para tu aplicación de Java, pero prefieres seguir usando la API de cassandra-java-driver familiar para el acceso a los datos.

  • Usa herramientas de Cassandra que no sean de Java. Quieres conectarte a Spanner con herramientas estándar de Cassandra, como cqlsh, o aplicaciones escritas en otros lenguajes que usan controladores de Cassandra.

Usa el cliente como una dependencia en el proceso

Integrar el cliente de Java de Cassandra de Spanner como una dependencia en el proceso es el método recomendado para que las aplicaciones de Java se conecten a Spanner Omni. En comparación con el método de proxy de sidecar, la configuración en el proceso proporciona un mejor rendimiento, ya que evita un salto de red adicional y la serialización y deserialización de datos asociadas. También simplifica la arquitectura de implementación, ya que elimina la necesidad de administrar un proceso independiente.

Para usar el cliente como una dependencia en el proceso, haz lo siguiente:

  1. Modifica el código de creación de CqlSession y agrega las opciones específicas de comunicación de Spanner Omni.

  2. Agrega el cliente de Java de Cassandra de Spanner como una dependencia a tu proyecto.

    Comunicación de texto simple

    En el siguiente ejemplo, se muestra cómo establecer una conexión de texto simple a Spanner Omni:

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(true)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    Conexión TLS

    Para usar una conexión TLS, asegúrate de que el certificado de la AC se agregue al almacén de certificados de confianza que usa la aplicación, como se menciona en las instrucciones de TLS del SDK de Java:

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    Conexión mTLS

    Para usar una conexión mTLS, asegúrate de que el certificado de la AC se agregue al almacén de certificados de confianza que usa la aplicación y que la clave del cliente esté en formato PKCS#8, como se menciona en las instrucciones de mTLS del SDK de Java:

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
  .useClientCert("PATH_TO_CLIENT_CERT",
          "PATH_TO_CLIENT_KEY_PKCS8")

        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

Proxy sidecar o proceso independiente

Implementar el cliente de Java de Cassandra de Spanner como un proxy de sidecar es una opción eficaz para que las aplicaciones y herramientas que no son de Java, como cqlsh, se conecten a Spanner Omni con controladores estándar de Cassandra. Este método ejecuta el cliente como un proxy TCP independiente que intercepta el tráfico del protocolo de conexión de Cassandra y lo traduce a gRPC para la comunicación con Spanner Omni.

Puedes ejecutar el proxy de sidecar con un archivo de configuración YAML o especificando propiedades del sistema.

Usa un archivo de configuración YAML

Para las configuraciones de producción, te recomendamos que uses un archivo YAML para configurar el adaptador. Este método admite varios objetos de escucha y configuración global:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

Ejemplo de config.yaml:

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  experimentalHostEndpoint: "ENDPOINT"
  clientCertPath: "PATH_TO_CLIENT_CERT"
  clientKeyPath: "PATH_TO_CLIENT_KEY_PKCS8"
  usePlainText: "false"

listeners:
  - name: "listener_1"
    host: "127.0.0.1"
    port: 9042
    spanner:
      databaseUri: "DATABASE_ID"
      numGrpcChannels: 4
      maxCommitDelayMillis: 5
  - name: "listener_2"
    host: "127.0.0.2"
    port: 9043
    spanner:
      databaseUri: "DATABASE_ID_2"
      numGrpcChannels: 8

Usa propiedades del sistema

Para un solo objeto de escucha o implementaciones más simples, puedes ejecutar el proxy de sidecar como un proceso independiente y configurar sus parámetros con las propiedades del sistema de Java.

Para un solo objeto de escucha, puedes usar propiedades del sistema. En los siguientes ejemplos, se muestra cómo ejecutar el proxy de sidecar como un proceso independiente para cada modo de seguridad compatible:

Comunicación de texto simple

Para la comunicación de texto simple, ejecuta lo siguiente:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

Conexión TLS

Para una conexión TLS, ejecuta lo siguiente:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-jar PATH_TO_ADAPTER_JAR

Conexión mTLS

Para una conexión mTLS, ejecuta lo siguiente:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DclientCertPath=PATH_TO_CLIENT_CERT \
-DclientKeyPath=PATH_TO_CLIENT_KEY_PKCS8 \
-jar PATH_TO_ADAPTER_JAR