sqlmer

package module
v1.8.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 11, 2026 License: MIT Imports: 11 Imported by: 0

README

sqlmer

License Go Go Report Card Go Reference

功能简介

一个面向原生 SQL 的数据库操作库，在保持 SQL 语句灵活性的同时，通过统一的接口设计、便捷的参数处理和轻量级的 ORM 映射能力，让数据库操作更加优雅高效。目前支持 MySQL / SQLite / SQL Server 。

核心特性
  • 面向原生 SQL：核心交互以原生 SQL 语句为基础，提供灵活的结果映射能力，让数据库操作更加简单高效；
  • 增强的参数处理：提供了直观的 命名参数 和 索引参数 语法，其中 命名参数 支持使用 map/struct 作为参数，并允许参数重写，让 SQL 及参数更易维护和重用；
  • 轻量化 ORM 体验：支持将查询结果灵活映射为 Map 或类型安全的结构体，并提供智能的字段匹配机制，让数据操作更加简单直观；
  • 一致的接口设计：提供了直观统一的数据交互接口，事务和非事务操作保持一致的使用体验；
  • 增强的原生接口：针对原生 API 爱好者，也提供了增强的 sql.Rows/sql.Row，增加了自动检测列类型和数量的能力，可智能地将数据 Scan 到合适的类型，轻松装载到 Map 或 Slice；
  • 强大的事务支持：提供了支持嵌套使用的事务 API，优雅地处理复杂的事务场景；
  • 便捷的 IN 查询：支持直接传递 slice/array 类型参数到 IN 子句，无需手动拼接语句；
  • 灵活的装饰器模式：通过 wrap 包提供的装饰器模式，可以轻松注入慢日志、监控指标、链路追踪等自定义逻辑，让系统监控和诊断更加便捷；
  • 智能的连接管理：根据数据库配置自动初始化连接生命周期（该特性仅支持 MySQL）；

快速上手

让我们通过一系列示例来展示 sqlmer 的强大功能。以下示例将展示如何使用 sqlmer 进行数据库操作，包括基础查询、ORM 映射、事务处理等核心特性。

本小节完整例子：example

获取 sqlmer
go get github.com/bunnier/sqlmer
连接数据库

首先，让我们创建一个数据库连接。sqlmer 提供了统一的接口设计，无论是 MySQL / SQLite / SQL Server，都可以使用相同的 API 进行操作。

var (
	// 这是本库的基础接口，提供了访问数据库的的核心 API 操作。
	dbClient sqlmer.DbClient

	// 这是本库的扩展接口（推荐使用）。
	// DbClientEx 实现了 DbClient 的所有接口，并增加 must 版本 API、ORM 等扩展功能。
	// 后续演示为了简洁，使用了 panic 版本 API，因此主要使用这个接口。
	dbClientEx *sqlmer.DbClientEx
)

func init() {
	// 这里使用 SQLite (sqlite 包)做示范，其它支持的数据库也提供了一致的 API 和相应的参数解析逻辑。
	var err error
	if dbClient, err = sqlite.NewSqliteDbClient(
		"demo.db",
		sqlmer.WithConnTimeout(time.Second*30), // 连接超时。
		sqlmer.WithExecTimeout(time.Second*30), // 读写超时(执行语句时候，如果没有指定超时时间，默认用这个)。
	); err != nil {
		log.Fatal(err)
	}

	dbClientEx = sqlmer.Extend(dbClient)
}
基础查询操作

sqlmer 支持多种参数传递方式，包括命名参数和索引参数，也支持参数的重写覆盖逻辑，让 SQL 语句更易维护和重用。

// 准备演示数据。
func prepare() {
	// 创建/删除 测试表。
	dbClientEx.MustExecute(`
		CREATE TABLE IF NOT EXISTS demo (
			Id INTEGER PRIMARY KEY AUTOINCREMENT,
			Name TEXT NOT NULL,
			Age INTEGER NOT NULL,
			Scores TEXT NOT NULL
		)
	`)

	// 索引方式插入数据，@p1..@pN，分别对应第 1..n 个参数。
	dbClientEx.MustExecute("INSERT INTO demo(Name, Age, Scores) VALUES(@p1, @p2, @p3)", "rui", 1, "SCORES:1,3,5,7")
	dbClientEx.MustExecute("INSERT INTO demo(Name, Age, Scores) VALUES(@p1, @p2, @p3)", "bao", 2, "SCORES:2,4,6,8")
}

// 开始演示基础查询功能了~
func selectionDemo() {
	// 命名参数查询数据，参数采用 map 时：key 为 sql 语句 @ 之后的参数名，value 为值。
	dataMap := dbClientEx.MustGet("SELECT * FROM demo WHERE Name=@Name", map[string]any{"Name": "rui"})
	fmt.Println(dataMap) // Output: map[Age:1 Id:1 Name:rui Scores:SCORES:1,3,5,7]

	// 命名参数查询数据，参数采用 struct 时：字段名为 sql 语句 @ 之后的参数名，字段值为参数值。
	type Params struct {
		Name string
	}
	dataMap = dbClientEx.MustGet("SELECT * FROM demo WHERE Name=@Name", Params{Name: "rui"})
	fmt.Println(dataMap) // Output: map[Age:1 Id:1 Name:rui Scores:SCORES:1,3,5,7]

	// 可提供多个参数，DbClient 会自动进行参数合并，优先取靠后的参数中的同名字段（ struct 和 map 可互相覆盖）。
	dataMap = dbClientEx.MustGet("SELECT * FROM demo WHERE Name=@Name", Params{Name: "rui"}, map[string]any{"Name": "bao"})
	fmt.Println(dataMap) // Output: map[Age:2 Id:2 Name:bao Scores:SCORES:2,4,6,8]

	// 可通过 @p1...@pN 方式，指定参数的位置，参数位置从 1 开始。
	name, _ := dbClientEx.MustScalar("SELECT Name FROM demo WHERE Name=@p1", "rui")
	fmt.Println(name.(string))

	// 可混用 struct / map / 索引参数，DbClient 会自动进行参数合并。
	// 下面这个语句的 3 个参数，DbClient 进行合并后最后的参数列表是： @p1=rui, @Name="bao"
	count, _ := dbClientEx.MustScalar(
		"SELECT COUNT(1) FROM demo WHERE Name=@p1 OR Name=@Name",
		map[string]any{"Name": "other"},
		"rui",
		Params{Name: "bao"},
	)
	fmt.Println(count.(int64)) // Output: 2

	// 如果喜欢标准库风格，这里也提供了增强版本的 sql.Rows，支持 SliceScan、MapScan。
	// 注意：
	//   - 这里用到了 slice/array 的参数展开特性
	//   - 如果传入的 slice/array 长度为 0，会被解析为 NULL ，会导致 in/not in 语句均为 false；
	rows := dbClientEx.MustRows("SELECT Name, datetime('now') FROM demo WHERE Name IN (@p1)", []any{"rui", "bao"})
	for rows.Next() {
		// SliceScan 会自动判断列数及列类型，用 []any 方式返回。
		if dataSlice, err := rows.SliceScan(); err != nil {
			log.Fatal(err)
		} else {
			fmt.Println(dataSlice...)
			// Output:
			// rui 2022-04-09 22:35:33
			// bao 2022-04-09 22:35:33
		}
	}
	// 和标准库一样，Rows 的 Err 和 Close 返回的错误记得要处理哦～
	if err := rows.Err(); err != nil {
		log.Fatal(err)
	}

	if err := rows.Close(); err != nil {
		log.Fatal(err)
	}
}
轻量级 ORM 映射

