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 ao 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 Cassandra para Spanner 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 o mínimo de mudanças 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 Cassandra para Spanner

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 sua arquitetura de implantação ao remover a necessidade de gerenciar um processo independente separado.

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

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

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

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

    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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(true)
        .build();

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

session.close();

    TLS

    Para usar uma conexão TLS, verifique se o certificado de CA foi adicionado ao truststore usado pelo aplicativo, conforme descrito em Configurar o truststore 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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .build();

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

session.close();

    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. Para mais informações, consulte as instruções de mTLS do SDK do 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())
        .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();

    Substitua:

    • DATABASE_ID: o ID do banco de dados do Spanner Omni. Por exemplo, test-db.

    • ENDPOINT: o endpoint da sua instância do Spanner Omni, por exemplo, localhost:15000.

    • PATH_TO_CLIENT_CERT: o caminho para o arquivo de certificado do cliente.

    • PATH_TO_CLIENT_KEY_PKCS8: o caminho para o arquivo de chave privada do cliente no formato PKCS#8.

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, para se conectar 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 transmissão 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 oferece suporte a 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"
  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

Usar propriedades do sistema

Para um único listener ou implantações mais simples, é possível executar o proxy sidecar como um processo independente e configurar as definições dele usando propriedades do sistema Java.

Os exemplos a seguir mostram como executar o proxy sidecar como um processo independente para cada configuração de segurança compatível:

Texto simples

Para executar com comunicação de texto simples, execute o seguinte comando:

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

Para executar com uma conexão TLS, execute o seguinte comando:

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

Para executar com uma conexão mTLS, execute o seguinte comando:

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

Substitua:

  • DATABASE_ID: o ID do banco de dados do Spanner Omni, por exemplo, test-db.

  • ENDPOINT: o endpoint da sua instância do Spanner Omni, por exemplo, localhost:15000.

  • PATH_TO_ADAPTER_JAR: o caminho para o arquivo JAR do adaptador do Cassandra.

  • PATH_TO_CLIENT_CERT: o caminho para o arquivo de certificado do cliente.

  • PATH_TO_CLIENT_KEY_PKCS8: o caminho para o arquivo de chave privada do cliente no formato PKCS#8.