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 Ihren 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 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 ohne Java verwenden: Sie möchten mit Standard-Cassandra-Tools wie cqlsh oder mit Anwendungen, die in anderen Sprachen geschrieben sind und Cassandra-Treiber verwenden, eine Verbindung zu Spanner herstellen.

Client als In-Process-Abhängigkeit verwenden

Die Integration 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. Ändern Sie den Code zum Erstellen von CqlSession und fügen Sie die kommunikationsspezifischen Optionen für Spanner Omni hinzu.

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

    Nur-Text-Kommunikation

    Das folgende Beispiel zeigt, wie Sie eine Nur-Text-Verbindung zu Spanner Omni herstellen:

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

    TLS-Verbindung

    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 in der TLS-Anleitung für das 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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
        .build();

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

session.close();

    mTLS-Verbindung

    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, wie in der Anleitung für mTLS im Java SDK beschrieben:

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

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"
  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

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-Systemattributen konfigurieren.

Für einen einzelnen Listener können Sie Systemeigenschaften verwenden. Die folgenden Beispiele zeigen, wie der Sidecar-Proxy für jeden unterstützten Sicherheitsmodus als eigenständiger Prozess ausgeführt wird:

Nur-Text-Kommunikation

Führen Sie für die Nur-Text-Kommunikation Folgendes aus:

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

TLS-Verbindung

Führen Sie für eine TLS-Verbindung Folgendes aus:

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

mTLS-Verbindung

Führen Sie für eine mTLS-Verbindung Folgendes aus:

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