概述

Golang使用UXDB数据库，需要使用uxdb-golang模块来连接，Linux平台也可以使用该模块进行连接。

1. 安装Golang

官网下载安装Golang：https://golang.google.cn/ Golang版本要求：Go >= 1.10

官网提供多种平台的安装包，根据实际情况进行下载。

  • Windows

    a. 下载对应Windows环境的安装包，后缀名为.msi。

    b. 双击运行，直接进行下一步，注意GOROOT为GO语言的主目录，GOPATH为工作目录。

    c. 默认安装go语言完成后，会自动添加环境变量，若自主修改了GOROOT与GOPATH目录路径，则需要修改环境变量。

    d. 完成后可在CMD命令行运行go version来查看版本号信息。

  • Linux

    a. 下载对应Linux环境的安装包，后缀名为.tar.gz。

    b. 执行tar命令解压安装包至/usr/local目录下（官方推荐目录）。

    c. 添加/usr/local/go/bin目录到path变量中，在/etc/profile文件最后一行添加：

    export GOROOT=/usr/local/go
export PATH=$PATH:$GOROOT/bin

    保存后，执行如下命令：

    source /etc/profile

    d. 安装完成之后执行go version，如果出现版本号信息，则Go环境安装成功。

2. 创建环境并连接数据库

a. 在GOPATH工作目录下创建工程文件夹。如：GOPATH目录为E:\go，在E:\go目录下创建一个工程文件夹，如：uxdb_test

b. 在工程文件夹uxdb_test下创建test.go文件，内容如下：

连接UXDB oracle模式数据库，数据库名（dbname）和用户（user）需要大写。

package main
import (
  "database/sql"
  "fmt"
  _ "uxdb-golang" //_操作其实只是引入该包。当导入一个包时，它所有的init()函数就会被执行，但有些时候并非真的需要使用这些包，仅仅是希望它的init()函数被执行而已。这个时候就可以使用_操作引用该包
)
var db *sql.DB
var err error                       //定义全局变量
func sqlOpen() {
  db, err = sql.Open("uxdb", "host=192.168.168.128 port=5432 user=uxdb password=****** dbname=uxdb sslmode=disable")
  //driverName是数据库驱动类型名称，uxdb的go语言驱动名称为uxdb;
  //port是数据库的端口号，默认是5432;
  //user是数据库的登录帐号;
  //dbname是数据库名称;
  //sslmode是安全验证模式,disable为不使用ssl加密方式连接;
  if err != nil {
      fmt.Println("连接数据库错误：" + err.Error())
  } else {
      fmt.Println("数据库连接成功")
  }
  err = db.Ping() //Ping检查与数据库的连接是否有效,如果失效返回error信息
  if err != nil {
      fmt.Println("DBPing错误：" + err.Error())
  } else
  {
      fmt.Println("DBPingSuccess")
  }
}
func sqlcreate() {
  fmt.Println("*****开始创建表*****")
  createsql := "create table Student(Sno int,Sname char(10),Sage int,Ssex char(10));"
  stmt, err := db.Prepare(createsql)
  if err != nil {
      fmt.Print(err.Error())
  } else {
      fmt.Println("create table successfully")
  }
  stmt.Exec()
}

func sqlInsert() {
  //插入数据
  fmt.Println("+++++开始进行数据库插入+++++")
  stmt, err := db.Prepare("INSERT INTO student(sno,sname,sage,ssex) VALUES($1,$2,$3,$4) ")
  checkErr(err)
  res, err := stmt.Exec("1", "mary", "22", "女")
  checkErr(err)
  affect, err := res.RowsAffected()  //RowsAffected返回被update、insert或delete命令影响的行数
  checkErr(err)
  fmt.Println("受影响的行:", affect)
}

func sqlInsert1() {
  //插入数据
  fmt.Println("+++++开始进行数据库插入+++++")
  stmt, err := db.Prepare("INSERT INTO student(sno,sname,sage,ssex) VALUES($1,$2,$3,$4) ")
  checkErr(err)
  res, err := stmt.Exec("2", "jack", "23", "男")
  checkErr(err)
  affect, err := res.RowsAffected()  //RowsAffected返回被update、insert或delete命令影响的行数
  checkErr(err)
  fmt.Println("受影响的行:", affect)
}
func sqlDelete() {
  //删除数据
  fmt.Println("=====开始删除数据=====")
  stmt, err := db.Prepare("delete from student where sno=$1")
  checkErr(err)
  res, err := stmt.Exec(1)
  checkErr(err)
  affect, err := res.RowsAffected()
  checkErr(err)
  fmt.Println("受影响的行:", affect)
}
func sqlSelect() {
  //查询数据
  fmt.Println("*****开始进行数据库查询*****")
  rows, err := db.Query("SELECT * FROM student")
  checkErr(err)
  for rows.Next() {
      var sno int
      var sname string
      var sage int
      var ssex string
      err = rows.Scan(&sno, &sname, &sage, &ssex)
      checkErr(err)
      fmt.Println("sno = ", sno, "\nsname = ", sname, "\nsage = ", sage, "\nssex = ", ssex, "\n-----------")
  }
}
func sqlUpdate() {
  //更新数据
  fmt.Println("#####开始进行数据更新#####")
  stmt, err := db.Prepare("update student set sname=$1 where sno=$2")
  checkErr(err)
  res, err := stmt.Exec("uxsino", 1)
  checkErr(err)
  affect, err := res.RowsAffected()
  checkErr(err)
  fmt.Println("受影响的行:", affect)
}
func sqlClose() {
  //关闭数据库
  db.Close()
}
func checkErr(err error) {
  //定义异常排查函数
  if err != nil {
      panic(err)
  }
}
func sqlTest() {
  //创建测试函数，调用增删改查函数进行数据库操作
  sep := "----------\n"

  sqlInsert()
  sqlInsert1()
  sqlSelect()

  sqlUpdate()
  sqlSelect()

  sqlDelete()
  sqlSelect()

  sqlClose()
  println(sep, "数据库已关闭")
}
func main() {
  //运行打开数据库函数
  sqlOpen()
  //运行创建表函数
  sqlcreate()
  //运行增删改查测试函数
  sqlTest()
}

c. 将GO语言数据库驱动uxdb-golang分别放在test.go的同级目录和GOROOT的src目录下。

GOROOT目录：windows一般在C:\Go\src目录下；Linux一般在/usr/local/go/src目录下。根据实际安装golang时的环境变量而定。

d. 运行结果

  • Windows：打开cmd窗口，进入test.go所在的目录，执行命令go run test.go运行。

  • Linux：打开终端，进入test.go所在的目录，执行命令go run test.go运行。

E:\go\uxdb_test>go run test.go
数据库连接成功
DB Ping Success

***** 开始创建表 *****
create table successfully

+++++ 开始进行数据库插入 +++++
受影响的行：1

+++++ 开始进行数据库插入 +++++
受影响的行：1

***** 开始进行数据库查询 *****
sno: 1
sname: mary
sage: 22
ssex: 女

sno: 2
sname: jack
sage: 23
ssex: 男

##### 开始进行数据更新 #####

受影响的行：1

***** 开始进行数据库查询 *****
sno: 2
sname: jack
sage: 23
ssex: 男

sno: 1
sname: uxsino
sage: 22
ssex: 女

==== 开始删除数据 ====
受影响的行：1

***** 开始进行数据库查询 *****
sno: 2
sname: jack
sage: 23
ssex: 男

数据库已关闭

3.接口介绍

3.1.包级函数

3.1.1.sql.Drivers

  • 功能

    列出当前已注册的所有驱动名（UXDB 驱动注册名为 uxdb）

  • 函数

    func Drivers() []string

  • 参数：无。

  • 返回值

    返回当前已注册驱动名称的字符串切片。

3.1.2.sql.Register

  • 功能

    向 database/sql 注册一个驱动实现

  • 函数

    func Register(name string, driver driver.Driver)

  • 参数

    表 Register 参数说明

    名称描述
    name（输入）驱动名称。
    driver（输入）驱动实现。

  • 返回值

    无返回值。

3.1.3.sql.Open

  • 功能

    按驱动名与连接串创建数据库句柄（惰性连接，不实际建连）

  • 函数

    func Open(driverName, dataSourceName string) (*DB, error)；用法 sql.Open("uxdb", "host=... port=... user=... password=... dbname=... sslmode=disable")

  • 参数

    表 Open 参数说明

    名称描述
    driverName（输入）驱动名称，如 uxdb。
    dataSourceName（输入）数据源名称（连接串），如 host=... port=... user=... password=... dbname=... sslmode=disable。

  • 返回值

    返回数据库句柄指针 *DB 和错误信息 error。

3.1.4.sql.OpenDB

  • 功能

    用自定义 Connector 创建数据库句柄

  • 函数

    func OpenDB(c driver.Connector) *DB

  • 参数

    表 OpenDB 参数说明

    名称描述
    c（输入）自定义的连接器 Connector。

  • 返回值

    返回数据库句柄指针 *DB。

3.1.5.sql.Named

  • 功能

    构造带名字的查询参数

  • 函数

    func Named(name string, value any) NamedArg

  • 参数

    表 Named 参数说明

    名称描述
    name（输入）参数名。
    value（输入）参数值。

  • 返回值

    返回带名字的查询参数 NamedArg。

3.2.包级变量

3.2.1.sql.ErrConnDone

  • 功能

    连接已被关闭时返回的错误

  • 函数

    var ErrConnDone = errors.New("sql: connection is already closed")

  • 参数：无。

  • 返回值

    该变量为 error 错误对象，表示连接已被关闭。

3.2.2.sql.ErrNoRows

  • 功能

    QueryRow 未查询到任何行时返回的错误

  • 函数

    var ErrNoRows = errors.New("sql: no rows in result set")

  • 参数：无。

  • 返回值

    该变量为 error 错误对象，表示 QueryRow 未查询到任何行。

3.2.3.sql.ErrTxDone

  • 功能

    事务已提交或回滚后继续操作返回的错误

  • 函数

    var ErrTxDone = errors.New("sql: transaction has already been committed or rolled back")

  • 参数：无。

  • 返回值

    该变量为 error 错误对象，表示事务已提交或回滚。

3.3.sql.DB（连接池句柄）

3.3.1.DB.Begin

  • 功能

    开启一个事务

  • 函数

    Begin() (*Tx, error)

  • 参数：无。

  • 返回值

    返回事务对象 *Tx 和错误信息 error。

3.3.2.DB.BeginTx

  • 功能

    按指定隔离级别与只读属性开启事务

  • 函数

    BeginTx(ctx, opts *TxOptions) (*Tx, error)

  • 参数

    表 BeginTx 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    opts（输入）事务选项 TxOptions，指定隔离级别与只读属性。

  • 返回值

    返回事务对象 *Tx 和错误信息 error。

3.3.3.DB.Close

  • 功能

    关闭数据库句柄并释放连接池中的连接

  • 函数

    Close() error

  • 参数：无。

  • 返回值

    返回错误信息 error。

3.3.4.DB.Conn

  • 功能

    从连接池中独占取出一条连接

  • 函数

    Conn(ctx) (*Conn, error)

  • 参数

    表 Conn 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。

  • 返回值

    返回独占连接 *Conn 和错误信息 error。

