Usar o cliente Java do Cassandra para se conectar ao Spanner Omni

O cliente Java do Cassandra para Spanner conecta aplicativos escritos para o banco de dados Apache Cassandra com o Spanner. O cliente trabalha com o Spanner Omni da mesma forma que trabalha com o Spanner.

Como o Spanner oferece suporte nativo ao protocolo de transmissão do Cassandra v4, o cliente Java do Spanner Cassandra traduz o protocolo de transmissão do Cassandra para a API gRPC do Spanner. Isso permite migrar seus aplicativos do Cassandra para o Spanner com mudanças mínimas no código.

Este documento mostra como integrar o cliente ao Spanner Omni usando um dos seguintes métodos:

  • Dependência no processo: use esse método para aplicativos Java que já usam o cassandra-java-driver. Essa abordagem incorpora o cliente ao processo do aplicativo para modificações mínimas no código.

  • Proxy sidecar: use esse método para aplicativos que não são Java ou ao usar ferramentas externas do Cassandra, como cqlsh. Essa abordagem executa o cliente como um processo independente.

Para mais informações, consulte Interface do Cassandra na documentação do Spanner.

Quando usar o cliente Java do Spanner Cassandra

Esse cliente é útil nos seguintes cenários:

  • Use o Spanner com refatoração mínima. Você quer usar o Spanner como back-end do seu aplicativo Java, mas prefere continuar usando a API cassandra-java-driver para acesso aos dados.

  • Use ferramentas do Cassandra que não sejam Java. Você quer se conectar ao Spanner usando ferramentas padrão do Cassandra, como cqlsh, ou aplicativos escritos em outras linguagens que usam drivers do Cassandra.

Usar o cliente como uma dependência no processo

Integrar o cliente Java do Spanner Cassandra como uma dependência no processo é o método recomendado para que aplicativos Java se conectem ao Spanner Omni. Em comparação com o método de proxy sidecar, a configuração no processo oferece melhor desempenho, evitando um salto de rede extra e a serialização e desserialização de dados associadas. Ele também simplifica a arquitetura de implantação, eliminando a necessidade de gerenciar um processo independente separado.

Para usar o cliente como uma dependência no processo, faça o seguinte:

  1. Modifique o código de criação de CqlSession e adicione as opções específicas de comunicação do Spanner Omni.

  2. Adicione o cliente Java do Spanner Cassandra como uma dependência ao seu projeto.

    Comunicação em texto simples

    O exemplo a seguir mostra como estabelecer uma conexão de texto simples com o 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();

    Conexão TLS

    Para usar uma conexão TLS, verifique se o certificado de CA foi adicionado ao truststore usado pelo aplicativo, conforme mencionado nas instruções de TLS do 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();

    Conexão mTLS

    Para usar uma conexão mTLS, verifique se o certificado de CA foi adicionado ao truststore usado pelo aplicativo e se a chave do cliente está no formato PKCS#8, conforme mencionado nas instruções mTLS do 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 ou processo independente

Implantar o cliente Java do Spanner Cassandra como um proxy sidecar é uma opção eficaz para aplicativos e ferramentas que não são Java, como cqlsh, se conectarem ao Spanner Omni usando drivers padrão do Cassandra. Esse método executa o cliente como um proxy TCP independente que intercepta o tráfego do protocolo de rede do Cassandra e o converte em gRPC para comunicação com o Spanner Omni.

É possível executar o proxy sidecar usando um arquivo de configuração YAML ou especificando propriedades do sistema.

Usar um arquivo de configuração YAML

Para configurações de produção, recomendamos usar um arquivo YAML para configurar o adaptador. Esse método é compatível com vários listeners e configurações globais:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

config.yaml de exemplo:

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

Usar propriedades do sistema

Para um único listener ou implantações mais simples, execute o proxy sidecar como um processo independente e configure as definições usando propriedades do sistema Java.

Para um único listener, use propriedades do sistema. Os exemplos a seguir mostram como executar o proxy sidecar como um processo independente para cada modo de segurança compatível:

Comunicação em texto simples

Para comunicação em texto simples, execute o seguinte:

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

Conexão TLS

Para uma conexão TLS, execute o seguinte:

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

Conexão mTLS

Para uma conexão mTLS, execute o seguinte:

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