sqlmer 提供了简单而强大的轻量级 ORM 映射功能，支持将查询结果直接映射到 Go 结构体。支持驼峰和下划线分割的名称的首字母模糊匹配，让数据操作更加灵活：

// 演示如何使用轻量化 ORM 功能。将数据库的行，映射到 Go struct 。
//
// 由于 Go 语言的限制， struct 的字段必须是大写字母开头的，可能和数据库命名规范不一致。
// 在 ORM 的映射中，可以支持驼峰和下划线分割的名称的首字母模糊匹配，例如：
// struct 字段 GoodName 可以自动匹配到数据库字段 GoodName/goodName/good_name 。
func ormDemo() {
	// 用于表示对应行的数据的类型。
	type Row struct {
		Id     int
		Name   string
		Age    int
		Scores string
	}

	// 轻量化 ORM 的 API 定义在 DbClientEx 里，需要扩展（ Extend ） DbClient 得到。
	clientEx := sqlmer.Extend(dbClient)

	// 获取一行。
	var row Row
	clientEx.MustGetStruct(&row, "SELECT * FROM demo WHERE Id=1")
	fmt.Printf("%v\n", row) // Output: {1 rui 1 1,3,5,7}

	// 获取一个列表。
	//
	// 由于 Golang 不支持方法级的泛型，这里需要通过第一个参数传入一个模板（这里是 Row{} ），指定需要将数据行映射到什么类型；
	// API 返回模板类型的 slice ，以 any 表示，需要再进行类型转换（这里是 []Row ）。
	rows := clientEx.MustListOf(Row{}, "SELECT * FROM demo").([]Row)
	fmt.Println("Rows:")
	for _, v := range rows {
		fmt.Printf("%v\n", v)
	}
	// Output:
	// Rows:
	// {1 rui 1 SCORES:1,3,5,7}
	// {2 bao 2 SCORES:2,4,6,8}

	// 模板可以是 struct 也可以是其指针，指针的写法：
	// clientEx.MustListOf(new(Row), "SELECT * FROM demo").([]*Row)
}

// 演示如何在 ORM 过程中，如果 struct 的目标字段的类型和数据库的类型不能兼容时，如何通过代码定制转换过程。
func ormWithFieldConvert() {
	// 目标类型。
	type Row struct {
		Id     int
		Name   string
		Age    int
		Scores []int
	}

	// 这里利用 Golang 的 struct 内嵌特性，让外层 struct 的同名字段隐藏掉内层的，
	// ORM 赋值过程中， Scores 会赋值到外层，先用兼容的类型（这里是 string ）将数据库的值取出来。
	wrapper := &struct {
		Row
		Scores string
	}{}
	sqlmer.Extend(dbClient).MustGetStruct(wrapper, "SELECT * FROM demo WHERE Id=1")

	// 在已经取到值的基础上，用一段代码，将处理后的值赋值给最终的目标。
	// 这里 Scores 字段的格式是 SCORES: N1,N2,N3,... ，我们的目标格式是将数字部分转换为 []int 。
	row := wrapper.Row
	scores := strings.TrimPrefix(wrapper.Scores, "SCORES:")
	for _, v := range strings.Split(scores, ",") {
		i, _ := strconv.Atoi(v)
		row.Scores = append(row.Scores, i)
	}

	fmt.Printf("%v\n", row) // Output: {1 rui 1 [1 3 5 7]}
}
事务处理

sqlmer 提供了强大的事务支持，包括嵌套事务，让复杂的事务场景处理变得简单：

// 演示如何使用数据库事务。
func transactionDemo() {
	rowNum, _ := dbClientEx.MustScalar("SELECT count(1) FROM demo")
	fmt.Println(rowNum) // Output: 2

	// CreateTransaction 返回一个 TransactionKeeper，提供了 DbClient 一致的 API。
	// CreateTransactionEx 返回一个 TransactionKeeperEx ，提供了 DbClientEx 一致的 API。
	trans := dbClientEx.MustCreateTransactionEx()

	// 如果 TransactionKeeper.Commit/MustCommit 没有被调用，则 Close 操作会回滚事务；
	// 若事务已提交，则 Close 操作仅关闭连接。
	defer trans.MustClose()

	trans.MustExecute("DELETE FROM demo WHERE Id=1")

	// 支持使用嵌套事务。
	func() {
		embeddedTrans := trans.MustCreateTransactionEx()
		defer embeddedTrans.MustClose() // 注意：嵌套事务也需要 Close 。

		embeddedTrans.MustExecute("DELETE FROM demo WHERE Id=2")
		embeddedTrans.MustCommit()
	}()

	// 提交外层的事务。
	trans.MustCommit()

	rowNum, _ = dbClientEx.MustScalar("SELECT count(1) FROM demo")
	fmt.Println(rowNum) // Output: 0
}
超时控制

所有数据库操作都支持通过 Context 设置超时，提供更好的系统稳定性：

