type DB
DB 结构体类型代表零个或多个基础连接的数据库句柄,对于多个 goroutine 协程并发使用是安全的。database/sql 软件包会自动创建并释放连接,它还维护空闲连接的连接池。
方法
Open()
功能
打开一个由其数据库驱动名称和特定于驱动程序的数据源名称指定的数据库,该名称通常由数据库名称和连接信息组成。
原型
go
func Open (driverName, dataSourceName string) (*DB, error)
参数
driverName : 数据库驱动名称,虚谷驱动名称为 "xugu" 。
dataSourceName : 连接字符串,里面是各个连接参数的键值对,连接字符串包含多个键值对,以分号分隔。
说明
键值 | 键值说明 |
---|---|
IP | 服务端的IP地址 |
IPS | 多IP创建连接(IP与IP之间使用逗号间隔) |
PORT | 连接的端口信息 |
DBNAME | 连接的数据库名 |
USER | 连接的用户名 |
PASSWORD | 该用户名对应的口令 |
CHAR_SET | 应用端使用的字符集 |
提示
其他数据库会话连接参数,直接使用数据库会话连接参数名传递参数。
返回值
返回 DB 类型的指针
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
SetConnMaxLifetime()
功能
设置可以重用连接的最长时间,过期的连接可以在重新使用之前延迟关闭,如果给定参数值 <=0, 则连接永远重复使用。
原型
go
func (db *DB)SetConnMaxLifetime(d time.Duration)
参数
- d : 连接的最长重用时间。
返回值
无返回值。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Dura, err := time.ParseDuration("30m")
if err != nil {
log.Fatal(err)
}
db.SetConnMaxLifetime(Dura)
SetMaxIdleConns()
功能
设置空闲连接池中的最大连接数,如果 MaxOpenConns 大于 0 但小于新的 MaxIdleConns,则新的 MaxIdleConns 将减少以匹配 MaxOpenConns 限制。如果参数 <= 0, 则不保留空闲连接。
原型
go
func (db *DB)SetMaxIdleConns(n int)
参数
- n : 连接池中的最大连接数。
返回值
无返回值。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
db.SetMaxIdleConns(5)
SetMaxOpenConns()
功能
设置与数据库的最大打开连接数。
原型
go
func (db *DB)SetMaxOpenConns(n int)
参数
- n : 与数据库的最大打开连接数。
返回值
无返回值。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
db.SetMaxOpenConns(5)
Begin()
功能
开启数据库事务。
原型
go
func (db *DB) Begin() (*Tx, error)
参数
无参数。
返回值
*Tx : 返回 Tx 类型的指针
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
Close()
功能
将关闭数据库并阻止启用新查询,然后等待所有已经在服务器上处理的查询完成。该方法通常很少使用,因为数据库句柄是长期存在的并且在多个 goroutine 之间共享。
原型
go
func (db *DB) Close() error
参数
无参数。
返回值
- error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
db.Close()
Conn()
功能
通过打开新连接或从连接池返回现有连接来返回单个连接。
原型
go
func (db *DB) Conn(ctx context.Context) (*Conn, error)
参数
- ctx : 上下文。
返回值
*Conn : Conn 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
conn, err := db.Conn(context.Background())
Exec()
功能
执行 SQL 语句而不返回任何行。
原型
go
func (db *DB) Exec (query string, args ...interface{}) (Result,error)
参数
query : SQL 语句。
args : 参数组。
返回值
Result : Result 类型对象。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
_, err = db.Exec("create table go_test(c1 int, c2 varchar);")
if err != nil {
log.Fatal(err)
}
db.Close()
ExecContext()
功能
结合上下文执行 SQL 语句而不返回任何行。
原型
go
func (db *DB) ExecContext (ctx context.Contextquery,query string, args...interface{}) (Result, error)
参数
ctx : 上下文信息。
query : SQL 语句。
args : 参数组。
返回值
Result : Result 类型对象。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
_, err = db.ExecContext(context.Background,"create table go_test(c1 int, c2 varchar);")
if err != nil {
log.Fatal(err)
}
db.Close()
Ping()
功能
验证当前到数据库的连接是否仍然有效,并在必要时建立连接。
原型
go
func (db *DB) Ping () error
参数
无参数。
返回值
- error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"fmt"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
err = db.Ping()
if err != nil {
fmt.Printf("connect xugu dbms ... failed\n")
} else {
fmt.Printf("connect xugu dbms ... ok\n")
}
err = db.Close()
PingContext()
功能
验证当前到数据库的连接是否仍然有效,并在必要时建立连接。
原型
go
func (db *DB) PingContext(ctx context.Context) error
参数
- ctx : 上下文信息。
返回值
- error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"fmt"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
err = db.PingContext(context.Background())
if err != nil {
fmt.Printf("connect xugu dbms ... failed\n")
} else {
fmt.Printf("connect xugu dbms ... ok\n")
}
err = db.Close()
Prepare()
功能
为以后的查询或执行创建准备好的语句。
原型
go
func (db *DB) Prepare (query string) (*Stmt, error)
参数
- query : 待执行的 SQL 语句。
返回值
*Stmt : Stmt 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
stmt, err := db.Prepare("insert into go_test values(?, ?);")
if err != nil {
log.Fatal(err)
}
_, err = stmt.Exec(3, "xugusql")
if err != nil {
log.Fatal(err)
}
stmt.Close()
PrepareContext()
功能
为以后的查询或执行创建准备好的语句。
原型
go
func (db *DB) PrepareContext (ctx context.Context, query string) (*Stmt, error)
参数
ctx : 上下文信息。
query : 待执行的 SQL 语句。
返回值
*Stmt : Stmt 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
stmt, err := db.PrepareContext("insert into go_test values(?, ?);")
if err != nil {
log.Fatal(err)
}
_, err = stmt.Exec(3, "xugusql")
if err != nil {
log.Fatal(err)
}
stmt.Close()
Query()
功能
执行返回行的查询,通常是 SELECT。
原型
go
func (db *DB) Query (query string, args ...interface{}) (*Rows,error)
参数
query : 待执行的查询 SQL 语句。
args : 查询中的任何占位符参数。
返回值
*Rows : Rows 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
rows, err := db.Query("select c1, c2 from go_test")
QueryContext()
功能
执行返回行的查询,通常是 SELECT。
原型
go
func (db *DB) QueryContext (ctx context.Context, query string, args...interface{}) (*Rows, error)
参数
ctx : 上下文信息。
query : 待执行的查询 SQL 语句。
args : 查询中的任何占位符参数。
返回值
*Rows : Rows 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
rows, err := db.QueryContext("select c1, c2 from go_test")
QueryRow()
功能
执行最多返回一行的查询。
原型
go
func (db *DB) QueryRow (query string, args ...interface{}) *Row
参数
query : 待执行的查询 SQL 语句。
args : 查询中的任何占位符参数。
返回值
- *Row : Row 类型指针。
说明
QueryRow 始终返回非 nil 值,错误将延迟到调用 Row 的 Scan 方法之前。如果查询未选择任何行,则在调用 Scan 时返回 ErrNoRows;否则,返回结果集中的第一行,并丢弃其余的行。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
rows, err := db.QueryRow("select c1, c2 from go_test limit 1")
QueryRowContext()
功能
执行最多返回一行的查询。
原型
go
func (db *DB) QueryRowContext (ctx context.Context, query string, args ...interface{}) *Row
参数
ctx : 上下文信息。
query : 待执行的查询 SQL 语句。
args : 查询中的任何占位符参数。
返回值
- *Row : Row 类型指针。
说明
QueryRow 始终返回非 nil 值,错误将延迟到调用 Row 的 Scan 方法之前。如果查询未选择任何行,则在调用 Scan 时返回 ErrNoRows;否则,返回结果集中的第一行,并丢弃其余的行。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
rows, err := db.QueryRowContext(context.Background(), "select c1, c2 from go_test limit 1")
type Stmt
方法
Exec()
功能
用给定的参数执行一条准备好的 SQL 语句,并返回一个 Result 类型的结果对象。
原型
go
func (s *Stmt) Exec(args ...interface{}) (Result, error)
参数
query : SQL 语句。
args : 参数组。
返回值
Result : Result 类型对象。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
stmt, err := db.Prepare("insert into go_test values(?, ?);")
if err != nil {
log.Fatal(err)
}
res, _ := stmt.Exec(4, "Exec")
db.Close()
Query()
功能
用给定的参数执行一条准备好的查询语句,并将查询结果作为 *Rows 返回。
原型
go
func (s *Stmt) Query(args ...interface{}) (*Rows, error)
参数
query : 待执行的查询 SQL 语句。
args : 查询中的任何占位符参数。
返回值
*Rows : Rows 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
stmt, _ := db.Prepare("select * from go_test where id = ?;")
rows, err := stmt.Query(3)
if err != nil {
log.Fatal(err)
}
}
QueryRow()
功能
执行最多返回一行的查询。
原型
go
func (s *Stmt) QueryRow (args ...interface{}) *Row
参数
- args : 查询中的任何占位符参数。
返回值
- *Row : Row 类型指针。
说明
QueryRow 始终返回非 nil 值,错误将延迟到调用 Row 的 Scan 方法之前。如果查询未选择任何行,则在调用 Scan 时返回 ErrNoRows;否则,返回结果集中的第一行,并丢弃其余的行。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
stmt, _ := db.Prepare("select c1,c2,c3 from go_1th;")
row := stmt.QueryRow()
type Rows
方法
Next()
功能
准备下一个结果行,以使用 Scan 方法读取。
原型
go
func (s *Rows) Next() bool
参数
无参数。
返回值
成功时返回 true,如果没有下一个结果行或错误,则返回 false。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
stmt, _ := db.Prepare("select * from go_test;")
rows, err := stmt.Query()
if err != nil {
log.Fatal(err)
}
for rows.Next() {
fmt.Printf("\n")
}
Columns()
功能
返回查询结果列名。
原型
go
func (s *Rows) Columns() ([]string, error)
参数
无参数。
返回值
[]string : 列名数组。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
stmt, _ := db.Prepare("select * from go_test;")
rows, err := stmt.Query()
if err != nil {
log.Fatal(err)
}
var cols []string
cols, err = rows.Columns()
if err != nil {
log.Fatal(err)
}
NextResultSet()
功能
准备下一个要读取的结果集。
原型
go
func (s *Rows) NextResultSet() bool
参数
无参数。
返回值
如果没有更多结果集或者报错,则为 false 。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
rows, err := db.Query("select * from go_1th;select * from go_2th;")
if err != nil {
log.Fatal(err)
}
if !rows.NextResultSet() {
}
Close()
功能
用于关闭 Rows,如果调用 Next 并返回 false, 并且没有其他结果集,则将自动关闭 Rows。
原型
go
func (s *Rows) Close() error
参数
无参数。
返回值
- error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
rows, err := db.Query("select * from go_test;")
if err != nil {
log.Fatal(err)
}
rows.Close()
db.Close()
Scan()
功能
将当前 Rows 中的列复制到 dest 指向的值中。dest 中的值数必须与 Rows 中的列数相同。
原型
go
func (s *Rows) Scan(dest ...interface{}) error
参数
- dest : 接收数据的 interface 数组。
返回值
- error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
rows, err := db.Query("select c1,c2 from go_test;")
var cols []string
cols, err = rows.Columns()
if err != nil {
log.Fatal(err)
}
pvals := make([]interface{}, len(cols))
for key, _ := range pvals {
dest := make([]byte, 216)
pvals[key] = &dest
} /* end for */
for rows.Next() {
err = rows.Scan(pvals...)
if err != nil {
log.Fatal(err)
}
for _, v := range pvals {
fmt.Printf("%s\t", string(*(v.(*[]byte))))
}
fmt.Printf("\n")
}
rows.Close()
type Tx
方法
Commit()
功能
提交当前事务。
原型
go
func (tx *Tx) Commit() error
参数
无参数。
返回值
- error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
Tx.Commit()
Rollback()
功能
回滚当前事务。
原型
go
func (tx *Tx) Rollback() error
参数
无参数。
返回值
- error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
Tx.Rollback()
Exec()
功能
执行 SQL 语句而不返回任何行。
原型
go
func (tx *Tx) Exec (query string, args ...interface{}) (Result,error)
参数
query : SQL 语句。
args : 参数组。
返回值
Result : Result 类型对象。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
_, err = Tx.Exec("insert into go_1th values(100, 0.2, 0.2);")
if err != nil {
log.Fatal(err)
}
db.Close()
Prepare()
功能
为以后的查询或执行创建准备好的语句。
原型
go
func (tx *Tx) Prepare(query string) (*Stmt, error)
参数
- query : 待执行的 SQL 语句。
返回值
*Stmt : Stmt 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
if err != nil {
log.Fatal(err)
}
stmt, _ = Tx.Prepare("insert into go_test values(?, ?);")
Query()
功能
执行返回行的查询,通常是 SELECT。
原型
go
func (tx *Tx) Query (query string, args ...interface{}) (*Rows,error)
参数
query : 待执行的查询 SQL 语句。
args : 查询中的任何占位符参数。
返回值
*Rows : Rows 类型指针。
error : 错误信息。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
if err != nil {
log.Fatal(err)
}
_, err = Tx.Query("select c1, c2 from go_test")
if err != nil {
log.Fatal(err)
}
QueryRow()
功能
执行最多返回一行的查询。
原型
go
func (tx *Tx) QueryRow (query string, args ...interface{}) *Row
参数
query : 待执行的查询 SQL 语句。
args : 查询中的任何占位符参数。
返回值
- *Row : Row 类型指针。
说明
QueryRow 始终返回非 nil 值,错误将延迟到调用 Row 的 Scan 方法之前。如果查询未选择任何行,则在调用 Scan 时返回 ErrNoRows;否则,返回结果集中的第一行,并丢弃其余的行。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
if err != nil {
log.Fatal(err)
}
row := Tx.QueryRow("select c1,c2,c3 from go_1th;")
Stmt()
功能
从现有语句返回特定于事务的预准备语句。
原型
go
func (tx *Tx) Stmt(stmt *Stmt) *Stmt
参数
- stmt : Stmt 类型指针。
返回值
- *Stmt : Stmt 类型指针。
示例
go
package main
import (
_ "gitee.com/XuguDB/go-xugu-driver"
"database/sql"
"log"
)
db, err := sql.Open("xugu", "IP=127.0.0.1;DB=SYSTEM;User=SYSDBA;PWD=SYSDBA;Port=5138;CHAR_SET=UTF8")
Tx, err := db.Begin()
if err != nil {
log.Fatal(err)
}
stmt, err := db.Prepare("insert into go_test values(?, ?);")
_, err = Tx.Stmt(stmt).Exec(3, "xugusql")
if err != nil {
log.Fatal(err)
}