使用 Cassandra Go 客户端连接到 Spanner Omni

适用于 Spanner 的 Cassandra Go 客户端将为 Apache Cassandra 数据库编写的应用与 Spanner 连接起来。该客户端与 Spanner Omni 的工作方式与它与 Spanner 的工作方式相同。 由于 Spanner 原生支持 Cassandra v4 传输协议，因此该客户端允许使用 gocql 驱动程序的 Go 应用，或非 Go 应用和工具（例如 cqlsh）连接到 Spanner 数据库。

此客户端充当本地 TCP 代理。它会拦截驱动程序或客户端工具发送的原始 Cassandra 协议字节。然后，它会将这些字节和必要的元数据封装到 gRPC 消息中，以便与 Spanner Omni 通信。该客户端会将 Spanner Omni 的响应转换回 Cassandra 传输格式，并将其发送回原始驱动程序或工具。

本文档介绍了如何使用以下方法之一将客户端与 Spanner Omni 集成：

如需详细了解 Apache Cassandra 如何与 Spanner 协同工作，请参阅 Cassandra 接口。

何时使用 Spanner Cassandra Go 客户端

在以下场景中，此客户端非常有用：

  • 以最少的重构使用 Spanner。您希望将 Spanner 用作 Go 应用的后端，但更愿意继续使用熟悉的 gocql API 进行数据访问。

  • 使用非 Go Cassandra 工具。您希望使用标准 Cassandra 工具（例如 cqlsh）或使用 Cassandra 驱动程序以其他语言编写的应用连接到 Spanner。

将客户端用作进程内依赖项

Go 应用通过将 Spanner Cassandra Go 客户端作为进程内依赖项集成来连接到 Spanner Omni。此方法会将代理逻辑直接嵌入到应用中，从而无需单独的进程，简化了部署架构。此配置还可以避免额外的网络跃点以及额外的数据序列化和反序列化，从而提供最佳性能。

如需将客户端用作进程内依赖项，请执行以下操作：

  • 在 Go 应用中导入 Spanner 软件包：

    import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"

  • 修改集群创建代码。请使用 spanner.NewCluster 并提供以下 Spanner Omni 特定选项，而不是使用 gocql.NewCluster：

    纯文本通信

    以下示例展示了如何建立与 Spanner Omni 的纯文本连接：

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.UsePlainText = true

  cluster := spanner.NewCluster(opts)
  // ...
}

    TLS 连接

    以下示例展示了如何建立与 Spanner Omni 的 TLS 连接：

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"

  cluster := spanner.NewCluster(opts)
  // ...
}

    mTLS 连接

    以下示例展示了如何建立与 Spanner Omni 的 mTLS 连接：

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

  cluster := spanner.NewCluster(opts)
  // ...
}

将客户端部署为边车代理

对于非 Go 应用和工具（例如 cqlsh），将 Spanner Cassandra Go 客户端部署为边车代理是一种有效的选择，以便使用标准 Cassandra 驱动程序连接到 Spanner Omni。此方法会将客户端作为独立的 TCP 代理运行，该代理会拦截 Cassandra 传输协议流量并将其转换为 gRPC，以便与 Spanner Omni 通信。

当您需要使用外部 Cassandra 工具或需要避免直接修改应用的代码时，此配置非常有用。

您可以通过以下方式运行边车代理：

使用 Go run 命令在本地运行

从源代码将边车代理作为本地进程运行，对于您希望快速迭代应用和代理配置的开发和测试环境非常有用。

  1. 克隆代码库：

    git clone https://github.com/googleapis/go-spanner-cassandra.git

  2. 切换到代码库目录：

    cd go-spanner-cassandra

  3. 使用必需的 -db 标志和以下 Spanner Omni 特定标志运行 cassandra_launcher.go。将 -db 的值替换为 Spanner Omni 数据库名称：

  • 对于纯文本通信，请运行以下命令：
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • 对于 TLS 连接，请运行以下命令：
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • 对于 mTLS 连接，请运行以下命令：
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

使用预构建的 Docker 映像运行

我们建议在生产环境中使用预构建的 Docker 映像将边车代理作为容器化应用运行，因为它提供了一致且隔离的运行时环境。

  1. 从官方注册表代码库中拉取映像：

    docker pull gcr.io/cloud-spanner-adapter/cassandra-adapter

  2. 使用必需的标志运行映像：

    纯文本通信

    对于纯文本通信，请运行以下命令：

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText

    TLS 连接

    对于 TLS 连接，请运行以下命令：

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT

    mTLS 连接

    对于 mTLS 连接，请运行以下命令：

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY