Cassandra-Java-Client verwenden, um eine Verbindung zu Spanner Omni herzustellen

Der Cassandra-Java-Client für Spanner verbindet Anwendungen, die für die Apache Cassandra-Datenbank geschrieben wurden, mit Spanner. Der Client funktioniert mit Spanner Omni genauso wie mit Spanner.

Da Spanner das Cassandra v4-Wire-Protokoll nativ unterstützt, übersetzt der Spanner Cassandra-Java-Client das Cassandra-Wire-Protokoll in die Spanner-gRPC-API. So können Sie Ihre Cassandra-Anwendungen mit minimalen Codeänderungen zu Spanner migrieren.

In diesem Dokument wird beschrieben, wie Sie den Client mit Spanner Omni integrieren. Dazu haben Sie folgende Möglichkeiten:

  • In-Process-Abhängigkeit: Verwenden Sie diese Methode für Java-Anwendungen, die bereits cassandra-java-driver verwenden. Bei diesem Ansatz wird der Client in den Anwendungsprozess eingebettet, sodass nur minimale Codeänderungen erforderlich sind.

  • Sidecar-Proxy: Verwenden Sie diese Methode für Nicht-Java-Anwendungen oder wenn Sie externe Cassandra-Tools wie cqlsh verwenden. Bei diesem Ansatz wird der Client als eigenständiger Prozess ausgeführt.

Weitere Informationen finden Sie unter Cassandra-Schnittstelle in der Spanner-Dokumentation.

Wann sollte der Spanner Cassandra Java-Client verwendet werden?

Dieser Client ist in den folgenden Szenarien nützlich:

  • Spanner mit minimalem Refactoring verwenden Sie möchten Spanner als Backend für Ihre Java-Anwendung verwenden, aber weiterhin die vertraute cassandra-java-driver API für den Datenzugriff nutzen.

  • Cassandra-Tools verwenden, die nicht in Java geschrieben sind: Sie möchten mit Standard-Cassandra-Tools wie cqlsh oder mit Anwendungen, die in anderen Sprachen geschrieben wurden und Cassandra-Treiber verwenden, eine Verbindung zu Spanner herstellen.

Client als In-Process-Abhängigkeit verwenden

Die Einbindung des Spanner Cassandra Java-Clients als In-Process-Abhängigkeit ist die empfohlene Methode für Java-Anwendungen, um eine Verbindung zu Spanner Omni herzustellen. Im Vergleich zur Sidecar-Proxy-Methode bietet die In-Process-Konfiguration eine bessere Leistung, da ein zusätzlicher Netzwerk-Hop und die damit verbundene Serialisierung und Deserialisierung von Daten vermieden werden. Außerdem wird die Bereitstellungsarchitektur vereinfacht, da kein separater eigenständiger Prozess mehr verwaltet werden muss.

So verwenden Sie den Client als In-Process-Abhängigkeit:

  1. Fügen Sie den Spanner Cassandra-Java-Client als Abhängigkeit zu Ihrem Projekt hinzu:

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

  2. Ändern Sie den Code zum Erstellen von CqlSession und fügen Sie die kommunikationsspezifischen Optionen für Spanner Omni hinzu:

    Nur-Text

    Das folgende Beispiel zeigt, wie eine Nur-Text-Verbindung zu Spanner Omni hergestellt wird:

    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

    Wenn Sie eine TLS-Verbindung verwenden möchten, muss das CA-Zertifikat dem von der Anwendung verwendeten Truststore hinzugefügt werden. Weitere Informationen finden Sie unter Java-Truststore konfigurieren:

    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

    Wenn Sie eine mTLS-Verbindung verwenden möchten, muss das CA-Zertifikat dem von der Anwendung verwendeten Truststore hinzugefügt werden und der Clientschlüssel muss im PKCS#8-Format vorliegen. Weitere Informationen finden Sie in der Anleitung für mTLS im Java SDK.

    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();

    Ersetzen Sie Folgendes:

    • DATABASE_ID: die ID Ihrer Spanner Omni-Datenbank, z. B. test-db.

    • ENDPOINT: Der Endpunkt Ihrer Spanner Omni-Instanz, z. B. localhost:15000.

    • PATH_TO_CLIENT_CERT: der Pfad zu Ihrer Clientzertifikatsdatei.

    • PATH_TO_CLIENT_KEY_PKCS8: der Pfad zu Ihrer privaten Clientschlüsseldatei im PKCS#8-Format.

Sidecar-Proxy oder eigenständiger Prozess

Die Bereitstellung des Spanner Cassandra Java-Clients als Sidecar-Proxy ist eine effektive Option für Nicht-Java-Anwendungen und -Tools wie cqlsh, um mit Standard-Cassandra-Treibern eine Verbindung zu Spanner Omni herzustellen. Bei dieser Methode wird der Client als eigenständiger TCP-Proxy ausgeführt, der den Cassandra-Wire-Protokoll-Traffic abfängt und für die Kommunikation mit Spanner Omni in gRPC übersetzt.

Sie können den Sidecar-Proxy mit einer YAML-Konfigurationsdatei oder durch Angabe von Systemeigenschaften ausführen.

YAML-Konfigurationsdatei verwenden

Für Produktionsumgebungen empfehlen wir, den Adapter mit einer YAML-Datei zu konfigurieren. Diese Methode unterstützt mehrere Listener und globale Einstellungen:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

Beispiel 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

Systemeigenschaften verwenden

Bei einem einzelnen Listener oder einfacheren Bereitstellungen können Sie den Sidecar-Proxy als eigenständigen Prozess ausführen und seine Einstellungen mit Java-Systemeigenschaften konfigurieren.

Die folgenden Beispiele zeigen, wie der Sidecar-Proxy für jede unterstützte Sicherheitskonfiguration als eigenständiger Prozess ausgeführt wird:

Nur-Text

Führen Sie den folgenden Befehl aus, um die Kommunikation im Nur-Text-Modus zu verwenden:

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

Führen Sie den folgenden Befehl aus, um eine TLS-Verbindung zu verwenden:

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

Führen Sie den folgenden Befehl aus, um eine mTLS-Verbindung zu verwenden:

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

Ersetzen Sie Folgendes:

  • DATABASE_ID: die ID Ihrer Spanner Omni-Datenbank, z. B. test-db.

  • ENDPOINT: Der Endpunkt Ihrer Spanner Omni-Instanz, z. B. localhost:15000.

  • PATH_TO_ADAPTER_JAR: der Pfad zur JAR-Datei des Cassandra-Adapters.

  • PATH_TO_CLIENT_CERT: Pfad zu Ihrer Clientzertifikatsdatei.

  • PATH_TO_CLIENT_KEY_PKCS8: der Pfad zu Ihrer privaten Clientschlüsseldatei im PKCS#8-Format.