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 in cui funziona con 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 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 la nota API cassandra-java-driver per l'accesso ai dati.

  • Utilizza strumenti Cassandra non Java. Vuoi connetterti a Spanner utilizzando strumenti Cassandra standard come cqlsh o applicazioni scritte in altre lingue 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. Inoltre, semplifica l'architettura di deployment eliminando la necessità di gestire un processo autonomo separato.

Per utilizzare il client come dipendenza in-processo:

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

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

    Comunicazione in 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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(true)
        .build();

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

session.close();

    Connessione TLS

    Per utilizzare una connessione TLS, assicurati che il certificato CA sia aggiunto all'archivio attendibilità utilizzato dall'applicazione, come indicato nelle istruzioni TLS 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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
        .build();

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

session.close();

    Connessione mTLS

    Per utilizzare una connessione mTLS, assicurati che il certificato CA sia aggiunto al truststore utilizzato dall'applicazione e che la chiave client sia in formato PKCS#8, come indicato nelle 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())
    .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 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"
  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

Utilizzare le proprietà di sistema

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

Per un singolo listener, puoi utilizzare le proprietà di sistema. Gli esempi seguenti mostrano come eseguire il proxy sidecar come processo autonomo per ogni modalità di sicurezza supportata:

Comunicazione in testo normale

Per la comunicazione in testo normale, esegui questo comando:

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

Connessione TLS

Per una connessione TLS, esegui questo comando:

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

Connessione mTLS

Per una connessione mTLS, esegui questo comando:

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