apache/cassandra-gocql-driver
GitHub: apache/cassandra-gocql-driver
GoCQL 是 Apache 官方维护的 Go 语言 Cassandra 数据库驱动，通过原生协议提供高性能、类型安全的集群连接与查询能力。
Stars: 2690 | Forks: 652
# Apache Cassandra GoCql 驱动
[!在 https://the-asf.slack.com/archives/C05LPRVNZV1 加入聊天](https://the-asf.slack.com/archives/C05LPRVNZV1)
[](https://pkg.go.dev/github.com/apache/cassandra-gocql-driver/v2)
gocql 包为 Go 编程语言实现了一个快速且稳定的 Cassandra 客户端。
项目网站：https://cassandra.apache.org
API 文档：https://pkg.go.dev/github.com/apache/cassandra-gocql-driver/v2
讨论：https://cassandra.apache.org/_/community.html#discussions ## 支持的版本 以下矩阵显示了作为 CI 构建一部分，通过集成测试套件测试的 Go 和 Cassandra 版本： | Go/Cassandra | 4.1.x | 5.0.x | |--------------|-------|-------| | 1.25 | 是 | 是 | | 1.26 | 是 | 是 | Gocql 已经在生产环境中针对许多版本的 Cassandra 进行了测试。由于 CI 设置的限制，我们仅针对最新的 2 个正式发布版本（GA）进行测试。 ## 停止维护模型 ## 安装 ``` go get github.com/apache/cassandra-gocql-driver/v2 ``` **注意：** `2.0.0` 版本引入了破坏性变更。请参阅[升级指南](https://github.com/apache/cassandra-gocql-driver/blob/trunk/UPGRADE_GUIDE.md)以获取从 `1.x` 升级的说明。 ## 功能 * 使用原生传输的现代 Cassandra 客户端 * Cassandra 和 Go 之间的自动类型转换 * 支持所有常见类型，包括 set、list 和 map * 自定义类型可以实现 `Marshaler` 和 `Unmarshaler` 接口 * 严格的类型转换，无精度损失 * 内置对 UUID 的支持（版本 1 和 4） * 支持 logged、unlogged 和 counter batch * 集群管理 * 连接失败时通过指数退避进行自动重连 * 查询在不同主机之间的轮询分发 * 查询在主机上不同连接之间的轮询分发 * 每个连接最多可以执行 n 个并发查询（其中 n 是客户端选择使用的协议版本设定的限制） * 可选的节点自动发现 * 基于策略的连接池，带有 token 感知（token aware）和轮询（round-robin）策略实现 * 通过 Query.SetHostID() 支持针对特定主机的查询 * 支持密码认证 * 可配置分页大小的分页结果迭代 * 支持 TLS/SSL * 可选的帧压缩（Snappy 和 LZ4 在单独的包中提供） * 结构化日志记录支持，为流行的日志记录器（Zap、Zerolog）提供专用包 * 自动查询准备 * 支持查询追踪 * 通过原生协议版本 3、4 和 5 支持 Cassandra 2.1+ 到 5.0+： * **协议 3**（Cassandra 2.1+）： * 支持多达 32768 个流 * 支持 tuple 类型 * 默认支持客户端时间戳 * 通过自定义 marshaller 或 struct tag 支持 UDT * **协议 4**（Cassandra 3.0+）： * 包含协议 3 的所有功能 * 提升的性能与效率 * **协议 5**（Cassandra 4.0+）： * 包含以前所有协议的功能 * 支持按查询覆盖 keyspace (Query.SetKeyspace(), Batch.SetKeyspace()) * 支持按查询自定义时间戳 (Query.WithNowInSeconds(), Batch.WithNowInSeconds()) * **Cassandra 5.0+ 专属**： * 支持用于向量搜索功能的 vector 类型 * 提供用于访问给定 keyspace 的 schema 元数据的 API ## 性能 虽然驱动程序力求具备高性能，但在某些情况下很难进行测试和验证。该驱动程序在构建时优先考虑可维护性和代码可读性，其次是性能和功能，因此性能偶尔可能会下降；如果发生这种情况，请提交 issue，我们会进行查看并予以解决。驱动程序从其读取缓冲区复制数据的唯一情况是在将数据 Unmarshal（反序列化）到提供的类型中时。 从驱动程序获取更高性能的一些提示： * 使用 TokenAware 策略 * 在执行插入时使用大量 goroutine，该驱动程序是异步的，但提供了同步 API，它可以并发执行许多查询 * 调整查询分页大小 * 从网络读取数据进行 unmarshal 将导致大量的内存分配，这可能会对垃圾回收器产生不利影响，请调整 `GOGC` * 使用后关闭 iterator 以回收字节缓冲区 ## 重要的默认 Keyspace 变更 为了简化库，gocql 不再支持执行 "use" 语句。用户仍然可以定义连接的默认 keyspace，但现在只能在创建 session 之前定义 keyspace。查询仍然可以通过在查询语句中指定 keyspace 来访问它们：
```
SELECT * FROM example2.table;
```
正确用法的示例：
```
cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
cluster.Keyspace = "example"
...
session, err := cluster.CreateSession()
```
错误用法的示例：
```
cluster := gocql.NewCluster("192.168.1.1", "192.168.1.2", "192.168.1.3")
cluster.Keyspace = "example"
...
session, err := cluster.CreateSession()
if err = session.Query("use example2").Exec(); err != nil {
log.Fatal(err)
}
```
由于用户试图执行 "use" 语句，这将导致 session.Query 行返回一个错误。
## 示例
请参阅[包文档](https://pkg.go.dev/github.com/apache/cassandra-gocql-driver/v2#pkg-examples)。
## 数据绑定
有多种方法可以将应用层数据结构绑定到 CQL 语句：
* 您可以手动编写数据绑定，如 Tweet 示例中所述。这为您提供了最大的灵活性，但这确实意味着您需要使应用程序代码与 Cassandra schema 保持同步。
* 您可以使用 `SliceMap()` API 将整个查询结果动态 marshal（序列化）到 `[]map[string]interface{}` 中。这将返回一个由 CQL 列名作为键的行 map 组成的切片。此方法不需要与 gocql API 进行任何特殊的交互，但确实需要您的应用程序能够处理数据的键值视图。
* 作为对 `SliceMap()` API 的改进，您还可以调用 `MapScan()`，它会逐行返回 `map[string]interface{}` 实例。
* `Bind()` API 为客户端应用程序提供了一种底层机制，用于内省查询元数据并从应用层数据结构中提取相应的字段值。
* [gocqlx](https://github.com/scylladb/gocqlx) 包是 gocql 的一个符合语言习惯的扩展，提供了易用性功能。使用 gocqlx，您可以从 map 和 struct 绑定查询参数，使用命名查询参数（:identifier），并将查询结果扫描到 struct 和 slice 中。它附带了一个流畅且灵活的 CQL 查询构建器，支持完整的 CQL 规范，包括 BATCH 语句和自定义函数。
* 在 gocql 驱动程序之上构建的 [cqlr](https://github.com/relops/cqlr) 增加了将 CQL iterator 自动绑定到 struct，或者将 struct 绑定到 INSERT 语句的功能。
* 另一个建立在 gocql 之上的外部项目是 [cqlc](http://relops.com/cqlc)，它可以根据您的 Cassandra schema 生成兼容 gocql 的代码，以便您能在 Go 中使用自然的查询语法编写类型安全的 CQL 语句。
* [gocassa](https://github.com/hailocab/gocassa) 是建立在 gocql 之上的一个外部项目，提供便捷的查询构建和数据绑定。
* [gocqltable](https://github.com/kristoiv/gocqltable) 提供了一个 ORM 风格的便利层，使使用 gocql 进行 CRUD 操作更加容易。
## 生态系统
## 其他项目
* [gocqldriver](https://github.com/tux21b/gocqldriver) 是 gocql 的前身，基于 Go 的 `database/sql` 包。该项目不再维护，因为 Cassandra 并不适合传统的 `database/sql` API。请改用此包。
## SEO
出于某些原因，当您在 Google 搜索 `golang cassandra` 时，该项目在结果列表中的排名并不高。但如果您搜索 `go cassandra`，我们在列表中的排名会稍微靠前一点。所以写这段话是为了试图说服 Google，golang 是 Go 的别名。
API 文档：https://pkg.go.dev/github.com/apache/cassandra-gocql-driver/v2
讨论：https://cassandra.apache.org/_/community.html#discussions ## 支持的版本 以下矩阵显示了作为 CI 构建一部分，通过集成测试套件测试的 Go 和 Cassandra 版本： | Go/Cassandra | 4.1.x | 5.0.x | |--------------|-------|-------| | 1.25 | 是 | 是 | | 1.26 | 是 | 是 | Gocql 已经在生产环境中针对许多版本的 Cassandra 进行了测试。由于 CI 设置的限制，我们仅针对最新的 2 个正式发布版本（GA）进行测试。 ## 停止维护模型 ## 安装 ``` go get github.com/apache/cassandra-gocql-driver/v2 ``` **注意：** `2.0.0` 版本引入了破坏性变更。请参阅[升级指南](https://github.com/apache/cassandra-gocql-driver/blob/trunk/UPGRADE_GUIDE.md)以获取从 `1.x` 升级的说明。 ## 功能 * 使用原生传输的现代 Cassandra 客户端 * Cassandra 和 Go 之间的自动类型转换 * 支持所有常见类型，包括 set、list 和 map * 自定义类型可以实现 `Marshaler` 和 `Unmarshaler` 接口 * 严格的类型转换，无精度损失 * 内置对 UUID 的支持（版本 1 和 4） * 支持 logged、unlogged 和 counter batch * 集群管理 * 连接失败时通过指数退避进行自动重连 * 查询在不同主机之间的轮询分发 * 查询在主机上不同连接之间的轮询分发 * 每个连接最多可以执行 n 个并发查询（其中 n 是客户端选择使用的协议版本设定的限制） * 可选的节点自动发现 * 基于策略的连接池，带有 token 感知（token aware）和轮询（round-robin）策略实现 * 通过 Query.SetHostID() 支持针对特定主机的查询 * 支持密码认证 * 可配置分页大小的分页结果迭代 * 支持 TLS/SSL * 可选的帧压缩（Snappy 和 LZ4 在单独的包中提供） * 结构化日志记录支持，为流行的日志记录器（Zap、Zerolog）提供专用包 * 自动查询准备 * 支持查询追踪 * 通过原生协议版本 3、4 和 5 支持 Cassandra 2.1+ 到 5.0+： * **协议 3**（Cassandra 2.1+）： * 支持多达 32768 个流 * 支持 tuple 类型 * 默认支持客户端时间戳 * 通过自定义 marshaller 或 struct tag 支持 UDT * **协议 4**（Cassandra 3.0+）： * 包含协议 3 的所有功能 * 提升的性能与效率 * **协议 5**（Cassandra 4.0+）： * 包含以前所有协议的功能 * 支持按查询覆盖 keyspace (Query.SetKeyspace(), Batch.SetKeyspace()) * 支持按查询自定义时间戳 (Query.WithNowInSeconds(), Batch.WithNowInSeconds()) * **Cassandra 5.0+ 专属**： * 支持用于向量搜索功能的 vector 类型 * 提供用于访问给定 keyspace 的 schema 元数据的 API ## 性能 虽然驱动程序力求具备高性能，但在某些情况下很难进行测试和验证。该驱动程序在构建时优先考虑可维护性和代码可读性，其次是性能和功能，因此性能偶尔可能会下降；如果发生这种情况，请提交 issue，我们会进行查看并予以解决。驱动程序从其读取缓冲区复制数据的唯一情况是在将数据 Unmarshal（反序列化）到提供的类型中时。 从驱动程序获取更高性能的一些提示： * 使用 TokenAware 策略 * 在执行插入时使用大量 goroutine，该驱动程序是异步的，但提供了同步 API，它可以并发执行许多查询 * 调整查询分页大小 * 从网络读取数据进行 unmarshal 将导致大量的内存分配，这可能会对垃圾回收器产生不利影响，请调整 `GOGC` * 使用后关闭 iterator 以回收字节缓冲区 ## 重要的默认 Keyspace 变更 为了简化库，gocql 不再支持执行 "use
标签：EVTX分析, 日志审计