3.3.5.DB.Driver

  • 功能

    返回底层驱动实现

  • 函数

    Driver() driver.Driver

  • 参数：无。

  • 返回值

    返回底层驱动实现 driver.Driver。

3.3.6.DB.Exec

  • 功能

    执行不返回结果集的语句（INSERT/UPDATE/DELETE/DDL）

  • 函数

    Exec(query string, args ...any) (Result, error)

  • 参数

    表 Exec 参数说明

    名称描述
    query（输入）SQL 语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回执行结果 Result 和错误信息 error。

3.3.7.DB.ExecContext

  • 功能

    带 context 的 Exec，可取消与超时

  • 函数

    ExecContext(ctx, query string, args ...any) (Result, error)

  • 参数

    表 ExecContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回执行结果 Result 和错误信息 error。

3.3.8.DB.Ping

  • 功能

    检测数据库连通性

  • 函数

    Ping() error

  • 参数：无。

  • 返回值

    返回错误信息 error。

3.3.9.DB.PingContext

  • 功能

    带 context 的连通性检测

  • 函数

    PingContext(ctx) error

  • 参数

    表 PingContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。

  • 返回值

    返回错误信息 error。

3.3.10.DB.Prepare

  • 功能

    预处理一条语句，返回可重复使用的 Stmt

  • 函数

    Prepare(query string) (*Stmt, error)

  • 参数

    表 Prepare 参数说明

    名称描述
    query（输入）SQL 语句。

  • 返回值

    返回预处理语句 *Stmt 和错误信息 error。

3.3.11.DB.PrepareContext

  • 功能

    带 context 的语句预处理

  • 函数

    PrepareContext(ctx, query string) (*Stmt, error)

  • 参数

    表 PrepareContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 语句。

  • 返回值

    返回预处理语句 *Stmt 和错误信息 error。

3.3.12.DB.Query

  • 功能

    执行查询并返回多行结果集

  • 函数

    Query(query string, args ...any) (*Rows, error)

  • 参数

    表 Query 参数说明

    名称描述
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回结果集 *Rows 和错误信息 error。

3.3.13.DB.QueryContext

  • 功能

    带 context 的查询执行

  • 函数

    QueryContext(ctx, query string, args ...any) (*Rows, error)

  • 参数

    表 QueryContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回结果集 *Rows 和错误信息 error。

3.3.14.DB.QueryRow

  • 功能

    执行查询并返回单行结果

  • 函数

    QueryRow(query string, args ...any) *Row

  • 参数

    表 QueryRow 参数说明

    名称描述
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回单行结果 *Row。

3.3.15.DB.QueryRowContext

  • 功能

    带 context 的单行查询

  • 函数

    QueryRowContext(ctx, query string, args ...any) *Row

  • 参数

    表 QueryRowContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回单行结果 *Row。

3.3.16.DB.SetConnMaxIdleTime

  • 功能

    设置连接在池中最大空闲时长

  • 函数

    SetConnMaxIdleTime(d time.Duration)

  • 参数

    表 SetConnMaxIdleTime 参数说明

    名称描述
    d（输入）连接在池中允许空闲的最大时长。

  • 返回值

    无返回值。

3.3.17.DB.SetConnMaxLifetime

  • 功能

    设置连接的最大存活时长

  • 函数

    SetConnMaxLifetime(d time.Duration)

  • 参数

    表 SetConnMaxLifetime 参数说明

    名称描述
    d（输入）连接允许存活的最大时长。

  • 返回值

    无返回值。

3.3.18.DB.SetMaxIdleConns

  • 功能

    设置空闲连接数的上限

  • 函数

    SetMaxIdleConns(n int)

  • 参数

    表 SetMaxIdleConns 参数说明

    名称描述
    n（输入）空闲连接数的上限。

  • 返回值

    无返回值。

3.3.19.DB.SetMaxOpenConns

  • 功能

    设置打开连接数的上限

  • 函数

    SetMaxOpenConns(n int)

  • 参数

    表 SetMaxOpenConns 参数说明

    名称描述
    n（输入）打开连接数的上限。

  • 返回值

    无返回值。

3.3.20.DB.Stats

  • 功能

    返回连接池运行统计

  • 函数

    Stats() DBStats

  • 参数：无。

  • 返回值

    返回连接池运行统计 DBStats。

3.4.sql.Conn（独占连接）

3.4.1.Conn.BeginTx

  • 功能

    在该连接上开启事务

  • 函数

    BeginTx(ctx, opts *TxOptions) (*Tx, error)

  • 参数

    表 BeginTx 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    opts（输入）事务选项 TxOptions，指定隔离级别与只读属性。

  • 返回值

    返回事务对象 *Tx 和错误信息 error。

3.4.2.Conn.Close

  • 功能

    把连接归还连接池

  • 函数

    Close() error

  • 参数：无。

  • 返回值

    返回错误信息 error。

3.4.3.Conn.ExecContext

  • 功能

    在该连接上执行语句

  • 函数

    ExecContext(ctx, query string, args ...any) (Result, error)

  • 参数

    表 ExecContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回执行结果 Result 和错误信息 error。

3.4.4.Conn.PingContext

  • 功能

    在该连接上检测连通性

  • 函数

    PingContext(ctx) error

  • 参数

    表 PingContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。

  • 返回值

    返回错误信息 error。

3.4.5.Conn.PrepareContext

  • 功能

    在该连接上预处理语句

  • 函数

    PrepareContext(ctx, query string) (*Stmt, error)

  • 参数

    表 PrepareContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 语句。

  • 返回值

    返回预处理语句 *Stmt 和错误信息 error。

3.4.6.Conn.QueryContext

  • 功能

    在该连接上执行查询

  • 函数

    QueryContext(ctx, query string, args ...any) (*Rows, error)

  • 参数

    表 QueryContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回结果集 *Rows 和错误信息 error。

3.4.7.Conn.QueryRowContext

  • 功能

    在该连接上执行单行查询

  • 函数

    QueryRowContext(ctx, query string, args ...any) *Row

  • 参数

    表 QueryRowContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回单行结果 *Row。

3.4.8.Conn.Raw

  • 功能

    直接操作底层驱动连接（driver.Conn）

  • 函数

    Raw(f func(driverConn any) error) error

  • 参数

    表 Raw 参数说明

    名称描述
    f（输入）回调函数，其参数为底层驱动连接 driverConn。

  • 返回值

    返回错误信息 error。

3.5.sql.Stmt（预处理语句）

3.5.1.Stmt.Close

  • 功能

    关闭预处理语句并释放服务端资源

  • 函数

    Close() error

  • 参数：无。

  • 返回值

    返回错误信息 error。

3.5.2.Stmt.Exec

  • 功能

    执行预处理语句（非查询）

  • 函数

    Exec(args ...any) (Result, error)

  • 参数

    表 Exec 参数说明

    名称描述
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回执行结果 Result 和错误信息 error。

3.5.3.Stmt.ExecContext

  • 功能

    带 context 执行预处理语句

  • 函数

    ExecContext(ctx, args ...any) (Result, error)

  • 参数

    表 ExecContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回执行结果 Result 和错误信息 error。

3.5.4.Stmt.Query

  • 功能

    执行预处理语句并返回结果集

  • 函数

    Query(args ...any) (*Rows, error)

  • 参数

    表 Query 参数说明

    名称描述
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回结果集 *Rows 和错误信息 error。

3.5.5.Stmt.QueryContext

  • 功能

    带 context 执行预处理查询

  • 函数

    QueryContext(ctx, args ...any) (*Rows, error)

  • 参数

    表 QueryContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回结果集 *Rows 和错误信息 error。

3.5.6.Stmt.QueryRow

  • 功能

    执行预处理语句并返回单行

  • 函数

    QueryRow(args ...any) *Row

  • 参数

    表 QueryRow 参数说明

    名称描述
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回单行结果 *Row。

3.5.7.Stmt.QueryRowContext

  • 功能

    带 context 的预处理单行查询

  • 函数

    QueryRowContext(ctx, args ...any) *Row

  • 参数

    表 QueryRowContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回单行结果 *Row。

3.6.sql.Tx（事务）

3.6.1.Tx.Commit

  • 功能

    提交事务

  • 函数

    Commit() error

  • 参数：无。

  • 返回值

    返回错误信息 error。

3.6.2.Tx.Rollback

  • 功能

    回滚事务

  • 函数

    Rollback() error

  • 参数：无。

  • 返回值

    返回错误信息 error。

3.6.3.Tx.Exec

  • 功能

    在事务中执行语句

  • 函数

    Exec(query string, args ...any) (Result, error)

  • 参数

    表 Exec 参数说明

    名称描述
    query（输入）SQL 语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回执行结果 Result 和错误信息 error。

3.6.4.Tx.ExecContext

  • 功能

    在事务中带 context 执行语句

  • 函数

    ExecContext(ctx, query string, args ...any) (Result, error)

  • 参数

    表 ExecContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回执行结果 Result 和错误信息 error。

3.6.5.Tx.Prepare

  • 功能

    在事务中预处理语句

  • 函数

    Prepare(query string) (*Stmt, error)

  • 参数

    表 Prepare 参数说明

    名称描述
    query（输入）SQL 语句。

  • 返回值

    返回预处理语句 *Stmt 和错误信息 error。

3.6.6.Tx.PrepareContext

  • 功能

    在事务中带 context 预处理语句

  • 函数

    PrepareContext(ctx, query string) (*Stmt, error)

  • 参数

    表 PrepareContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 语句。

  • 返回值

    返回预处理语句 *Stmt 和错误信息 error。

3.6.7.Tx.Query

  • 功能

    在事务中执行查询

  • 函数

    Query(query string, args ...any) (*Rows, error)

  • 参数

    表 Query 参数说明

    名称描述
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回结果集 *Rows 和错误信息 error。

3.6.8.Tx.QueryContext

  • 功能

    在事务中带 context 执行查询

  • 函数

    QueryContext(ctx, query string, args ...any) (*Rows, error)

  • 参数

    表 QueryContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回结果集 *Rows 和错误信息 error。

3.6.9.Tx.QueryRow

  • 功能

    在事务中执行单行查询

  • 函数

    QueryRow(query string, args ...any) *Row

  • 参数

    表 QueryRow 参数说明

    名称描述
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回单行结果 *Row。

3.6.10.Tx.QueryRowContext

  • 功能

    在事务中带 context 执行单行查询

  • 函数

    QueryRowContext(ctx, query string, args ...any) *Row

  • 参数

    表 QueryRowContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    query（输入）SQL 查询语句。
    args（输入）SQL 参数值，可变参数。

  • 返回值

    返回单行结果 *Row。

3.6.11.Tx.Stmt

  • 功能

    把一条已预处理的语句绑定到本事务

  • 函数

    Stmt(stmt *Stmt) *Stmt

  • 参数

    表 Stmt 参数说明

    名称描述
    stmt（输入）已预处理的语句 Stmt。

  • 返回值

    返回绑定到本事务的预处理语句 *Stmt。

3.6.12.Tx.StmtContext

  • 功能

    带 context 地把预处理语句绑定到本事务

  • 函数

    StmtContext(ctx, stmt *Stmt) *Stmt

  • 参数

    表 StmtContext 参数说明

    名称描述
    ctx（输入）上下文 context.Context，用于控制超时与取消。
    stmt（输入）已预处理的语句 Stmt。

  • 返回值

    返回绑定到本事务的预处理语句 *Stmt。

3.7.sql.Rows（结果集）

3.7.1.Rows.Close

  • 功能

    关闭结果集，释放连接

  • 函数

    Close() error

  • 参数：无。

  • 返回值

    返回错误信息 error。

3.7.2.Rows.ColumnTypes

  • 功能

    返回各列的数据库类型元信息

  • 函数

    ColumnTypes() ([]*ColumnType, error)

  • 参数：无。

  • 返回值

    返回列类型信息切片 []*ColumnType 和错误信息 error。

3.7.3.Rows.Columns

  • 功能

    返回结果集的列名清单

  • 函数

    Columns() ([]string, error)

  • 参数：无。

  • 返回值

    返回列名字符串切片 []string 和错误信息 error。

3.7.4.Rows.Err

  • 功能

    返回遍历过程中发生的错误

  • 函数

    Err() error

  • 参数：无。

  • 返回值

    返回遍历过程中发生的错误信息 error。

3.7.5.Rows.Next

  • 功能

    移动到下一行，返回是否还有数据

  • 函数

    Next() bool

  • 参数：无。

  • 返回值

    返回布尔值 bool，表示是否还有下一行数据。

3.7.6.Rows.NextResultSet

  • 功能

    移动到下一个结果集

  • 函数

    NextResultSet() bool

  • 参数：无。

  • 返回值

    返回布尔值 bool，表示是否还有下一个结果集。

3.7.7.Rows.Scan

  • 功能

    把当前行各列的值扫描到目标变量

  • 函数

    Scan(dest ...any) error

  • 参数

    表 Scan 参数说明

    名称描述
    dest（输出）目标变量指针列表，按列顺序接收当前行的值。

  • 返回值

    返回错误信息 error。

3.8.sql.Row（单行结果）

3.8.1.Row.Err

  • 功能

    返回查询过程中发生的错误

  • 函数

    Err() error

  • 参数：无。

  • 返回值

    返回查询过程中发生的错误信息 error。

3.8.2.Row.Scan

  • 功能

    把单行结果扫描到目标变量

  • 函数

    Scan(dest ...any) error

  • 参数

    表 Scan 参数说明

    名称描述
    dest（输出）目标变量指针列表，按列顺序接收结果值。

  • 返回值

    返回错误信息 error。

3.9.sql.ColumnType（列元信息）

3.9.1.ColumnType.DatabaseTypeName

  • 功能

    返回列的数据库原生类型名

  • 函数

    DatabaseTypeName() string

  • 参数：无。

  • 返回值

    返回列的数据库原生类型名字符串。

3.9.2.ColumnType.DecimalSize

  • 功能

    返回列的精度与小数位数

  • 函数

    DecimalSize() (precision, scale int64, ok bool)

  • 参数：无。

  • 返回值

    返回精度 precision、小数位数 scale 以及是否有效 ok。

3.9.3.ColumnType.Length

  • 功能

    返回列的定义长度

  • 函数

    Length() (length int64, ok bool)

  • 参数：无。

  • 返回值

    返回列的定义长度 length 以及是否有效 ok。

3.9.4.ColumnType.Name

  • 功能

    返回列名

  • 函数

    Name() string

  • 参数：无。

  • 返回值

    返回列名字符串。

3.10.sql.Result（执行结果）

3.10.1.Result.LastInsertId

  • 功能

    返回最后插入记录的自增 ID

  • 函数

    LastInsertId() (int64, error)

  • 参数：无。

  • 返回值

    返回最后插入记录的自增 ID 和错误信息 error。

3.10.2.Result.RowsAffected

  • 功能

    返回受影响的行数

  • 函数

    RowsAffected() (int64, error)

  • 参数：无。

  • 返回值

    返回受影响的行数和错误信息 error。

3.11.sql.Scanner（扫描接口）

3.11.1.Scanner.Scan

  • 功能

    把数据库列值转换并写入自定义类型

  • 函数

    Scan(src any) error

  • 参数

    表 Scan 参数说明

    名称描述
    src（输入）数据库返回的列值。

  • 返回值

    返回错误信息 error。

3.12.其它类型·连接池统计

3.12.1.DBStats.MaxOpenConnections

  • 功能

    打开连接数的上限

  • 函数

    MaxOpenConnections int

  • 参数：无。

  • 返回值

    该字段为 int 类型，表示打开连接数的上限。

3.12.2.DBStats.OpenConnections

  • 功能

    当前已打开的连接数

  • 函数

    OpenConnections int

  • 参数：无。

  • 返回值

    该字段为 int 类型，表示当前已打开的连接数。

3.12.3.DBStats.InUse

  • 功能

    正在被使用的连接数

  • 函数

    InUse int

  • 参数：无。

  • 返回值

    该字段为 int 类型，表示正在被使用的连接数。

3.12.4.DBStats.Idle

  • 功能

    空闲连接数

  • 函数

    Idle int

  • 参数：无。

  • 返回值

    该字段为 int 类型，表示空闲连接数。

3.12.5.DBStats.WaitCount

  • 功能

    等待连接的累计次数

  • 函数

    WaitCount int64

  • 参数：无。

  • 返回值

    该字段为 int64 类型，表示等待连接的累计次数。

3.12.6.DBStats.WaitDuration

  • 功能

    等待连接的总时长

  • 函数

    WaitDuration time.Duration

  • 参数：无。

  • 返回值

    该字段为 time.Duration 类型，表示等待连接的总时长。

3.12.7.DBStats.MaxIdleClosed

  • 功能

    因超过空闲上限而被关闭的连接数

  • 函数

    MaxIdleClosed int64

  • 参数：无。

  • 返回值

    该字段为 int64 类型，表示因超过空闲上限而被关闭的连接数。

