sqlmer

package module

v1.7.6 Latest Latest Go to latest Published: Mar 31, 2025 License: MIT Imports: 11 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bunnier/sqlmer

Links

Open Source Insights

README ¶

sqlmer

功能简介

一个面向原生 SQL 的数据库操作库，在保持 SQL 语句灵活性的同时，通过统一的接口设计、便捷的参数处理和轻量级的 ORM 映射能力，让数据库操作更加优雅高效。目前支持 MySQL 和 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 还是 SQL Server，都可以使用相同的 API 进行操作。

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

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

func init() {
	// 这里使用 MySQL (mysql 包)做示范，SQL Server （mssql 包）也提供了一致的 API 和相应的参数解析逻辑。
	var err error
	if dbClient, err = mysql.NewMySqlDbClient(
		"test:testpwd@tcp(127.0.0.1:3306)/test",
		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 int(11) NOT NULL AUTO_INCREMENT,
			Name VARCHAR(10) NOT NULL,
			Age INT NOT NULL,
			Scores VARCHAR(200) NOT NULL,
			PRIMARY KEY (Id),
			KEY demo (Id)
		)
	`)

	// 索引方式插入数据，@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, 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 +0000 UTC
			// bao 2022-04-09 22:35:33 +0000 UTC
		}
	}
	// 和标准库一样，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, _ := context.WithTimeout(context.Background(), time.Second*1)
	if _, err = dbClient.ExecuteContext(ctx, "SELECT sleep(3)"); 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)

	clientEx.Execute("SELECT sleep(1)") // Output: [SlowSql]Sql=SELECT sleep(1), Duration=1240(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

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：

默认的数据库连接字符串定义在 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;"
 }
```
如果第 1 步配置的连接字符串有 DDL 权限，可通过调用 go run ./internal/testcmd/main.go -a PREPARE 来同时准备 MySQL / SQL Server 环境，如果没有 DDL 权限可自行直接执行 internal/testenv/*_prepare.sql 准备环境；
如果第 1 步配置的连接字符串有 DDL 权限，测试结束后可以通过 go run ./internal/testcmd/main.go -a CLEAN 销毁测试表，如果没有 DDL 权限可自行直接执行 internal/testenv/*_clean.sql 销毁测试表。

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

其他语言的版本

.net 版： cmstar/Data

Documentation ¶

Index ¶

Variables
type AbstractDbClient
- func NewAbstractDbClient(config *DbClientConfig) (*AbstractDbClient, error)
type BindSqlArgsFunc
type DbClient
type DbClientConfig
- func NewDbClientConfig(options ...DbClientOption) (*DbClientConfig, error)
type DbClientEx
- func Extend(raw DbClient) *DbClientEx
type DbClientOption
type MustDbClient
type TransactionKeeper
type TransactionKeeperEx
- func ExtendTx(raw TransactionKeeper) *TransactionKeeperEx

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) 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) MustScalarInt8 ¶ added in v1.5.0

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

MustScalarInt8 类似 ScalarInt8 ，但出现错误时不返回 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) 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) 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) 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
example
internal
testcmd
testenv
mssql
mysql
sqlen
wrap

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL