hubble-go-client

README

Hubble 客户端

Go编程语言的Hubble客户端。

功能

• 原生Go实现
• 通过HTTP或HTTPS连接
• HTTP Basic身份验证和Kerberos身份验证
• 每个查询的用户信息用于访问控制
• 支持自定义HTTP客户端(可调节的连接池,超时时间,TLS)
• 支持从Hubble转换为原生Go数据类型
  • string, sql.NullString
  • int64, sql.NullInt64
  • float64, sql.NullFloat64
  • map, hubble.NullMap
  • time.Time, hubble.NullTime
  • 高达3维数组到Go切片,任何支持的类型

要求

• Go 1.22或更高版本
• Hubble 5.1.7或更高版本

安装

您需要一个已安装Go并设置$GOPATH的工作环境。

下载并安装Hubble database/sql驱动程序:

go get gitee.com/openhubble/hubble-go-client/hubble

确保您已安装Git并将其添加到$PATH中。

用法

这个Hubble客户端是Go的 database/sql/driver 接口实现. 您需要导入包并使用database/sql的API。

只支持读取操作，如SHOW和SELECT。

使用“hubble”作为“driverName”，使用有效的[DSN]（#DSN数据源名称）作为“dataSourceName”。

例如:

import "database/sql"
import _ "gitee.com/openhubble/hubble-go-client/hubble"

dsn := "http://user@localhost:8080?catalog=default&schema=test"
db, err := sql.Open("hubble", dsn)

认证

同时支持HTTP基本身份验证和Kerberos身份验证。

HTTP Basic 认证

如果DSN包含密码，则客户端通过将每个请求中的“Authorization”标头设置为Hubble来启用HTTP Basic身份验证。

HTTP基本身份验证仅在HTTPS上的加密连接上受支持。

Kerberos 认证