// 演示如何设置超时时间。 DbClient 中的方法，都有一个 Context 版，支持传入 Context 以设置超时。
// 如 Execute 对应 ExecuteContext 。
func timeoutDemo() {
	ctx, cancelFunc := context.WithTimeout(context.Background(), time.Millisecond*10)
	defer cancelFunc()
	// 使用递归查询模拟耗时操作 (SQLite 无法使用 sleep)。
	if _, err := dbClient.ExecuteContext(ctx, "WITH RECURSIVE r(i) AS (VALUES(0) UNION ALL SELECT i+1 FROM r WHERE i < 1000000) SELECT count(*) FROM r"); err != nil {
		fmt.Println("timeout: " + err.Error()) // 预期内的超时~
	}
}
慢日志、监控指标、链路追踪

wrap 子包提供了装饰器模式的 DbClient ，可以简单的注入你的慢日志、监控指标、链路追踪等逻辑，下面演示如何注入慢日志。

// 演示如何通过 wrap 包提供的装饰器注入慢日志。
func decoratedDemo() {
	// 通过 wrap 包提供的扩展注入慢日志逻辑。
	dbClient := wrap.Extend(dbClient, func(sql string, args []any) func(error) {
		// 函数会立刻执行。
		startTime := time.Now()

		// 返回的函数会在语句执行后执行。
		return func(err error) {
			duration := time.Since(startTime)
			if duration <= 100*time.Microsecond {
				return
			}

			fmt.Printf("[SlowSql]Sql=%s, Duration=%d(ms), Err=%v", sql, duration/time.Millisecond, err)
		}
	})

	// 因为还是 DbClient 接口，还可以继续扩展为 DbClientEx。
	clientEx := sqlmer.Extend(dbClient)

	// 使用递归查询模拟耗时操作 (SQLite 无法使用 sleep)。
	clientEx.Execute("WITH RECURSIVE r(i) AS (VALUES(0) UNION ALL SELECT i+1 FROM r WHERE i < 500000) SELECT count(*) FROM r") // Output: [SlowSql]Sql=..., Duration=...(ms), Err=<nil>
}

类型映射

nullable 的列，如果值为 NULL，均以 nil 返回。

MySql
DB datatype Go datatype
varchar / char / text string
tiny int / small int / int / unsigned int / bigint int64
float / double float64
decimal string
date / datetime / timestamp time.Time
bit []byte
SQLite
DB datatype Go datatype
text / varchar / char / clob string
integer / int / tiny int / ... int64
real / double / float float64
time / date / datetime time.Time
blob []byte
SQL Server
DB datatype Go datatype
nvarchar / nchar / varchar / char / text string
small int / tiny int / int / bigint int64
float / real float64
small money / money / decimal string
date / datetime / datetime2 / time time.Time
binary / varbinary []byte
bit bool

测试用例

测试用例 Schema：

  1. 默认的数据库连接字符串定义在 internal/testenv/conf.go 里，默认使用本机的测试库。当需要自定义测试库连接字符串时，可在项目的根（和当前 README 同级）下新建 .db.json，当此文件存在时，会自动加载此文件。文件格式为：

     {
 	"mysql": "testuser:testuser@tcp(127.0.0.1:3306)/test",
 	"sqlserver": "server=127.0.0.1; database=test; user id=testuser;password=testuser;",
 	"sqlite": "test.db"
 }

  2. 如果第 1 步配置的连接字符串有 DDL 权限，可通过调用 go run ./internal/testcmd/main.go -a PREPARE 来同时准备 MySQL / SQL Server 环境，如果没有 DDL 权限可自行直接执行 internal/testenv/*_prepare.sql 准备环境；

  3. 如果第 1 步配置的连接字符串有 DDL 权限，测试结束后可以通过 go run ./internal/testcmd/main.go -a CLEAN 销毁测试表，如果没有 DDL 权限可自行直接执行 internal/testenv/*_clean.sql 销毁测试表。

另外，如果你和我一样使用 VSCode 作为开发工具，可直接使用 .vscode 中编写好的 Task 来准备环境。

其他语言的版本

.net 版： cmstar/Data

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrTran 是数据库执行事务操作遇到的错误。
	ErrTran = errors.New("dbTrans")

	// ErrConnect 是 DbClient 获取数据库连接时遇到的错误。
	ErrConnect = errors.New("dbConnect")

	// ErrGetEffectedRows 当数据库不支持获取影响行数时候，会返回改类型的错误。
	ErrGetEffectedRows = errors.New("dbClient: the db driver do not support getting effected rows")

	// ErrSqlParamParse 解析 SQL 语句中的参数遇到错误时候，会返回该类型错误。
	ErrParseParamFailed = errors.New("dbClient: failed to parse named params")

	// ErrExpectedSizeWrong 当执行语句时候，没有影响到预期行数，返回该类型错误。
	ErrExpectedSizeWrong = errors.New("dbClient: effected rows was wrong")

	// ErrExecutingSql 当执行 SQL 语句执行时遇到错误，返回该类型错误。
	ErrExecutingSql = errors.New("dbClient: failed to execute sql")
)
View Source 
var MaxLengthErrorValue = 64 * 1024

MaxLengthErrorValue 用于限制错误输出中参数的长度，超过该大小将会进行截断。 NOTE: 可自行调整该值。

Functions

This section is empty.

Types

type AbstractDbClient added in v1.2.0 

type AbstractDbClient struct {
	Db   *sqlen.DbEnhance     // 内部依赖的连接池。
	Exer sqlen.EnhancedDbExer // 获取方法实际使用的执行对象。
	// contains filtered or unexported fields
}

AbstractDbClient 是一个 DbClient 的抽象实现。

func NewAbstractDbClient added in v1.3.11 

func NewAbstractDbClient(config *DbClientConfig) (*AbstractDbClient, error)

NewAbstractDbClient 用于获取一个 internalDbClient 对象。

func (*AbstractDbClient) CreateTransaction added in v1.2.0 

func (client *AbstractDbClient) CreateTransaction() (TransactionKeeper, error)

CreateTransaction 用于开始一个事务。 returns: 

@tran 返回一个实现了 TransactionKeeper（内嵌 DbClient 接口） 接口的对象，在上面执行的语句会在同一个事务中执行。
@err 创建事务时遇到的错误。

func (*AbstractDbClient) Dsn added in v1.3.11 

func (client *AbstractDbClient) Dsn() string

Dsn 用于获取当前实例所使用的数据库连接字符串。

func (*AbstractDbClient) Execute added in v1.2.0 

func (client *AbstractDbClient) Execute(sqlText string, args ...any) (int64, error)

Execute 用于执行非查询SQL语句，并返回所影响的行数。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@effectedRows 语句影响的行数。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。

func (*AbstractDbClient) ExecuteContext added in v1.2.0 

func (client *AbstractDbClient) ExecuteContext(ctx context.Context, sqlText string, args ...any) (int64, error)

ExecuteContext 用于执行非查询 sql 语句，并返回所影响的行数。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@effectedRows 语句影响的行数。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) Exists added in v1.2.0 

func (client *AbstractDbClient) Exists(sqlText string, args ...any) (bool, error)

Exists 用于判断给定的查询的结果是否至少包含 1 行。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@ok 结果至少包含一行。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) ExistsContext added in v1.2.0 

func (client *AbstractDbClient) ExistsContext(ctx context.Context, sqlText string, args ...any) (bool, error)

ExistsContext 用于判断给定的查询的结果是否至少包含 1 行。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@ok 结果至少包含一行。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) Get added in v1.2.0 

func (client *AbstractDbClient) Get(sqlText string, args ...any) (map[string]any, error)

Get 用于获取查询结果的第一行记录。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRow 目标查询第一行的结果。
@err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值是否为 nil。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) GetConnTimeout added in v1.7.0 

func (client *AbstractDbClient) GetConnTimeout() time.Duration

GetConnTimeout 用于获取当前 DbClient 实例的连接超时时间。

func (*AbstractDbClient) GetContext added in v1.2.0 

func (client *AbstractDbClient) GetContext(ctx context.Context, sqlText string, args ...any) (map[string]any, error)

GetContext 用于获取查询结果的第一行记录。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRow 目标查询第一行的结果。
@err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值是否为 nil。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) GetExecTimeout added in v1.7.0 

func (client *AbstractDbClient) GetExecTimeout() time.Duration

GetExecTimeout 用于获取当前 DbClient 实例的执行超时时间。

func (*AbstractDbClient) Row added in v1.2.0 

func (client *AbstractDbClient) Row(sqlText string, args ...any) (*sqlen.EnhanceRow, error)

Row 用于获取单个查询结果行。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) RowContext added in v1.2.0 

func (client *AbstractDbClient) RowContext(ctx context.Context, sqlText string, args ...any) (*sqlen.EnhanceRow, error)

RowContext 用于获取单个查询结果行。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) Rows added in v1.2.0 

func (client *AbstractDbClient) Rows(sqlText string, args ...any) (*sqlen.EnhanceRows, error)

Rows 用于获取查询结果行的游标对象。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) RowsContext added in v1.2.0 

func (client *AbstractDbClient) RowsContext(ctx context.Context, sqlText string, args ...any) (*sqlen.EnhanceRows, error)

RowsContext 用于获取查询结果行的游标对象。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。
@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) Scalar added in v1.2.0 

func (client *AbstractDbClient) Scalar(sqlText string, args ...any) (any, bool, error)

Scalar 用于获取查询的第一行第一列的值。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@cell 目标查询第一行第一列的值。
@hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。
@err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，而通过第二个返回值区分。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) ScalarContext added in v1.2.0 

func (client *AbstractDbClient) ScalarContext(ctx context.Context, sqlText string, args ...any) (any, bool, error)

ScalarContext 用于获取查询的第一行第一列的值。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@cell 目标查询第一行第一列的值。
@hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。
@err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，而通过第二个返回值区分。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) SizedExecute added in v1.2.0 

func (client *AbstractDbClient) SizedExecute(expectedSize int64, sqlText string, args ...any) error

SizedExecute 用于执行非查询SQL语句，并断言所影响的行数。 params: 

@expectedSize 预期的影响行数，当
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
  • sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) SizedExecuteContext added in v1.2.0 

func (client *AbstractDbClient) SizedExecuteContext(ctx context.Context, expectedSize int64, sqlText string, args ...any) error

SizedExecuteContext 用于执行非查询SQL语句，并断言所影响的行数。 params: 

@ctx context。
@expectedSize 预期的影响行数，当
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@err 执行语句时遇到的错误。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
  • sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) SliceGet added in v1.2.0 

func (client *AbstractDbClient) SliceGet(sqlText string, args ...any) ([]map[string]any, error)

SliceGet 用于获取查询结果的所有行。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRows 目标查询结果的所有行。
@err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值的 len。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*AbstractDbClient) SliceGetContext added in v1.2.0 

func (client *AbstractDbClient) SliceGetContext(ctx context.Context, sqlText string, args ...any) ([]map[string]any, error)

SliceGetContext 用于获取查询结果得行序列。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRows 目标查询结果的所有行。
@err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值的 len。

可以通过 errors.Is 判断的特殊 err：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

type BindSqlArgsFunc 

type BindSqlArgsFunc func(string, ...any) (string, []any, error)

BindSqlArgsFunc 定义用于预处理 sql 语句与参数的函数。

type DbClient 

type DbClient interface {
	// Dsn 用于获取当前实例所使用的数据库连接字符串。
	Dsn() string

	// GetConnTimeout 用于获取当前 DbClient 实例的获取连接的超时时间。
	GetConnTimeout() time.Duration

	// GetExecTimeout 用于获取当前 DbClient 实例的执行超时时间。
	GetExecTimeout() time.Duration

	// CreateTransaction 用于开始一个事务。
	// returns:
	//  @tran 返回一个实现了 TransactionKeeper（内嵌 DbClient 接口） 接口的对象，在上面执行的语句会在同一个事务中执行。
	//  @err 创建事务时遇到的错误。
	CreateTransaction() (tran TransactionKeeper, err error)

	// Execute 用于执行非查询SQL语句，并返回所影响的行数。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @effectedRows 语句影响的行数。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	Execute(sqlText string, args ...any) (rowsEffected int64, err error)

	// ExecuteContext 用于执行非查询 sql 语句，并返回所影响的行数。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @effectedRows 语句影响的行数。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	ExecuteContext(ctx context.Context, sqlText string, args ...any) (rowsEffected int64, err error)

	// SizedExecute 用于执行非查询SQL语句，并断言所影响的行数。
	// params:
	//  @expectedSize 预期的影响行数，当
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	SizedExecute(expectedSize int64, sqlText string, args ...any) error

	// SizedExecuteContext 用于执行非查询SQL语句，并断言所影响的行数。
	// params:
	//  @ctx context。
	//  @expectedSize 预期的影响行数，当
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	SizedExecuteContext(ctx context.Context, expectedSize int64, sqlText string, args ...any) error

	// Exists 用于判断给定的查询的结果是否至少包含 1 行。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @ok 结果至少包含一行。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	Exists(sqlText string, args ...any) (ok bool, err error)

	// ExistsContext 用于判断给定的查询的结果是否至少包含 1 行。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @ok 结果至少包含一行。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	ExistsContext(ctx context.Context, sqlText string, args ...any) (ok bool, err error)

	// Scalar 用于获取查询的第一行第一列的值。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @cell 目标查询第一行第一列的值。
	//  @hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。
	//  @err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，而通过第二个返回值区分。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	Scalar(sqlText string, args ...any) (cell any, hit bool, err error)

	// ScalarContext 用于获取查询的第一行第一列的值。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @cell 目标查询第一行第一列的值。
	//  @hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。
	//  @err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，而通过第二个返回值区分。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	ScalarContext(ctx context.Context, sqlText string, args ...any) (cell any, hit bool, err error)

	// Get 用于获取查询结果的第一行记录。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRow 目标查询第一行的结果。
	//  @err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值是否为 nil。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	Get(sqlText string, args ...any) (mapRow map[string]any, err error)

	// GetContext 用于获取查询结果的第一行记录。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRow 目标查询第一行的结果。
	//  @err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值是否为 nil。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	GetContext(ctx context.Context, sqlText string, args ...any) (mapRow map[string]any, err error)

	// SliceGet 用于获取查询结果的所有行。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRows 目标查询结果的所有行。
	//  @err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值的 len。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	SliceGet(sqlText string, args ...any) (mapRows []map[string]any, err error)

	// SliceGetContext 用于获取查询结果得行序列。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRows 目标查询结果的所有行。
	//  @err 执行语句时遇到的错误。注意，sql.ErrNoRows 不放 error 中返回，要知道是否有数据可直接判断第一个返回值的 len。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	SliceGetContext(ctx context.Context, sqlText string, args ...any) (mapRows []map[string]any, err error)

	// Row 用于获取单个查询结果行。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	Row(sqlText string, args ...any) (row *sqlen.EnhanceRow, err error)

	// RowContext 用于获取单个查询结果行。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	RowContext(context context.Context, sqlText string, args ...any) (row *sqlen.EnhanceRow, err error)

	// Rows 用于获取查询结果行的游标对象。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	Rows(sqlText string, args ...any) (rows *sqlen.EnhanceRows, err error)

	// RowsContext 用于获取查询结果行的游标对象。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。
	//  @err 执行语句时遇到的错误。
	// 可以通过 errors.Is 判断的特殊 err：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	RowsContext(context context.Context, sqlText string, args ...any) (rows *sqlen.EnhanceRows, err error)
}

ErrorDbClient 为 error 版本 API。

type DbClientConfig 

type DbClientConfig struct {
	Driver string  // 数据库驱动名称。
	Dsn    string  // 连接字符串。
	Db     *sql.DB // 数据库对象。
	// contains filtered or unexported fields
}

func NewDbClientConfig 

func NewDbClientConfig(options ...DbClientOption) (*DbClientConfig, error)

NewDbClientConfig 创建一个数据库连接配置。

type DbClientEx added in v1.5.0 

type DbClientEx struct {
	DbClient           // 原始的 DbClient 实例。
	Conv     conv.Conv // 为当前实例提供类型转换的 conv.Conv 实例。
}

DbClientEx 加强 DbClient。

  • 提供 Must 版本的 API；
  • 提供强类型的转化方法；

func Extend added in v1.5.0 

func Extend(raw DbClient) *DbClientEx

Extend 加强 DbClient ，提供强类型的转化方法。

func (*DbClientEx) CreateTransactionEx added in v1.5.3 

func (c *DbClientEx) CreateTransactionEx() (*TransactionKeeperEx, error)

CreateTransactionEx 基于 DbClient.CreateTransaction 创建一个 TransactionKeeperEx 实例。

func (*DbClientEx) GetStruct added in v1.5.0 

func (c *DbClientEx) GetStruct(ptr any, query string, args ...any) (ok bool, err error)

GetStruct 获取一行的查询结果，转化并填充到 ptr 。 ptr 必须是 struct 类型的指针。 若查询没有命中行，返回 ok=false ， ptr 不会被赋值。

func (*DbClientEx) ListOf added in v1.5.0 

func (c *DbClientEx) ListOf(elemExample any, query string, args ...any) (any, error)

ListOf 将查询结果的每一行转换到指定类型。返回转换后的元素的列表，需给定列表中的元素的类型。若查询没有命中行，返回空集。

注意，给定的 elemTyp 是元素的类型，返回的则是该元素的 slice ： 

type Info struct { /* fields */ }
list, err := ListOf(new(Info), query)
if err != nil {
  return err
}
infos := list.([]*Info)

func (*DbClientEx) ListType added in v1.5.0 

func (c *DbClientEx) ListType(elemTyp reflect.Type, query string, args ...any) (any, error)

ListOf 将查询结果的每一行转换到指定类型。返回转换后的元素的列表，需给定列表中的元素的类型。若查询没有命中行，返回空集。

注意，给定的 elemTyp 是元素的类型，返回的则是该元素的 slice ： 

list, err := ListType(reflect.TypeOf(0), query)
if err != nil {
  return err
}
infos := list.([]int)

func (*DbClientEx) MustCreateTransaction added in v1.5.2 

func (client *DbClientEx) MustCreateTransaction() *TransactionKeeperEx

MustCreateTransactionEx（和 MustCreateTransaction 一致） 用于开始一个事务。 returns: 

@tran 返回一个TransactionKeeperEx 实例（实现了 TransactionKeeper、DbClient 接口） 接口的对象，在上面执行的语句会在同一个事务中执行。

func (*DbClientEx) MustCreateTransactionEx added in v1.5.3 

func (c *DbClientEx) MustCreateTransactionEx() *TransactionKeeperEx

MustCreateTransactionEx（和 MustCreateTransaction 一致） 用于开始一个事务。 returns: 

@tran 返回一个TransactionKeeperEx 实例（实现了 TransactionKeeper、DbClient 接口） 接口的对象，在上面执行的语句会在同一个事务中执行。

func (*DbClientEx) MustExecute added in v1.7.0 

func (client *DbClientEx) MustExecute(sqlText string, args ...any) int64

MustExecute 用于执行非查询 sql 语句，并返回所影响的行数。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@effectedRows 语句影响的行数。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustExecuteContext added in v1.7.0 

func (client *DbClientEx) MustExecuteContext(ctx context.Context, sqlText string, args ...any) int64

MustExecuteContext 用于执行非查询SQL语句，并返回所影响的行数。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@effectedRows 语句影响的行数。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustExists added in v1.7.0 

func (client *DbClientEx) MustExists(sqlText string, args ...any) bool

MustExists 用于判断给定的查询的结果是否至少包含 1 行。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@ok 结果至少包含一行。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustExistsContext added in v1.7.0 

func (client *DbClientEx) MustExistsContext(ctx context.Context, sqlText string, args ...any) bool

MustExistsContext 用于判断给定的查询的结果是否至少包含 1 行。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@ok 结果至少包含一行。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustGet added in v1.7.0 

func (client *DbClientEx) MustGet(sqlText string, args ...any) map[string]any

MustGet 用于获取查询结果的第一行记录。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRow 目标查询第一行的结果。

可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以判断返回值是否为 nil：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustGetContext added in v1.7.0 

func (client *DbClientEx) MustGetContext(ctx context.Context, sqlText string, args ...any) map[string]any

MustGetContext 用于获取查询结果的第一行记录。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRow 目标查询第一行的结果。

可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以判断返回值是否为 nil：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustGetStruct added in v1.5.0 

func (c *DbClientEx) MustGetStruct(ptr any, query string, args ...any) (ok bool)

MustGetStruct 类似 GetStruct ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustListOf added in v1.5.0 

func (c *DbClientEx) MustListOf(elemExample any, query string, args ...any) any

MustListOf 类似 ListOf ，但出现错误时不返回 error ，而是 panic 。 

type Info struct { /* fields */ }
list := MustListOf(new(Info), query).([]*Info)

func (*DbClientEx) MustListType added in v1.5.0 

func (c *DbClientEx) MustListType(elemTyp reflect.Type, query string, args ...any) any

MustListType 类似 ListType ，但出现错误时不返回 error ，而是 panic 。

注意，给定的 elemTyp 是元素的类型，返回的则是该元素的 slice ： 

list := MustListType(reflect.TypeOf(0), query).([]int)

func (*DbClientEx) MustRow added in v1.7.0 

func (client *DbClientEx) MustRow(sqlText string, args ...any) *sqlen.EnhanceRow

MustRow 用于获取单个查询结果行。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。

可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，要知道是否有数据可直接判断返回值的 len。

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustRowContext added in v1.7.0 

func (client *DbClientEx) MustRowContext(ctx context.Context, sqlText string, args ...any) *sqlen.EnhanceRow

MustRowContext 用于获取单个查询结果行。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustRows added in v1.7.0 

func (client *DbClientEx) MustRows(sqlText string, args ...any) *sqlen.EnhanceRows

MustRows 用于获取查询结果行的游标对象。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustRowsContext added in v1.7.0 

func (client *DbClientEx) MustRowsContext(ctx context.Context, sqlText string, args ...any) *sqlen.EnhanceRows

MustRowsContext 用于获取查询结果行的游标对象。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustScalar added in v1.7.0 

func (client *DbClientEx) MustScalar(sqlText string, args ...any) (any, bool)

MustScalar 用于获取查询的第一行第一列的值。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@cell 目标查询第一行第一列的值。
@hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。

可能 panic 出的 error（可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以通过第二个返回值区分：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustScalarBool added in v1.5.0 

func (c *DbClientEx) MustScalarBool(query string, args ...any) (value *bool, ok bool)

MustScalarBool 类似 ScalarBool ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarContext added in v1.7.0 

func (client *DbClientEx) MustScalarContext(ctx context.Context, sqlText string, args ...any) (any, bool)

MustScalarContext 用于获取查询的第一行第一列的值。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@cell 目标查询第一行第一列的值。
@hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。

可能 panic 出的 error（可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以通过第二个返回值区分：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustScalarFloat32 added in v1.5.0 

func (c *DbClientEx) MustScalarFloat32(query string, args ...any) (value *float32, ok bool)

MustScalarFloat32 类似 ScalarFloat32 ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarFloat64 added in v1.5.0 

func (c *DbClientEx) MustScalarFloat64(query string, args ...any) (value *float64, ok bool)

MustScalarFloat64 类似 ScalarFloat64 ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarInt added in v1.5.0 

func (c *DbClientEx) MustScalarInt(query string, args ...any) (value *int, ok bool)

MustScalarInt 类似 ScalarInt ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarInt8 added in v1.5.0 

func (c *DbClientEx) MustScalarInt8(query string, args ...any) (value *int8, ok bool)

MustScalarInt8 类似 ScalarInt8 ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarInt16 added in v1.5.0 

func (c *DbClientEx) MustScalarInt16(query string, args ...any) (value *int16, ok bool)

MustScalarInt16 类似 ScalarInt16 ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarInt32 added in v1.5.0 

func (c *DbClientEx) MustScalarInt32(query string, args ...any) (value *int32, ok bool)

MustScalarInt32 类似 ScalarInt32 ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarInt64 added in v1.5.0 

func (c *DbClientEx) MustScalarInt64(query string, args ...any) (value *int64, ok bool)

MustScalarInt64 类似 ScalarInt64 ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarOf added in v1.5.0 

func (c *DbClientEx) MustScalarOf(example any, query string, args ...any) (value any, ok bool, err error)

MustScalarOf 类似 ScalarOf ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarString added in v1.5.0 

func (c *DbClientEx) MustScalarString(query string, args ...any) (value *string, ok bool)

MustScalarString 类似 ScalarString ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustScalarType added in v1.5.0 

func (c *DbClientEx) MustScalarType(typ reflect.Type, query string, args ...any) (value any, ok bool)

MustScalarType 类似 ScalarType ，但出现错误时不返回 error ，而是 panic 。

func (*DbClientEx) MustSizedExecute added in v1.7.0 

func (client *DbClientEx) MustSizedExecute(expectedSize int64, sqlText string, args ...any)

MustSizedExecute 用于执行非查询 sql 语句，并断言所影响的行数。 params: 

@expectedSize 预期的影响行数，当
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
  • sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustSizedExecuteContext added in v1.7.0 

func (client *DbClientEx) MustSizedExecuteContext(ctx context.Context, expectedSize int64, sqlText string, args ...any)

MustSizedExecuteContext 用于执行非查询 sql 语句，并断言所影响的行数。 params: 

@ctx context。
@expectedSize 预期的影响行数，当
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

可能 panic 出的 error （可以通过 errors.Is 判断）：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
  • sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustSliceGet added in v1.7.0 

func (client *DbClientEx) MustSliceGet(sqlText string, args ...any) []map[string]any

MustSliceGet 用于获取查询结果的所有行。 params: 

@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRows 目标查询结果的所有行。

可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以判断返回值是否为 nil：

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) MustSliceGetContext added in v1.7.0 

func (client *DbClientEx) MustSliceGetContext(ctx context.Context, sqlText string, args ...any) []map[string]any

MustSliceGetContext 用于获取查询结果的所有行。 params: 

@ctx context。
@sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
@args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。

returns: 

@mapRows 目标查询结果的所有行。

可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，要知道是否有数据可直接判断返回值的 len。

  • sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
  • sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。

func (*DbClientEx) ScalarBool added in v1.5.0 

func (c *DbClientEx) ScalarBool(query string, args ...any) (value *bool, ok bool, err error)

ScalarBool 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarFloat32 added in v1.5.0 

func (c *DbClientEx) ScalarFloat32(query string, args ...any) (value *float32, ok bool, err error)

ScalarFloat32 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarFloat64 added in v1.5.0 

func (c *DbClientEx) ScalarFloat64(query string, args ...any) (value *float64, ok bool, err error)

ScalarFloat64 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarInt added in v1.5.0 

func (c *DbClientEx) ScalarInt(query string, args ...any) (value *int, ok bool, err error)

ScalarInt 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarInt8 added in v1.5.0 

func (c *DbClientEx) ScalarInt8(query string, args ...any) (value *int8, ok bool, err error)

ScalarInt8 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarInt16 added in v1.5.0 

func (c *DbClientEx) ScalarInt16(query string, args ...any) (value *int16, ok bool, err error)

ScalarInt16 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarInt32 added in v1.5.0 

func (c *DbClientEx) ScalarInt32(query string, args ...any) (value *int32, ok bool, err error)

ScalarInt32 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarInt64 added in v1.5.0 

func (c *DbClientEx) ScalarInt64(query string, args ...any) (value *int64, ok bool, err error)

ScalarInt64 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarOf added in v1.5.0 

func (c *DbClientEx) ScalarOf(example any, query string, args ...any) (value any, ok bool, err error)

ScalarOf 查询第一行第一列，并返回与 example 相同类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

下面两行代码等价： 

client.ScalarOf("", query)
client.ScalarType(reflect.TypeOf(""), query)

func (*DbClientEx) ScalarString added in v1.5.0 

func (c *DbClientEx) ScalarString(query string, args ...any) (value *string, ok bool, err error)

ScalarString 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回空指针和 ok=false ；若有结果但值是 null ，则返回空指针和 ok=true 。 若值不是目标类型，则尝试转换类型。

func (*DbClientEx) ScalarType added in v1.5.0 

func (c *DbClientEx) ScalarType(typ reflect.Type, query string, args ...any) (value any, ok bool, err error)

ScalarType 查询第一行第一列，并返回目标类型的值。 若查询没有命中行，返回 nil 和 ok=false ；若有结果但值是 null ，则返回 nil 和 ok=true 。 若值不是目标类型，则尝试转换类型。

例1，获取可空字段： 

var s *string
v, ok, err := client.ScalarType(reflect.TypeOf(s), querySomeNullable)
if err != nil && ok {
  s = v.(*string)
}

例2，获取非空字段： 

var s string
v, ok, err := client.ScalarType(reflect.TypeOf(s), querySomeNonNullable)
if err != nil && ok {
  s = v.(string)
}

type DbClientOption 

type DbClientOption func(config *DbClientConfig) error

DbClientOption 是 DbClientConfig 的可选配置。

func WithBindArgsFunc 

func WithBindArgsFunc(argsFunc BindSqlArgsFunc) DbClientOption

WithBindArgsFunc 用于为 DbClientConfig 设置处理参数的函数。

func WithConnTimeout 

func WithConnTimeout(timeout time.Duration) DbClientOption

WithConnTimeout 用于为 DbClientConfig 设置获取数据库连接的超时时间。

func WithDb added in v1.2.0 

func WithDb(db *sql.DB, driver string, dsn string) DbClientOption

WithDb 用于用现有的 sql.DB 初始化 DbClientOption。

func WithDsn added in v1.3.11 

func WithDsn(driver string, dsn string) DbClientOption

WithDsn 用于用现有的 sql.DB 初始化 DbClientOption。

func WithExecTimeout 

func WithExecTimeout(timeout time.Duration) DbClientOption

WithExecTimeout 用于为 DbClientConfig 设置默认的执行超时时间。

func WithGetScanTypeFunc added in v1.3.11 

func WithGetScanTypeFunc(scanFunc sqlen.GetScanTypeFunc) DbClientOption

WithBindArgsFunc 用于为 DbClientConfig 设置根据列信息获取 Scan 类型的函数。

func WithPingCheck added in v1.2.0 

func WithPingCheck(withPingCheck bool) DbClientOption

WithPingCheck 用于选择是否在初始化 DbClient 时候进行 ping 操作（默认为 false）。

func WithUnifyDataTypeFunc added in v1.3.1 

func WithUnifyDataTypeFunc(unifyDataType sqlen.UnifyDataTypeFn) DbClientOption

WithUnifyDataTypeFunc 用于为 DbClient 注入驱动相关的类型转换逻辑。

type MustDbClient added in v1.3.10 

