KingbaseES客户端编程接口指南-Gokb.pdf

KingbaseES 客户端编程接口指南-Gokb 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 驱动说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 配置说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 查看版本信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.4 导入说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.5 编译说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 第 3 章 管理连接 5 3.1 连接到数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 关闭连接 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.3 连接池 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 第 4 章 执行 SQL 语句 7 4.1 查询和结果集处理 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 执行非查询 SQL 语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.3 准备语句和绑定 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.4 类型映射 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 5 章 程序示例 9 5.1 连接数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.2 获取结果集 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 版权声明 12 服务周期承诺 13 I 第 1 章 前言 1 第 章 前言 本文档描述了...... 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES Gokb 指南面向所有使用 KingbaseES 数据库的用户，主要是 Go 语言应用程序开发人员。 1.2 相关文档 有关 Go 驱动程序的更多信息，请参阅以下资源： pkg.go.dev 1.3 术语 无 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 1 第 1 章 前言 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 • 驱动说明 • 配置说明 • 查看版本信息 • 导入说明 • 编译说明 2.1 驱动说明 Gokb 是基于 database/sql 包的、完全由 Golang 编写的 kingbase 驱动，它为数据库提供了轻量级的访问接口。 通常情况下，用户使用 database/sql 包，而不直接使用驱动包。驱动包提供了对具体操作的实现，而不对外提供 其实现细节。 本章主要说明了 Gokb 如何使用以及使用时应当注意的情况。 2.2 配置说明 首先，需要安装 golang，且配置 GOPATH 环境变量。 将 Gokb 驱动解压后，把 kingbase.com 文件夹放在某个目录下，以下均以 ~/drivers 目录为例。 2.3 查看版本信息 在 kingbase.com 文件夹下，执行命令 strings gokb.a |grep GOKBVersion ，即可查看驱动版本信息。如下图 所示： 3 第 2 章 概述 一般情况下，不同平台的驱动不能通用，但 Windows 版本的驱动也可以拷贝至 Linux 平台，然后使用同样的方 法查看版本信息。 2.4 导入说明 Gokb 实现了 database/sql 包的接口，因此，使用时需要导入 database/sql 包，还需要匿名导入驱动，如下所 示： import ( "database/sql" _ "kingbase.com/gokb" ) 2.5 编译说明 使用静态库时，不能直接使用 go run 或者 go build 命令，这样无法正确链接库。 需要手动指定导入库的路径和需要链接库的路径。如下所示，其中 test.go 为测试文件： go tool compile -I ~/drivers/ test.go # 指定导入库的路径 go tool link -L ~/drivers/ test.o # 指定链接库的路径 更进一步的信息，可以通过执行 go tool compile 和 go tool link 查看帮助说明。 4 第3章 管理连接 3 第 章 管理连接 • 连接到数据库 • 关闭连接 • 连接池 3.1 连接到数据库 我们可以使用以下语句连接到数据库： connStr := "host=127.0.0.1 user=SYSTEM password=123456 dbname=TEST" db, err := sql.Open("kingbase", connStr) err = db.Ping() 和其他语言不同，Open 函数并不会建立连接，也不会验证连接参数。 Go 语言使用惰性求值，仅在初次使用时才会建立连接，因此，需要使用 Ping 函数进行检查。 连接参数说明可参考下表。 表 3.1.1: 连接参数说明 参数名 说明 备注 host 数据库服务器的地址，包括域名、主机名、 默认为 localhost 主机的 IP 地址等，也可以是 UNIX domain socket port 端口号 user 登录的用户名 password 用户名的密码 默认为 54321 见续表 5 第3章 管理连接 表 3.1.1 – 续表 参数名 说明 dbname 连接至的数据库名 sslmode 是否使用 SSL 备注 默认开启使用; 可选参数为 “Disable, Require, verify-ca, verify-full“ sslcert 证书路径，必须包含 PEM 编码数据 sslkey 密钥文件路径，必须包含 PEM 编码数据 sslrootcert 根证书路径，必须包含 PEM 编码数据 connect_timeout 连接的最长等待时间，单位为秒 0 值或未指定均为无限等待 连接参数之间以空格分隔，若参数值包含空格，需要使用”（单引号）将该值括起来。示例： "user=SYSTEM password=123456 dbname=TEST sslmode=disable" "user='space man' password='it\'s valid'" 3.2 关闭连接 要关闭与数据库的连接，只需要对数据库对象 db 调用 Close 方法。 db.Close() 但 db 对象是为了长连接而设计的，如无必要，不要频繁调用 Open 和 Close 函数，尽量遵守 database/sql 库的 设计准则。 3.3 连接池 database/sql 包中实现了通用的连接池，只提供了非常简单的接口，除了限制连接数和设置生命周期外，基本没 有定制选项。 db 对象代表着 0 到多个底层连接的连接池，可以安全地被多个 Go 协程并发使用。 Go 会自动创建并管理连接，也保持空闲的连接。 当调用 Begin 函数开启事务时，返回的对象才会绑定到单个连接上，调用 Commit 或 Rollback 后，该事务绑定 的连接才会返回到连接池中。 6 第 4 章 执行 SQL 语句 4 第 章 执行 SQL 语句 • 查询和结果集处理 • 执行非查询 SQL 语句 • 准备语句和绑定 • 类型映射 4.1 查询和结果集处理 使用 Query 函数来发送查询到数据库，获取结果集信息和错误信息。 Next 函数作为循环条件，迭代读取结果集，该过程中发生错误会返回 False 。 Scan 函数用于读取一行结果。 rows, err := db.Query("SELECT id FROM TEST") defer rows.Close() for rows.Next() { var id int if err = rows.Scan(&id); err != nil { } fmt.Println("id=", n) } 4.2 执行非查询 SQL 语句 直接执行 Exec 函数即可。 7 第 4 章 执行 SQL 语句 _, err = db.Exec('CREATE TABLE TEST (id INTEGER PRIMARY KEY, name TEXT)') _, err = db.Exec("INSERT INTO TEST(id, name) VALUES(1, 'John')") 4.3 准备语句和绑定 Go 语言建议使用 Prepare 方式而非拼接字符串，以此来转义参数，避免 sql 注入，同时也省去了部分开销，提 高了性能。 占位符使用 PostgreSQL 风格，即”$N”，其中 N 是从 1 递增的整数，表示参数的位置。 stmt, err := db.Prepare("INSERT INTO TEST(id, name) VALUES($1,$2)") _, err = stmt.Exec(2,'Tom') stmt, err = db.Prepare("SELECT name FROM TEST WHERE id = $1") rows, err = stmt.Query(2) 4.4 类型映射 当 Go 应用和 KingbaseES 服务器交换信息时，需要在 KingbaseES 数据类型和 Go 变量类型之间进行转换。 类型映射说明可参考下表。 表 4.4.1: 类型映射数说明 KingbaseES 数据类型 Go 变量类型 整数类型（smallint, integer, bigint） int64 浮点类型（real, double） float64 字符类型（char, varchar, text, clob） string 时间类型（date, time, timetz, timestamp, timestamptz） time.Time 布尔类型（boolean） bool 二进制类型（bytea, blob） []byte 其他类型 []byte 8 第5章 程序示例 5 第 章 程序示例 以下为几个常用功能的程序示例： • 连接数据库 • 获取结果集 您可前往 人大金仓官网 下载 Golang 测试用例 。 连接数据库 5.1 package main import ( "database/sql" "fmt" _ "kingbase.com/gokb" ) const ( host = "127.0.0.1" port = 54321 user = "system" password = "123456" dbname = "TEST" ) func main() { connInfo := fmt.Sprintf("host=%s port=%d user=%s "+ "password=%s dbname=%s sslmode=disable", host, port, user, password, dbname) db, err = sql.Open("kingbase", connInfo) 9 第5章 程序示例 if err != nil { panic(err) } err = db.Ping() if err != nil { panic(err) } fmt.Println("Connection test success!") db.Close() } 获取结果集 5.2 package main import ( "database/sql" "fmt" _ "kingbase.com/gokb" ) const ( host = "127.0.0.1" port = 54321 user = "system" password = "123456" dbname = "TEST" ) type GoTable struct { Num int `db:"num"` Text string `db:"text"` Blob []byte `db:"blob"` Clob string `db:"clob"` } func main() { connInfo := fmt.Sprintf("host=%s port=%d user=%s "+ "password=%s dbname=%s sslmode=disable", 10 第5章 程序示例 host, port, user, password, dbname) db, err = sql.Open("kingbase", connInfo) if err != nil { panic(err) } err = db.Ping() if err != nil { panic(err) } db.Close() var data []*GoTable rows, err := db.Query("select * from temp_golang_test;") defer rows.Close() if err != nil { return nil, err } for rows.Next() { var row GoTable err = rows.Scan(&row.Num, &row.Text, &row.Blob, &row.Clob) if err != nil { return nil, err } data = append(data, &row) } for i := 0; i < len(data); i++ { fmt.Println(data[i]) } } 11 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 12 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 13 服务周期承诺 开方式宣布产品服务终止日期。 14