此驱动程序通过在[Config]中设置Kerberos字段来支持Kerberos身份验证(https://godoc.org/gitee.com/openhubble/hubble-go-client/hubble#Config)结构。

系统访问控制和每次查询的用户信息

可以将用户信息传递给Hubble，这与用于向协调器进行身份验证的主体不同。

为了将查询中的用户信息传递给Hubble，您必须添加一个NamedArg键为X-Hubble-User的查询参数。

无论实际连接的身份验证方法如何，驱动程序都会使用此参数通知Hubble用户正在执行查询，并且其值不会传递给查询。

例如:

db.Query("SELECT * FROM foobar WHERE id=?", 1, sql.Named("X-Hubble-User", string("hubble")))

X-Hubble-User NamedArg可以放到参数任何位置，不会影响到查询。

DSN（数据源名称）

数据源名称是一个URL，具有强制用户名和此驱动程序支持的可选查询字符串参数，格式如下：

http[s]://user[:pass]@host[:port][?parameters]

建立DSN的最简单方法是使用Config.FormatDSN助手功能。

该驱动程序同时支持HTTP和HTTPS。如果您使用HTTPS，建议您还提供一个自定义的“http.Client”，它可以验证（或跳过）服务器证书的安全检查，和/或配置TLS客户端身份验证。

参数

参数区分大小写

参考Hubble的参数

source

类型:     string
有效值:   描述到Hubble的连接源的字符串
默认值:   empty

“source”参数是可选的，但如果使用，可以帮助Hubble管理员解决查询问题，并将其追溯到原始客户端。

catalog

类型:      string
有效值:    Hubble服务器中配置的catalog的名称
默认值:    默认为空

“catalog”参数定义了hubble catalog，其中存在用于组织表的模式。

schema

类型:     string
有效值:   catalog中现有schema的名称
默认值:   默认为空

“schema”参数定义了存在表的Hubble模式。在某些环境中，这也被称为命名空间。

session_properties

类型:     string
有效值:   以逗号分隔的key=value会话参数列表
默认值:   默认为空

“session_properties”参数必须包含Hubble服务器接受的有效参数。在Hubble中运行“SHOW SESSION”以获取当前列表。

custom_client

类型:     string
有效值:   驱动中注册的http客户端的名称
默认值:   默认为空 (默认为http.DefaultClient)

“custom_client”参数允许使用自定义“http.client”与Hubble进行通信。

在驱动程序中注册您的自定义客户端，然后在DSN中调用“sql.Open”时按名称引用它：

customClient := &http.Client{
    Transport: &http.Transport{
        Proxy: http.ProxyFromEnvironment,
        DialContext: (&net.Dialer{
            Timeout:   30 * time.Second,
            KeepAlive: 30 * time.Second,
            DualStack: true,
        }).DialContext,
        MaxIdleConns:          100,
        IdleConnTimeout:       90 * time.Second,
        TLSHandshakeTimeout:   10 * time.Second,
        ExpectContinueTimeout: 1 * time.Second,
        TLSClientConfig:       &tls.Config{
        // your config here...
        },
    },
}
hubble.RegisterCustomClient("custom", customClient)
db, err := sql.Open("hubble", "https://user@localhost:8080?custom_client=custom")

例子

http://user@localhost:38080?source=hello&catalog=default&schema=custom

https://user@localhost:38443?session_properties=query_max_run_time=10m,query_priority=2

数据类型

查询参数

将参数传递给查询时，驱动程序支持以下Go数据类型：

• integers
• bool
• string
• slices
• hubble.Numeric - 数字的字符串表示
• time.Time - 作为带有时区的时间戳传递给Hubble
• hubble.Date(year, month, day) 的结果 - 作为日期传递给hubble
• hubble.Time(hour, minute, second, nanosecond) - 作为没有时区的时间传递给Hubble
• hubble.TimeTz(hour, minute, second, nanosecond, location) - 作为有时区的时间传递给Hubble
• hubble.Timestamp(year, month, day, hour, minute, second, nanosecond) 的结果 - 作为不带时区的时间戳传递给Hubble

目前尚不支持的类型：

• nil
• float32 or float64
• byte
• time.Duration
• json.RawMessage
• maps

要使用不受支持的类型，请将它们作为字符串传递，并在查询中使用强制转换，如下所示：

SELECT * FROM table WHERE col_double = cast(? AS DOUBLE) OR col_timestamp = CAST(? AS TIMESTAMP)

返回记录

读取返回记录时，驱动程序支持大多数Hubble数据类型，除了:

• 精确的时间和时间戳-所有时间类型返回为 time.Time. 所有精度最高支持到纳秒 (TIMESTAMP(9) or TIME(9)) 支持 (因为 time.Time 是Golang的最大精度支持). 如果查询返回以更高精度定义的列，值将被修剪为9位小数。使用“CAST”减少返回的精度，或者将值转换为可以手动解析的字符串。
• DECIMAL - 返回 string
• IPADDRESS - 返回 string
• INTERVAL YEAR TO MONTH 和 INTERVAL DAY TO SECOND - 返回 string
• UUID - 返回 string

不支持“HyperLogLog”、“SetDigest”、“QDigest”和“TDigest”等数据类型，因此无法从查询中返回。

要读取可为null的列，请使用：

• hubble.NullTime
• hubble.NullMap - 其中存储为 map[string]interface{} 或来自 database/sql 包, 例如 sql.NullInt64

要读取包含数组或映射的查询结果，请将以下结构之一传递给“Scan（）”函数：

• hubble.NullSliceBool
• hubble.NullSliceString
• hubble.NullSliceInt64
• hubble.NullSliceFloat64
• hubble.NullSliceTime
• hubble.NullSliceMap

对于二维或三维数组，请使用“hubble.NullSlice2Bool”和“hubble.nullSlice3Pool”或其他数据类型的等效项。

要读取“ROW”值，请在结构中实现“sql.Scanner”接口。它的“Scan（）”函数 将接收具有以下类型值的“[]interface｛｝”切片：

• bool
• json.Number 对于任何数字Hubble类型
• []interface{} Hubble 数组
• map[string]interface{} Hubble maps
• string 对于其他Hubble类型，如字符、日期、时间或时间戳