3.12.8.DBStats.MaxLifetimeClosed

  • 功能

    因超过存活时长而被关闭的连接数

  • 函数

    MaxLifetimeClosed int64

  • 参数：无。

  • 返回值

    该字段为 int64 类型，表示因超过存活时长而被关闭的连接数。

3.13.其它类型·事务隔离级别

3.13.1.IsolationLevel.LevelDefault

  • 功能

    使用数据库默认隔离级别

  • 函数

    LevelDefault IsolationLevel = iota

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示使用数据库默认隔离级别。

3.13.2.IsolationLevel.LevelReadUncommitted

  • 功能

    读未提交

  • 函数

    LevelReadUncommitted

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示读未提交隔离级别。

3.13.3.IsolationLevel.LevelReadCommitted

  • 功能

    读已提交

  • 函数

    LevelReadCommitted

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示读已提交隔离级别。

3.13.4.IsolationLevel.LevelWriteCommitted

  • 功能

    写已提交

  • 函数

    LevelWriteCommitted

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示写已提交隔离级别。

3.13.5.IsolationLevel.LevelRepeatableRead

  • 功能

    可重复读

  • 函数

    LevelRepeatableRead

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示可重复读隔离级别。

3.13.6.IsolationLevel.LevelSnapshot

  • 功能

    快照隔离

  • 函数

    LevelSnapshot

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示快照隔离级别。

3.13.7.IsolationLevel.LevelSerializable

  • 功能

    可串行化

  • 函数

    LevelSerializable

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示可串行化隔离级别。

3.13.8.IsolationLevel.LevelLinearizable

  • 功能

    线性一致

  • 函数

    LevelLinearizable

  • 参数：无。

  • 返回值

    该常量为 IsolationLevel 类型，表示线性一致隔离级别。

3.14.其它类型·事务选项

3.14.1.TxOptions.Isolation

  • 功能

    事务隔离级别

  • 函数

    Isolation IsolationLevel

  • 参数：无。

  • 返回值

    该字段为 IsolationLevel 类型，表示事务隔离级别。

3.14.2.TxOptions.ReadOnly

  • 功能

    是否开启只读事务

  • 函数

    ReadOnly bool

  • 参数：无。

  • 返回值

    该字段为 bool 类型，表示是否开启只读事务。

3.15.其它类型·命名参数

3.15.1.NamedArg.Name

  • 功能

    参数名

  • 函数

    Name string

  • 参数：无。

  • 返回值

    该字段为 string 类型，表示参数名。

3.15.2.NamedArg.Value

  • 功能

    参数值

  • 函数

    Value any

  • 参数：无。

  • 返回值

    该字段为 any 类型，表示参数值。

3.16.其它类型·可空类型

3.16.1.Null[T].V

  • 功能

    实际值（泛型可空类型，Go 1.22+）

  • 函数

    V T

  • 参数：无。

  • 返回值

    该字段为泛型 T 类型，表示可空类型的实际值。

3.16.2.Null[T].Valid

  • 功能

    值是否有效（非 NULL）

  • 函数

    Valid bool

  • 参数：无。

  • 返回值

    该字段为 bool 类型，表示值是否有效（非 NULL）。

3.16.3.NullString.String

  • 功能

    字符串值

  • 函数

    String string

  • 参数：无。

  • 返回值

    该字段为 string 类型，表示字符串值。

3.16.4.NullString.Valid

  • 功能

    值是否有效（非 NULL）

  • 函数

    Valid bool

  • 参数：无。

  • 返回值

    该字段为 bool 类型，表示值是否有效（非 NULL）。

3.16.5.NullBool.Bool / Valid

  • 功能

    布尔值与有效性标记

  • 函数

    Bool bool / Valid bool

  • 参数：无。

  • 返回值

    该字段组为 bool 类型，表示布尔值与有效性标记。

3.16.6.NullByte.Byte / Valid

  • 功能

    字节值与有效性标记

  • 函数

    Byte byte / Valid bool

  • 参数：无。

  • 返回值

    该字段组为 byte 类型，表示字节值与有效性标记。

3.16.7.NullFloat64.Float64 / Valid

  • 功能

    浮点值与有效性标记

  • 函数

    Float64 float64 / Valid bool

  • 参数：无。

  • 返回值

    该字段组为 float64 类型，表示浮点值与有效性标记。

3.16.8.NullInt16.Int16 / Valid

  • 功能

    16 位整数值与有效性标记

  • 函数

    Int16 int16 / Valid bool

  • 参数：无。

  • 返回值

    该字段组为 int16 类型，表示 16 位整数值与有效性标记。

3.16.9.NullInt32.Int32 / Valid

  • 功能

    32 位整数值与有效性标记

  • 函数

    Int32 int32 / Valid bool

  • 参数：无。

  • 返回值

    该字段组为 int32 类型，表示 32 位整数值与有效性标记。

3.16.10.NullInt64.Int64 / Valid

  • 功能

    64 位整数值与有效性标记

  • 函数

    Int64 int64 / Valid bool

  • 参数：无。

  • 返回值

    该字段组为 int64 类型，表示 64 位整数值与有效性标记。

3.16.11.NullTime.Time / Valid

  • 功能

    时间值与有效性标记

  • 函数

    Time time.Time / Valid bool

  • 参数：无。

  • 返回值

    该字段组为 time.Time 类型，表示时间值与有效性标记。

3.16.12.Out

  • 功能

    标记输出参数（driver.Out 别名，空结构体）

  • 函数

    type Out struct{}

  • 参数：无。

  • 返回值

    该类型为输出参数标记（driver.Out 别名，空结构体）。

