sqlmer

package module
v1.5.3 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2022 License: MIT Imports: 10 Imported by: 0

README

sqlmer

License Go Go Report Card Go Reference

功能简介

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

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

来个 Demo

package main

import (
	"context"
	"fmt"
	"log"
	"time"

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

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

	// 这里使用 MySQL 做示范，SQL Server 也提供了一致的 API 和相应的参数解析逻辑。
	if dbClient, err = mysql.NewMySqlDbClient(
		"test:test@tcp(127.0.0.1:1433)/test",
		sqlmer.WithConnTimeout(time.Second*30), // 连接超时。
		sqlmer.WithExecTimeout(time.Second*30), // 读写超时(执行语句时候，如果没有指定超时时间，默认用这个)。
	); err != nil {
		log.Fatal(err)
	}

	// 创建/删除 测试表。
	dbClient.MustExecute(`
		CREATE TABLE demo(
			Id int(11) NOT NULL AUTO_INCREMENT,
			Name VARCHAR(10) NOT NULL,
			Age INT NOT NULL,
			PRIMARY KEY (Id),
			KEY demo (Id))`)
	defer dbClient.MustExecute("DROP TABLE demo")

	// 通过 context 设置超时时间。。
	ctx, _ := context.WithTimeout(context.Background(), time.Second*1)
	if _, err = dbClient.ExecuteContext(ctx, "SELECT sleep(3)"); err != nil {
		fmt.Println("timeout: " + err.Error()) // 预期内的超时~
	}

	// 索引方式插入数据，@p1..@pn，分别对应第 1..n 个参数。
	dbClient.MustExecute("INSERT INTO demo(Name, Age) VALUES(@p1, @p2)", "rui", 1)
	dbClient.MustExecute("INSERT INTO demo(Name, Age) VALUES(@p1, @p2)", "bao", 2)

	// 命名参数查询数据，命名参数采用 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。
	rows := dbClient.MustRows("SELECT Name, now() FROM demo WHERE Name IN (@p1, @p2)", "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)
	}

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

	trans := dbClient.MustCreateTransaction() // 事务操作也支持和 DbClient 几乎一致的 API。
	trans.MustExecute("DELETE FROM demo WHERE Id=1")

	embeddedTrans := trans.MustCreateTransaction() // 支持嵌套事务。
	embeddedTrans.MustExecute("DELETE FROM demo WHERE Id=2")
	embeddedTrans.MustCommit()
	embeddedTrans.MustClose() // 注意：嵌套事务也需要 Close。

	trans.MustCommit()
	trans.MustClose()

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

类型映射

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：

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

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

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

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

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

其他语言的版本

.net 版： cmstar/Data

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrConnect = errors.New("dbConnect")

ErrConnect 是 DbClient 获取数据库连接时遇到的错误。

View Source 
var ErrExecutingSql = errors.New("dbClient: failed to execute sql")

ErrExecutingSql 当执行 SQL 语句执行时遇到错误，返回该类型错误。

View Source 
var ErrExpectedSizeWrong = errors.New("dbClient: effected rows was wrong")

ErrExpectedSizeWrong 当执行语句时候，没有影响到预期行数，返回该类型错误。

View Source 
var ErrGetEffectedRows = errors.New("dbClient: the db driver do not support getting effected rows")

ErrGetEffectedRows 当数据库不支持获取影响行数时候，会返回改类型的错误。

View Source 
var ErrParseParamFailed = errors.New("dbClient: failed to parse named params")

ErrSqlParamParse 解析 SQL 语句中的参数遇到错误时候，会返回该类型错误。

View Source 
var ErrTran = errors.New("dbTrans")

ErrTran 是数据库执行事务操作遇到的错误。

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
internal
testcmd command
testenv

Jump to

Keyboard shortcuts

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