Go SDK 简介

goclickzetta
goclickzetta
实现了 Go 标准库 database/sql 的驱动接口,导入后即以
clickzetta
clickzetta
为名注册驱动。本文介绍环境要求、版本选择、安装方法,以及如何运行第一个查询程序。

环境要求

  • Go 1.25 或更高版本(主版本)。
  • Linux、macOS 或 Windows。
  • 可访问 Lakehouse 服务地址的网络环境。

当前稳定版本为

v0.0.21
v0.0.21
。版本和源码更新以 goclickzetta GitHub 仓库 为准。

版本选择

SDK 有一个主版本和两个兼容版本。新应用请使用主版本。

版本结果格式Arrow 依赖Go 版本版本号格式状态
主版本Arrow
github.com/apache/arrow-go/v18
github.com/apache/arrow-go/v18
1.25 及以上
vX.Y.Z
vX.Y.Z
持续开发
Arrow v12 兼容版Arrow
github.com/apache/arrow/go/v12
github.com/apache/arrow/go/v12
1.19 及以上
vX.Y.Z-arrow12
vX.Y.Z-arrow12
已冻结
无 Arrow 版CSV无1.19 及以上
vX.Y.Z-csv
vX.Y.Z-csv
已冻结

两个兼容版本只为无法使用主版本依赖的应用保留:

  • Arrow v12 兼容版:应用必须停留在 Arrow v12。
  • 无 Arrow 版:应用无法引入任何 Arrow 依赖。典型情况是应用依赖了旧版
    github.com/apache/thrift
    github.com/apache/thrift
    (v0.13 及更早),而 Arrow 要求 thrift v0.16 及以上,两者无法在同一程序中共存。

已冻结的版本只修复安全问题和严重缺陷(结果错误、无法连接或无法执行查询),不再增加新功能。兼容版本与主版本的差异:

功能主版本Arrow v12 兼容版无 Arrow 版
Arrow 结果读取(
QueryArrowStream
QueryArrowStream
)
支持不支持不支持
Bulkload支持支持,接口不同,见 兼容版本的接口不支持,调用时返回错误,请改用
INSERT
INSERT
DSN 中省略
protocol
protocol
v0.0.20
v0.0.20
起支持
不支持,必须填写不支持,必须填写
sdk.job.timeout
sdk.job.timeout
和
context.WithTimeout
context.WithTimeout
按设置值生效
v0.0.21
v0.0.21
起支持
不支持,见 超时与取消不支持,见 超时与取消

安装

在 Go module 项目中安装当前稳定版本:

go get github.com/clickzetta/goclickzetta@v0.0.21

需要升级时执行:

go get github.com/clickzetta/goclickzetta@latest

安装兼容版本时必须指定完整的版本号。Go 把带后缀的版本号视为预发布版本,

go get -u
go get -u
和
@latest
@latest
不会选中它们,而是安装主版本。请在 版本列表 中选择对应后缀的最新版本,例如:

go get github.com/clickzetta/goclickzetta@v0.0.20-arrow12

无 Arrow 版:

go get github.com/clickzetta/goclickzetta@v0.0.12-csv

配置连接

Go SDK 使用 DSN(Data Source Name)配置连接:

<username>:<password>@https(<service>)/<schema>?virtualCluster=<vcluster>&workspace=<workspace>&instance=<instance>

你可以在 Lakehouse Studio 的 管理 -> 工作空间 页面查看 JDBC 连接串,并从中获取

service
service
、
instance
instance
、
workspace
workspace
等信息。全部参数说明见 使用 database/sql 查询。

以下命令将 DSN 写入当前 Shell 的环境变量:

export CLICKZETTA_DSN='<username>:<password>@https(<service>)/<schema>?virtualCluster=<vcluster>&workspace=<workspace>&instance=<instance>'

运行第一个查询

以下程序连接 Lakehouse 并执行一个最小查询:

package main import ( "context" "database/sql" "fmt" "log" "os" "time" _ "github.com/clickzetta/goclickzetta" ) func main() { dsn := os.Getenv("CLICKZETTA_DSN") if dsn == "" { log.Fatal("CLICKZETTA_DSN is not set") } db, err := sql.Open("clickzetta", dsn) if err != nil { log.Fatal(err) } defer db.Close() ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) defer cancel() if err := db.PingContext(ctx); err != nil { log.Fatal(err) } var value int if err := db.QueryRowContext(ctx, "SELECT 1 AS value").Scan(&value); err != nil { log.Fatal(err) } fmt.Println(value) }

运行程序:

go run .

输出如下:

1

sql.Open
sql.Open
只初始化连接池,不会立即验证账号或网络。程序启动时调用
PingContext
PingContext
,可以尽早发现 DSN、权限或网络配置问题。

常见问题

go get -u
go get -u
后变成了主版本

兼容版本的版本号带有后缀,Go 把它视为预发布版本,升级时会选择主版本。请按 安装 中的说明指定完整版本号,并在

go.mod
go.mod
中固定。

编译报 thrift 相关错误

应用依赖的旧版 thrift(v0.13 及更早)与 Arrow 要求的 thrift 版本冲突。可以升级应用中依赖旧版 thrift 的库;无法升级时,使用无 Arrow 版。

missing virtual cluster name
missing virtual cluster name
、
missing workspace name
missing workspace name
等错误

DSN 中缺少必填参数。请检查

virtualCluster
virtualCluster
、
workspace
workspace
、
instance
instance
是否齐全。

联系我们
预约咨询
微信咨询
电话咨询
邮件咨询