3.16.13.RawBytes

  • 功能

    原始字节切片别名，用于直接取回未解析的列值

  • 函数

    type RawBytes []byte

  • 参数：无。

  • 返回值

    该类型为原始字节切片别名，用于直接取回未解析的列值。

3.17.UXDB 驱动扩展·连接器

3.17.1.uxsql.Connector

  • 功能

    可复用的连接器，配合 sql.OpenDB 使用

  • 函数

    type Connector struct{}

  • 参数：无。

  • 返回值

    该类型为可复用的连接器结构体，用于配合 sql.OpenDB 使用。

3.17.2.uxsql.NewConnector

  • 功能

    按 DSN 创建连接器

  • 函数

    func NewConnector(dsn string) (*Connector, error)

  • 参数

    表 NewConnector 参数说明

    名称描述
    dsn（输入）数据源名称（连接串）。

  • 返回值

    返回连接器 *Connector 和错误信息 error。

3.18.UXDB 驱动扩展·数组/复合类型

3.18.1.uxsql.Array

  • 功能

    把 Go 切片声明为 UXDB 数组参数

  • 函数

    func Array(a interface{}) interface{}

  • 参数

    表 Array 参数说明

    名称描述
    a（输入）Go 切片，用于声明为 UXDB 数组参数。

  • 返回值

    返回声明为 UXDB 数组参数的值。

3.18.2.uxsql.ArrayDelimiter

  • 功能

    自定义数组分隔符

  • 函数

    type ArrayDelimiter interface { ArrayDelimiter() string }

  • 参数：无。

  • 返回值

    该类型为自定义数组分隔符接口。

3.18.3.uxsql.BoolArray

  • 功能

    布尔数组

  • 函数

    type BoolArray []bool

  • 参数：无。

  • 返回值

    该类型为布尔数组，用于声明 UXDB 数组参数。

3.18.4.uxsql.ByteaArray

  • 功能

    字节数组（bytea[]）

  • 函数

    type ByteaArray [][]byte

  • 参数：无。

  • 返回值

    该类型为字节数组（bytea[]），用于声明 UXDB 数组参数。

3.18.5.uxsql.Float64Array

  • 功能

    双精度浮点数组

  • 函数

    type Float64Array []float64

  • 参数：无。

  • 返回值

    该类型为双精度浮点数组，用于声明 UXDB 数组参数。

3.18.6.uxsql.Int64Array

  • 功能

    64 位整型数组

  • 函数

    type Int64Array []int64

  • 参数：无。

  • 返回值

    该类型为 64 位整型数组，用于声明 UXDB 数组参数。

3.18.7.uxsql.StringArray

  • 功能

    字符串数组

  • 函数

    type StringArray []string

  • 参数：无。

  • 返回值

    该类型为字符串数组，用于声明 UXDB 数组参数。

3.18.8.uxsql.GenericArray

  • 功能

    通用数组包装（元素实现 ArrayDelimiter）

  • 函数

    type GenericArray struct { A interface{} }

  • 参数：无。

  • 返回值

    该类型为通用数组包装，元素需实现 ArrayDelimiter 接口。

3.18.9.hstore.Hstore

  • 功能

    hstore 键值类型映射

  • 函数

    type Hstore map[string]NullString

  • 参数：无。

  • 返回值

    该类型为 hstore 键值类型映射。

3.19.UXDB 驱动扩展·COPY 批量

3.19.1.uxsql.CopyIn

  • 功能

    生成 COPY ... FROM STDIN 语句文本

  • 函数

    func CopyIn(table string, columns ...string) string

  • 参数

    表 CopyIn 参数说明

    名称描述
    table（输入）目标表名。
    columns（输入）目标列名，可变参数。

  • 返回值

    返回 COPY ... FROM STDIN 语句文本。

3.19.2.uxsql.CopyInSchema

  • 功能

    生成带 schema 限定的 COPY ... FROM STDIN 语句文本

  • 函数

    func CopyInSchema(schema, table string, columns ...string) string

  • 参数

    表 CopyInSchema 参数说明

    名称描述
    schema（输入）模式名。
    table（输入）目标表名。
    columns（输入）目标列名，可变参数。

  • 返回值

    返回带 schema 限定的 COPY ... FROM STDIN 语句文本。

3.20.UXDB 驱动扩展·异步通知

3.20.1.uxsql.Listener

  • 功能

    LISTEN/NOTIFY 异步通知监听器（自动重连）

  • 函数

    type Listener struct{}

  • 参数：无。

  • 返回值

    该类型为 LISTEN/NOTIFY 异步通知监听器（自动重连）。

3.20.2.uxsql.NewListener

  • 功能

    创建通知监听器

  • 函数

    func NewListener(name string, minReconnectInterval time.Duration, maxReconnectInterval time.Duration, eventCallback EventCallbackType) *Listener

  • 参数

    表 NewListener 参数说明

    名称描述
    name（输入）监听的通道名。
    minReconnectInterval（输入）最小重连间隔。
    maxReconnectInterval（输入）最大重连间隔。
    eventCallback（输入）监听器事件回调函数。

  • 返回值

    返回通知监听器 *Listener。

3.20.3.uxsql.NewDialListener

  • 功能

    使用自定义 Dialer 创建通知监听器

  • 函数

    func NewDialListener(d Dialer, name string, minReconnectInterval, maxReconnectInterval time.Duration, eventCallback EventCallbackType) *Listener

  • 参数

    表 NewDialListener 参数说明

    名称描述
    d（输入）自定义 Dialer。
    name（输入）监听的通道名。
    minReconnectInterval（输入）最小重连间隔。
    maxReconnectInterval（输入）最大重连间隔。
    eventCallback（输入）监听器事件回调函数。

  • 返回值

    返回通知监听器 *Listener。

