Utilizza il client Java Cassandra per connetterti a Spanner Omni

Il client Java Cassandra per Spanner collega le applicazioni scritte per il database Apache Cassandra a Spanner. Il client funziona con Spanner Omni allo stesso modo di Spanner.

Poiché Spanner supporta in modo nativo il protocollo di trasferimento Cassandra v4, il client Java Spanner Cassandra traduce il protocollo di trasferimento Cassandra nell'API gRPC di Spanner. Ciò ti consente di eseguire la migrazione delle tue applicazioni Cassandra a Spanner con modifiche minime al codice.

Questo documento mostra come integrare il client con Spanner Omni utilizzando uno dei seguenti metodi:

  • Dipendenza in-process: utilizza questo metodo per le applicazioni Java che utilizzano già cassandra-java-driver. Questo approccio incorpora il client nel processo di applicazione per modifiche minime al codice.

  • Proxy sidecar: utilizza questo metodo per applicazioni non Java o quando utilizzi strumenti Cassandra esterni, come cqlsh. Questo approccio esegue il client come processo autonomo.

Per saperne di più, consulta Interfaccia Cassandra nella documentazione di Spanner.

Quando utilizzare il client Java Spanner Cassandra

Questo client è utile nei seguenti scenari:

  • Utilizza Spanner con il minimo refactoring. Vuoi utilizzare Spanner come backend per la tua applicazione Java, ma preferisci continuare a utilizzare l'API cassandra-java-driver che conosci bene per l'accesso ai dati.

  • Utilizza strumenti Cassandra non Java. Vuoi connetterti a Spanner utilizzando strumenti Cassandra standard come cqlsh o applicazioni scritte in altri linguaggi che utilizzano driver Cassandra.

Utilizzare il client come dipendenza in-process

L'integrazione del client Java Spanner Cassandra come dipendenza in-process è il metodo consigliato per le applicazioni Java per connettersi a Spanner Omni. Rispetto al metodo proxy sidecar, la configurazione in-process offre prestazioni migliori evitando un hop di rete aggiuntivo e la serializzazione e deserializzazione associate dei dati. Semplifica inoltre l'architettura di deployment eliminando la necessità di gestire un processo autonomo separato.

Per utilizzare il client come dipendenza in-process:

  1. Aggiungi il client Java Spanner Cassandra come dipendenza al tuo progetto:

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

  2. Modifica il codice di creazione di CqlSession e aggiungi le opzioni specifiche per la comunicazione di Spanner Omni:

    Testo normale

    L'esempio seguente mostra come stabilire una connessione in testo normale 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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(true)
        .build();

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

session.close();

    TLS

    Per utilizzare una connessione TLS, assicurati che il certificato CA sia aggiunto all'archivio attendibilità utilizzato dall'applicazione, come descritto in Configurare l'archivio attendibilità 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

    Per utilizzare una connessione mTLS, assicurati che il certificato CA sia aggiunto all'archivio attendibilità utilizzato dall'applicazione e che la chiave client sia in formato PKCS#8. Per saperne di più, consulta le istruzioni mTLS dell'SDK 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();

    Sostituisci quanto segue:

    • DATABASE_ID: l'ID del tuo database Spanner Omni, ad esempio test-db.

    • ENDPOINT: l'endpoint dell'istanza Spanner Omni, ad esempio localhost:15000.

    • PATH_TO_CLIENT_CERT: il percorso del file del certificato client.

    • PATH_TO_CLIENT_KEY_PKCS8: il percorso del file della chiave privata client in formato PKCS#8.

Proxy sidecar o processo autonomo

Il deployment del client Java Spanner Cassandra come proxy sidecar è un'opzione efficace per applicazioni e strumenti non Java, come cqlsh, per connettersi a Spanner Omni utilizzando i driver Cassandra standard. Questo metodo esegue il client come proxy TCP autonomo che intercetta il traffico del protocollo wire Cassandra e lo traduce in gRPC per la comunicazione con Spanner Omni.

Puoi eseguire il proxy sidecar utilizzando un file di configurazione YAML o specificando le proprietà di sistema.

Utilizzare un file di configurazione YAML

Per le configurazioni di produzione, ti consigliamo di utilizzare un file YAML per configurare l'adattatore. Questo metodo supporta più listener e impostazioni globali:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

Esempio 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

Utilizzare le proprietà di sistema

Per un singolo listener o implementazioni più semplici, puoi eseguire il proxy sidecar come processo autonomo e configurarne le impostazioni utilizzando le proprietà di sistema Java.

Gli esempi seguenti mostrano come eseguire il proxy sidecar come processo autonomo per ogni configurazione di sicurezza supportata:

Testo normale

Per l'esecuzione con comunicazione in testo normale, esegui questo 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

Per l'esecuzione con una connessione TLS, esegui questo 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

Per eseguire con una connessione mTLS, esegui questo 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

Sostituisci quanto segue:

  • DATABASE_ID: l'ID del tuo database Spanner Omni, ad esempio test-db.

  • ENDPOINT: l'endpoint dell'istanza Spanner Omni, ad esempio localhost:15000.

  • PATH_TO_ADAPTER_JAR: il percorso del file JAR dell'adattatore Cassandra.

  • PATH_TO_CLIENT_CERT: il percorso del file del certificato client.

  • PATH_TO_CLIENT_KEY_PKCS8: il percorso del file della chiave privata del client in formato PKCS#8.