sqlmer

package module

v1.5.13 Latest Latest Go to latest Published: Feb 11, 2025 License: MIT Imports: 10 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

功能简介

数据库访问库，目前支持 MySQL 和 SQL Server。

增强了 SQL 参数解析逻辑，提供了统一的 命名参数、索引参数 语法，且可直观的使用 map 作为 SQL 语句参数；
提供了 面向 map 的交互接口，事务和非事务访问均可通过相同接口完成；
增强了原生 sql.Rows / sql.Row 的能力，使其支持自动检测列的类型及数量，自动 Scan 到合适的类型里，并装载到 Map 或 Slice 中；
支持全局/单独指定 SQL 语句的连接和读写超时；
提供了支持 嵌套事务 的事务 API；
能根据目标数据库的配置，自动配置 SetConnMaxLifetime (目前仅支持 MySQL)；
支持传递为 in 子句 传递 slice 类型的参数 (目前仅支持 MySQL)；

来个 Demo

package main

import (
	"context"
	"fmt"
	"log"
	"strconv"
	"strings"
	"time"

	"github.com/bunnier/sqlmer"
	"github.com/bunnier/sqlmer/mysql"
)

var dbClient sqlmer.DbClient // 这是本库的主接口，统一了各种数据库的 API 操作。
var err error                // 本库同时提供了 error/panic 两套 API，为了 demo 更为简洁，后续主要通过 panic(Must) 版本 API 演示。

func init() {
	// 这里使用 MySQL 做示范，SQL Server 也提供了一致的 API 和相应的参数解析逻辑。
	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)
	}
}

func main() {
	prepare()
	defer purge()

	selectionDemo()
	ormDemo()
	ormWithFieldConvert()
	transactionDemo()
	timeoutDemo()
}

func prepare() {
	// 创建/删除 测试表。
	dbClient.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 个参数。
	dbClient.MustExecute("INSERT INTO demo(Name, Age, Scores) VALUES(@p1, @p2, @p3)", "rui", 1, "SCORES:1,3,5,7")
	dbClient.MustExecute("INSERT INTO demo(Name, Age, Scores) VALUES(@p1, @p2, @p3)", "bao", 2, "SCORES:2,4,6,8")
}

func purge() {
	dbClient.MustExecute("DROP TABLE demo")
}

func selectionDemo() {
	// 命名参数查询数据，命名参数采用 map，key 为 sql 语句 @ 之后的参数名，value 为值。
	dataMap := dbClient.MustGet("SELECT * FROM demo WHERE Name=@name", map[string]any{"name": "rui"})
	fmt.Println(dataMap) // Output: map[Age:1 Id:1 Name:rui]

	// 获取第一行第一列，DBNull 和 未命中都会返回 nil，因此提供了第二返回值 hit（bool 类型）来区分是 DBNull 和无数据，这里不是可空字段因此无需判断。
	name, _ := dbClient.MustScalar("SELECT Name FROM demo WHERE Name=@p1", "rui")
	fmt.Println(name.(string)) // Output: rui

	// 如果喜欢标准库风格，这里也提供了增强版本的 sql.Rows，支持 SliceScan、MapScan。
	// 注意：
	//    - 这里 in 的参数适用了 slice 的方式，这个特性目前仅支持 MySQL，针对 SQL Server 暂时需要自行展开；
	//    - 如果 slice 为空，会被解析为 NULL ，这会导致 in/not in 语句均为 false；
	rows := dbClient.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 功能。将数据库的行，映射到 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]}
}

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

	// CreateTransaction 返回一个 TransactionKeeper ，
	// 它实现了 DbClient ，所以数据库操作方式和一般的 DbClient 完全一致。
	trans := dbClient.MustCreateTransaction()

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

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

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

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

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

	rowNum, _ = dbClient.MustScalar("SELECT count(1) FROM demo")
	fmt.Println(rowNum) // Output: 0
}

// 演示如何设置超时时间。 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()) // 预期内的超时~
	}
}

类型映射

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 ErrorDbClient
type ErrorTransactionKeeper
type MustDbClient
type MustTransactionKeeper
type TransactionKeeper
type 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) 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) MustCreateTransaction ¶ added in v1.2.0

func (client *AbstractDbClient) MustCreateTransaction() TransactionKeeper

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

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

func (*AbstractDbClient) MustExecute ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustExecuteContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustExists ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustExistsContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustGet ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustGetContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustRow ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustRowContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustRows ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustRowsContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustScalar ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustScalarContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustSizedExecute ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustSizedExecuteContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustSliceGet ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*AbstractDbClient) MustSliceGetContext ¶ added in v1.2.0

func (client *AbstractDbClient) 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 (*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() string  // Dsn 用于获取当前实例所使用的数据库连接字符串。
	ErrorDbClient // error 版本 API。
	MustDbClient  // panic 版本 API。
}

DbClient 定义了数据库访问客户端。

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 ，提供强类型的转化方法。

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() (tran *TransactionKeeperEx, err 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) MustCreateTransactionEx ¶ added in v1.5.3

func (c *DbClientEx) MustCreateTransactionEx() (tran *TransactionKeeperEx)

MustCreateTransactionEx 基于 DbClient.MustCreateTransaction 创建一个 TransactionKeeperEx 实例。

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

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

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

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) 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 ErrorDbClient ¶ added in v1.3.10

type ErrorDbClient interface {

	// 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 ErrorTransactionKeeper ¶ added in v1.3.10

type ErrorTransactionKeeper interface {
	// Commit 用于提交事务。
	Commit() error

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

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

ErrorTransactionKeeper 为 error 版本 API。

type MustDbClient ¶ added in v1.3.10

type MustDbClient interface {

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

	// 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 为 panic 版本 API

type MustTransactionKeeper ¶ added in v1.3.10

type MustTransactionKeeper interface {
	// MustClose 用于提交事务。
	MustCommit()

	// MustClose 用于回滚事务。
	MustRollback()

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

MustTransactionKeeper 为 panic 版本 API。

type TransactionKeeper ¶

type TransactionKeeper interface {
	DbClient               // DbClient 实现了数据库访问客户端的功能。
	ErrorTransactionKeeper // error 版本 API。
	MustTransactionKeeper  // panic 版本 API。
}

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

type TransactionKeeperEx ¶ added in v1.5.2

type TransactionKeeperEx struct {
	*DbClientEx
	TransactionKeeper
}

TransactionKeeperEx 扩展 TransactionKeeper ，增加 DbClientEx 的功能。

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
example
internal
testcmd command
testenv
mssql
mysql
sqlen

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