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 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 con 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 Java de Spanner Cassandra

Este cliente es útil en las siguientes situaciones:

  • Usar Spanner con una refactorización mínima Quieres usar Spanner como backend para tu aplicación de Java, pero prefieres seguir usando la conocida API de cassandra-java-driver para acceder 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 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 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. Agrega el cliente de Java de Spanner Cassandra como una dependencia a tu proyecto:

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

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

    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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(true)
        .build();

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

session.close();

    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 describe en Cómo configurar el almacén de confianza 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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .build();

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

session.close();

    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. Para obtener más información, consulta 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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .setClientCertPathAndKey(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_KEY_PKCS8")
        .build();

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

  session.close();

    Reemplaza lo siguiente:

    • DATABASE_ID: Es el ID de tu base de datos de Spanner Omni, por ejemplo, test-db.

    • ENDPOINT: Es el extremo de tu instancia de Spanner Omni, por ejemplo, localhost:15000.

    • PATH_TO_CLIENT_CERT: Es la ruta de acceso al archivo del certificado del cliente.

    • PATH_TO_CLIENT_KEY_PKCS8: Es la ruta de acceso al archivo de clave privada del cliente en formato PKCS#8.

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 de Cassandra estándar. 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 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"
  spannerEndpoint: "ENDPOINT"
  instanceType: "omni"
  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.

En los siguientes ejemplos, se muestra cómo ejecutar el proxy de sidecar como un proceso independiente para cada configuración de seguridad admitida:

Texto sin formato

Para ejecutar con comunicación de texto sin formato, ejecuta el siguiente comando:

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

TLS

Para ejecutar con una conexión TLS, ejecuta el siguiente comando:

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

mTLS

Para ejecutar con una conexión de mTLS, ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

  • DATABASE_ID: Es el ID de tu base de datos de Spanner Omni, por ejemplo, test-db.

  • ENDPOINT: Es el extremo de tu instancia de Spanner Omni, por ejemplo, localhost:15000.

  • PATH_TO_ADAPTER_JAR: Es la ruta de acceso a tu archivo JAR del adaptador de Cassandra.

  • PATH_TO_CLIENT_CERT: Es la ruta de acceso al archivo del certificado del cliente.

  • PATH_TO_CLIENT_KEY_PKCS8: Es la ruta de acceso al archivo de clave privada del cliente en formato PKCS#8.