Utilizza il client Java Cassandra per connetterti a Spanner Omni

Il client Java Cassandra per Spanner connette le applicazioni scritte per il database Apache Cassandra con Spanner. Il client funziona con Spanner Omni nello stesso modo in cui funziona con Spanner.

Poiché Spanner supporta in modo nativo il protocollo di rete Cassandra v4, il client Java Cassandra di Spanner traduce il protocollo di rete Cassandra nell'API gRPC di Spanner. In questo modo puoi eseguire la migrazione delle 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 dell'applicazione per modifiche minime al codice.

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

Per saperne di più, consulta l' interfaccia Cassandra nella documentazione di Spanner.

Quando utilizzare il client Java Cassandra di Spanner

Questo client è utile nei seguenti scenari:

  • Utilizza Spanner con un refactoring minimo. Vuoi utilizzare Spanner come backend per la tua applicazione Java, ma preferisci continuare a utilizzare l'API cassandra-java-driver che conosci 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 i driver Cassandra.

Utilizza il client come dipendenza in-process

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

Per utilizzare il client come dipendenza in-process:

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

  2. Aggiungi il client Java Cassandra di Spanner 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 al truststore 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 Cassandra di Spanner come proxy sidecar è un'opzione efficace per le applicazioni e gli 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 di rete 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.

Utilizza 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 di 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

Utilizza 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 quanto segue:

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 quanto segue:

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 quanto segue:

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