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

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

Dado que Spanner admite de forma nativa el protocolo de conexión de Cassandra v4, el cliente de Java de Spanner Cassandra 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 usando uno de los siguientes métodos:

  • Dependencia en el proceso: Usa este método para las aplicaciones de Java que ya usan cassandra-java-driver. Este enfoque incorpora el cliente en el proceso de la aplicación para realizar modificaciones mínimas en el código.

  • Proxy sidecar: Usa este método para aplicaciones que no son de Java o cuando usas herramientas externas de Cassandra, como cqlsh. Este enfoque ejecuta el cliente como un proceso independiente.

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

Cuándo usar el cliente de Spanner Cassandra Java

Este cliente es útil en las siguientes situaciones:

  • Usar Spanner con una refactorización mínima Deseas usar Spanner como backend para tu aplicación de Java, pero prefieres seguir usando la API de cassandra-java-driver que ya conoces para acceder a los datos.

  • Usa herramientas de Cassandra que no sean de Java. Deseas conectarte a Spanner con herramientas estándar de Cassandra, como cqlsh, o con 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 Spanner Cassandra 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 integrada 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 tu 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 tu código de creación de CqlSession y agrega las opciones específicas de la comunicación de Spanner Omni.

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

    Comunicación de texto sin formato

    En el siguiente ejemplo, se muestra cómo establecer una conexión de texto sin formato con 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 haya agregado 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 de 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 Spanner Cassandra como un proxy de sidecar es una opción eficaz para las aplicaciones y herramientas que no son de Java, como cqlsh, para conectarse 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 cable 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 parámetros de configuración globales:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

Ejemplo 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

Cómo usar las 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 sin formato

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