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.mod
go.mod
中固定该版本。如果构建中的其他依赖要求更高的
goclickzetta
goclickzetta
版本,Go 会把兼容版本替换为主版本。升级其他依赖后,可以执行
go list -m github.com/clickzetta/goclickzetta
go list -m github.com/clickzetta/goclickzetta
确认实际使用的版本。
配置连接
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 包含用户名和密码,不要将它硬编码到源码或提交到 Git。生产环境应通过环境变量或密钥管理服务注入。
以下命令将 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
是否齐全。