3.20.4.uxsql.ListenerConn

  • 功能

    单个通知通道的连接封装

  • 函数

    type ListenerConn struct{}

  • 参数：无。

  • 返回值

    该类型为单个通知通道的连接封装。

3.20.5.uxsql.NewListenerConn

  • 功能

    建立通知通道连接

  • 函数

    func NewListenerConn(name string, notificationChan chan<- *Notification) (*ListenerConn, error)

  • 参数

    表 NewListenerConn 参数说明

    名称描述
    name（输入）监听的通道名。
    notificationChan（输出）接收通知的通道。

  • 返回值

    返回通知通道连接 *ListenerConn 和错误信息 error。

3.20.6.uxsql.Notification

  • 功能

    一条异步通知（通道名、后端 PID、负载）

  • 函数

    type Notification struct { Channel, Extra string; BePid int32 }

  • 参数：无。

  • 返回值

    该类型为一条异步通知，含通道名、后端 PID 与负载。

3.20.7.uxsql.ListenerEventType

  • 功能

    监听器事件类型（连接/断开/出错）

  • 函数

    type ListenerEventType int

  • 参数：无。

  • 返回值

    该类型为监听器事件类型（连接/断开/出错）。

3.20.8.uxsql.EventCallbackType

  • 功能

    监听器事件回调函数

  • 函数

    type EventCallbackType func(event ListenerEventType, err error)

  • 参数：无。

  • 返回值

    该类型为监听器事件回调函数。

3.20.9.uxsql.ErrChannelAlreadyOpen

  • 功能

    通道已打开的错误

  • 函数

    var ErrChannelAlreadyOpen = errors.New("uxsql: channel is already open")

  • 参数：无。

  • 返回值

    该变量为 error 错误对象，表示通道已打开。

3.20.10.uxsql.ErrChannelNotOpen

  • 功能

    通道未打开的错误

  • 函数

    var ErrChannelNotOpen = errors.New("uxsql: channel is not open")

  • 参数：无。

  • 返回值

    该变量为 error 错误对象，表示通道未打开。

3.21.UXDB 驱动扩展·SQL 组装与转义

3.21.1.uxsql.QuoteIdentifier

  • 功能

    按 UXDB 规则引用标识符

  • 函数

    func QuoteIdentifier(name string) string

  • 参数

    表 QuoteIdentifier 参数说明

    名称描述
    name（输入）需要引用的标识符。

  • 返回值

    返回按 UXDB 规则引用后的标识符字符串。

3.21.2.uxsql.QuoteLiteral

  • 功能

    按 UXDB 规则引用字面量

  • 函数

    func QuoteLiteral(literal string) string

  • 参数

    表 QuoteLiteral 参数说明

    名称描述
    literal（输入）需要引用的字面量。

  • 返回值

    返回按 UXDB 规则引用后的字面量字符串。

3.21.3.uxsql.ParseURL

  • 功能

    把 URL 形式连接串转换为键值对连接串

  • 函数

    func ParseURL(url string) (string, error)

  • 参数

    表 ParseURL 参数说明

    名称描述
    url（输入）URL 形式连接串。

  • 返回值

    返回键值对连接串和错误信息 error。

3.21.4.uxsql.FormatTimestamp

  • 功能

    把 time.Time 格式化为 UXDB 时间戳字面量

  • 函数

    func FormatTimestamp(t time.Time) []byte

  • 参数

    表 FormatTimestamp 参数说明

    名称描述
    t（输入）需要格式化的时间。

  • 返回值

    返回格式化为 UXDB 时间戳字面量的字节切片。

3.21.5.uxsql.ParseTimestamp

  • 功能

    解析 UXDB 时间戳为 time.Time

  • 函数

    func ParseTimestamp(currentLocation *time.Location, str string) (time.Time, error)

  • 参数

    表 ParseTimestamp 参数说明

    名称描述
    currentLocation（输入）解析时使用的时区。
    str（输入）UXDB 时间戳字符串。

  • 返回值

    返回解析后的时间 time.Time 和错误信息 error。

3.21.6.uxsql.EnableInfinityTs

  • 功能

    开关 ±infinity 时间戳的映射

  • 函数

    func EnableInfinityTs(negative time.Time, positive time.Time)

  • 参数

    表 EnableInfinityTs 参数说明

    名称描述
    negative（输入）-infinity 时间戳映射的时间值。
    positive（输入）+infinity 时间戳映射的时间值。

  • 返回值

    无返回值。

3.21.7.uxsql.NullTime

  • 功能

    可空时间类型

  • 函数

    type NullTime struct { Time time.Time; Valid bool }

  • 参数：无。

  • 返回值

    该类型为可空时间类型。

3.22.UXDB 驱动扩展·错误处理

3.22.1.uxsql.Error

  • 功能

    UXDB 服务端返回的错误，含 SQLSTATE 与诊断字段

  • 函数

    type Error struct{}

  • 参数：无。

  • 返回值

    该类型为 UXDB 服务端返回的错误，含 SQLSTATE 与诊断字段。

3.22.2.uxsql.ErrorCode

  • 功能

    SQLSTATE 错误码（5 位）

  • 函数

    type ErrorCode string

  • 参数：无。

  • 返回值

    该类型为 SQLSTATE 错误码（5 位）。

3.22.3.uxsql.ErrorClass

  • 功能

    SQLSTATE 错误类别（前 2 位）

  • 函数

    type ErrorClass string

  • 参数：无。

  • 返回值

    该类型为 SQLSTATE 错误类别（前 2 位）。

3.22.4.uxsql.UXError

  • 功能

    可提取错误码的接口

  • 函数

    type UXError interface { Error() string; UXCode() ErrorCode }

  • 参数：无。

  • 返回值

    该类型为可提取错误码的接口。

Copyright © 2026 UXSINO版权所有