type MustDbClient interface {

	// MustCreateTransactionEx（和 MustCreateTransaction 一致） 用于开始一个事务。
	// returns:
	//	@tran 返回一个TransactionKeeperEx 实例（实现了 TransactionKeeper、DbClient 接口） 接口的对象，在上面执行的语句会在同一个事务中执行。
	MustCreateTransaction() (tran *TransactionKeeperEx)

	// MustExecute 用于执行非查询 sql 语句，并返回所影响的行数。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @effectedRows 语句影响的行数。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustExecute(sqlText string, args ...any) (rowsEffected int64)

	// MustExecuteContext 用于执行非查询SQL语句，并返回所影响的行数。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @effectedRows 语句影响的行数。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustExecuteContext(context context.Context, sqlText string, args ...any) (rowsEffected int64)

	// MustSizedExecute 用于执行非查询 sql 语句，并断言所影响的行数。
	// params:
	//  @expectedSize 预期的影响行数，当
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustSizedExecute(expectedSize int64, sqlText string, args ...any)

	// MustSizedExecuteContext 用于执行非查询 sql 语句，并断言所影响的行数。
	// params:
	//  @ctx context。
	//  @expectedSize 预期的影响行数，当
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrGetEffectedRows: 当执行成功，但驱动不支持获取影响行数时候，返回该类型错误。
	//  - sqlmer.ErrExpectedSizeWrong: 当没有影响到预期行数时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustSizedExecuteContext(context context.Context, expectedSize int64, sqlText string, args ...any)

	// MustExists 用于判断给定的查询的结果是否至少包含 1 行。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @ok 结果至少包含一行。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustExists(sqlText string, args ...any) (ok bool)

	// MustExistsContext 用于判断给定的查询的结果是否至少包含 1 行。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @ok 结果至少包含一行。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustExistsContext(context context.Context, sqlText string, args ...any) (ok bool)

	// MustScalar 用于获取查询的第一行第一列的值。
	// Scalar 用于获取查询的第一行第一列的值。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @cell 目标查询第一行第一列的值。
	//  @hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。
	// 可能 panic 出的 error（可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以通过第二个返回值区分：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustScalar(sqlText string, args ...any) (cell any, hit bool)

	// MustScalarContext 用于获取查询的第一行第一列的值。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @cell 目标查询第一行第一列的值。
	//  @hit true 表明有命中数据，false 则为没有命中数据，可通过该值区分是否为数据库空值。
	// 可能 panic 出的 error（可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以通过第二个返回值区分：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustScalarContext(context context.Context, sqlText string, args ...any) (cell any, hit bool)

	// MustGet 用于获取查询结果的第一行记录。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRow 目标查询第一行的结果。
	// 可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以判断返回值是否为 nil：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustGet(sqlText string, args ...any) (mapRow map[string]any)

	// MustGetContext 用于获取查询结果的第一行记录。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRow 目标查询第一行的结果。
	// 可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以判断返回值是否为 nil：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustGetContext(context context.Context, sqlText string, args ...any) (mapRow map[string]any)

	// MustSliceGet 用于获取查询结果的所有行。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRows 目标查询结果的所有行。
	// 可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，可以判断返回值是否为 nil：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustSliceGet(sqlText string, args ...any) (mapRows []map[string]any)

	// MustSliceGetContext 用于获取查询结果的所有行。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @mapRows 目标查询结果的所有行。
	// 可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，要知道是否有数据可直接判断返回值的 len。
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustSliceGetContext(context context.Context, sqlText string, args ...any) (mapRows []map[string]any)

	// MustRow 用于获取单个查询结果行。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。
	// 可能 panic 出的 error （可以通过 errors.Is 判断），注意，sql.ErrNoRows 不会 panic，要知道是否有数据可直接判断返回值的 len。
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustRow(sqlText string, args ...any) (row *sqlen.EnhanceRow)

	// MustRowContext 用于获取单个查询结果行。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRow 对象（是对 sql.Row 的增强包装对象）。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustRowContext(context context.Context, sqlText string, args ...any) (row *sqlen.EnhanceRow)

	// MustRows 用于获取查询结果行的游标对象。
	// params:
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustRows(sqlText string, args ...any) (rows *sqlen.EnhanceRows)

	// MustRowsContext 用于获取查询结果行的游标对象。
	// params:
	//  @ctx context。
	//  @sqlText SQL 语句，支持 @ 的命名参数占位及 @p1...@pn 这样的索引占位符。
	//  @args SQL 语句的参数，支持通过 map[string]any 提供命名参数值 或 通过变长参数提供索引参数值。
	// returns:
	//  @row 返回目标行的 EnhanceRows 对象（是对 sql.Rows 的增强包装对象）。
	// 可能 panic 出的 error （可以通过 errors.Is 判断）：
	//  - sqlmer.ErrParseParamFailed: 当 SQL 语句中的参数解析失败时返回该类错误。
	//  - sqlmer.ErrExecutingSql: 当 SQL 语句执行时遇到错误，返回该类型错误。
	MustRowsContext(context context.Context, sqlText string, args ...any) (rows *sqlen.EnhanceRows)
}

MustDbClient 提供了 DBClient 的 panic 版本 API

type TransactionKeeper 

type TransactionKeeper interface {
	DbClient // DbClient 实现了数据库访问客户端的功能。
	// Commit 用于提交事务。
	Commit() error

	// Rollback 用于回滚事务。
	Rollback() error

	// Close 用于优雅关闭事务，创建事务后可 defer 执行本方法。
	Close() error
}

TransactionKeeper 是一个定义数据库事务容器。

type TransactionKeeperEx added in v1.5.2 

type TransactionKeeperEx struct {
	*DbClientEx
	TransactionKeeper
}

TransactionKeeperEx 扩展 TransactionKeeper ，增加 DbClientEx 的功能和 Must 版本的事务 API。

func ExtendTx added in v1.7.3 

func ExtendTx(raw TransactionKeeper) *TransactionKeeperEx

ExtendTx 加强 TransactionKeeper 。

  • 提供 Must 版本的 API；

func (*TransactionKeeperEx) MustClose added in v1.7.0 

func (transKeeper *TransactionKeeperEx) MustClose()

MustClose 用于优雅关闭事务，创建事务后务必执行本方法或 Close 方法。

func (*TransactionKeeperEx) MustCommit added in v1.7.0 

func (transKeeper *TransactionKeeperEx) MustCommit()

MustCommit 用于提交事务。

func (*TransactionKeeperEx) MustRollback added in v1.7.0 

func (transKeeper *TransactionKeeperEx) MustRollback()

MustRollback 用于回滚事务。

Source Files

View all Source files

Directories

Path Synopsis
internal
testcmd command
testenv

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.