sql

package
v3.8.56 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: Apache-2.0 Imports: 28 Imported by: 1

Documentation

Overview

Package sql 提供基于 GORM 的关系型数据库客户端封装,支持 MySQL、ClickHouse 与 PostgreSQL。

该包通过 Client 配合 Option 完成连接配置,由 Dsn 与 Dialector 按 DriverName 生成对应 方言;SqlConn 按 DSN 缓存复用已建立的连接,可按需挂载指标采集与链路追踪拦截器。 包内同时提供 GORM 日志适配、分页/范围/排序参数辅助类型,以及可接受错误的判定工具。

Index

Constants

View Source
const (
	// MySQLDriverName 为 MySQL 驱动标识。
	MySQLDriverName = "mysql"
	// ClickHouseDriverName 为 ClickHouse 驱动标识。
	ClickHouseDriverName = "clickhouse"
	// PostgreSQLDriverName 为 PostgreSQL 驱动标识。
	PostgreSQLDriverName = "postgres"
	// TDengineDriverName 为 TDengine 驱动标识;当前 Dsn 与 Dialector 尚未实现该分支。
	TDengineDriverName = "tdengine"
)

数据库驱动名称常量,供 Client.DriverName 选择 DSN 与方言构造分支。

Variables

View Source
var (
	// ErrLastInsertIdIsNotSupported 表示当前驱动不支持获取 LastInsertId。
	ErrLastInsertIdIsNotSupported = errors.New("LastInsertId is not supported by this driver")
	// ErrRowsAffectedIsNotSupported 表示当前驱动不支持获取 RowsAffected。
	ErrRowsAffectedIsNotSupported = errors.New("RowsAffected is not supported by this driver")
	// ErrNoLastInsertIdAvailable 表示执行 DDL 语句后无法取得 LastInsertId。
	ErrNoLastInsertIdAvailable = errors.New("no LastInsertId available after DDL statement")
	// ErrNoRowsAffectedAvailable 表示执行 DDL 语句后无法取得 RowsAffected。
	ErrNoRowsAffectedAvailable = errors.New("no RowsAffected available after DDL statement")
)

SQL 驱动不返回结果元数据时使用的错误变量,由 Acceptable 判定为可接受错误。

Functions

func Acceptable added in v3.8.18

func Acceptable(err error) error

Acceptable 判定错误是否属于可忽略的常规情况:nil、上下文取消、记录不存在、驱动不返回 元数据等错误一律视为可接受并返回 nil;其余错误原样返回,交由调用方或日志层上报。

func ErrorIn added in v3.8.18

func ErrorIn(err error, errs ...error) bool

ErrorIn 判断 err 是否为 errs 中的任意一个错误,基于 errors.Is 进行包装错误匹配。

func LoggerCaller added in v3.8.17

func LoggerCaller(skip int) map[string]string

LoggerCaller 返回跳过 skip 层调用栈后当前调用方的文件、函数名与行号映射, 用于日志或追踪信息中定位原始调用位置;skip 超出调用栈深度时返回零值字段。

func RegisterInterceptor added in v3.8.17

func RegisterInterceptor(db *gorm.DB, options *Client, interceptors ...Interceptor)

RegisterInterceptor 将给定拦截器依次包装到 GORM 的 Create、Query、Delete、Update、 Row、Raw 六个回调阶段;替换阶段处理器失败时直接 panic,属于初始化期配置错误。

各拦截器按传入顺序叠加,后注册的在外层包装。

Types

type Client

type Client struct {
	// Host 为数据库主机地址(IP 或域名)。
	Host string
	// Port 为数据库服务端口。
	Port string
	// Username 为数据库登录用户名。
	Username string
	// Password 为数据库登录密码。
	Password string
	// Charset 为数据库字符集,仅 MySQL DSN 使用。
	Charset string
	// Database 为要连接的数据库名称。
	Database string
	// ParseTime 指定是否在 DSN 中开启时间解析,仅 MySQL DSN 使用。
	ParseTime bool
	// TimeZone 为数据库时区,MySQL 与 PostgreSQL DSN 使用。
	TimeZone string
	// SslMode 指定是否启用 SSL 连接,仅 PostgreSQL DSN 使用。
	SslMode bool
	// DialTimeOut 为建立连接的超时时间,仅 ClickHouse DSN 使用。
	DialTimeOut string
	// ReadTimeOut 为读取超时时间,仅 ClickHouse DSN 使用。
	ReadTimeOut string
	// MaxIdleConns 为连接池中空闲连接的最大数量,应小于 MaxOpenConns。
	MaxIdleConns int
	// MaxOpenConns 为连接池允许同时打开的最大连接数。
	MaxOpenConns int
	// MaxLifetime 为连接池中连接的最大存活时长,超过后会被回收重建。
	MaxLifetime time.Duration
	// MaxIdleTime 为连接池中连接的最大空闲时长,超过后会被关闭。
	MaxIdleTime time.Duration
	// EnableMetric 是否采集 SQL 操作指标。
	EnableMetric bool
	// EnableTrace 是否挂载 SQL 链路追踪拦截器。
	EnableTrace bool
	// EnableDebug 是否开启 GORM 调试日志输出。
	EnableDebug bool
	// DriverName 指定使用的数据库驱动,取值见本包驱动名称常量。
	DriverName string
	// Name 为连接实例名称,参与连接缓存的去重标识。
	Name string
}

Client 保存关系型数据库的全部连接配置,由各 With* Option 在 NewClient 阶段装配。

零值不可直接使用,须先通过 Option 填写 Host、Port、Username、Password、Database、 DriverName 等必填项后再调用 Open;Client 为配置载体,应在初始化阶段一次性写入, 不保证并发修改安全。

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient 依据传入的 Option 构造 Client 配置对象。

该方法只完成配置装配,不立即建立数据库连接;实际连接在 Open 时才发起, 返回的 error 恒为 nil。

func (*Client) ClickHouseDialector added in v3.8.17

func (c *Client) ClickHouseDialector() (gorm.Dialector, error)

ClickHouseDialector 构造 ClickHouse 的 GORM 方言实例;DSN 构造失败时返回对应错误。

func (*Client) ClickHouseDsn added in v3.8.17

func (c *Client) ClickHouseDsn() string

ClickHouseDsn 依据 Client 当前配置拼装 ClickHouse 连接字符串,附带连接与读取超时参数。

func (*Client) Dialector added in v3.8.17

func (c *Client) Dialector() (gorm.Dialector, error)

Dialector 按 DriverName 生成 GORM 方言实例;驱动不受支持时返回 Dsn 产生的错误。

func (*Client) Dsn added in v3.8.17

func (c *Client) Dsn() (string, error)

Dsn 按 DriverName 生成对应驱动的连接字符串。

DriverName 为 mysql、clickhouse、postgres 时返回对应 DSN;其余驱动名称返回 包含驱动名的错误,当前不支持 TDengine。

func (*Client) MySqlDialector added in v3.8.17

func (c *Client) MySqlDialector() (gorm.Dialector, error)

MySqlDialector 构造 MySQL 的 GORM 方言实例;DSN 构造失败时返回对应错误。

func (*Client) MySqlDsn added in v3.8.17

func (c *Client) MySqlDsn() string

MySqlDsn 依据 Client 当前配置拼装 MySQL 连接字符串,按 ParseTime 追加 parseTime 参数。

func (*Client) Open added in v3.8.17

func (c *Client) Open() (*ClientManager, error)

Open 依据当前配置建立数据库连接,完成方言初始化、连接池参数配置与连通性 Ping 校验。

成功时返回包装 *gorm.DB 的 ClientManager;方言构造、GORM 初始化、连接池设置或 Ping 任一环节失败都会返回错误,Ping 失败时会主动关闭已建立的连接。开启指标采集或 链路追踪时,会向 GORM 回调注册对应拦截器。

func (*Client) PostgreSQLDialector added in v3.8.17

func (c *Client) PostgreSQLDialector() (gorm.Dialector, error)

PostgreSQLDialector 构造 PostgreSQL 的 GORM 方言实例;DSN 构造失败时返回对应错误。

func (*Client) PostgreSQLDsn added in v3.8.17

func (c *Client) PostgreSQLDsn() string

PostgreSQLDsn 依据 Client 当前配置拼装 PostgreSQL 连接字符串,按 SslMode 决定 sslmode 取值, 并附加 TimeZone 参数。

func (*Client) SqlConn added in v3.8.17

func (c *Client) SqlConn() (*gorm.DB, error)

SqlConn 获取按 DSN 缓存复用的数据库连接,返回底层 *gorm.DB。

首次获取时调用 Open 建立连接并缓存;DSN 构造失败或连接建立失败时返回错误。

type ClientManager added in v3.8.17

type ClientManager struct {
	*gorm.DB
}

ClientManager 包装已建立连接的 *gorm.DB,对外提供关闭连接与获取底层实例的能力。

实例由 Open 创建并可按 DSN 缓存复用;底层 *gorm.DB 的并发安全由 GORM 自身保证; Close 关闭底层连接池后不应再复用该实例。

func (*ClientManager) Close added in v3.8.17

func (c *ClientManager) Close() error

Close 关闭底层数据库连接池,返回底层驱动 Close 的错误;未建立连接时返回对应错误。

func (*ClientManager) Gorm added in v3.8.17

func (c *ClientManager) Gorm() *gorm.DB

Gorm 返回底层 *gorm.DB 实例,供直接执行 GORM 链式查询使用。

type Handler added in v3.8.17

type Handler func(*gorm.DB)

Handler 为 GORM 回调中被拦截包装的下一层处理器。

type Interceptor added in v3.8.17

type Interceptor func(op string, client *Client, next Handler) Handler

Interceptor 以装饰器形式包装 GORM 回调处理器:op 为回调阶段名,client 为连接配置, next 为原处理器,返回包装后的处理器。

func MetricInterceptor added in v3.8.17

func MetricInterceptor() Interceptor

MetricInterceptor 返回采集 SQL 操作计数的拦截器:执行原处理器后按是否出错上报 成功或错误计数,错误状态收敛为短标签以控制指标标签基数。

func TraceInterceptor added in v3.8.17

func TraceInterceptor() Interceptor

TraceInterceptor 返回挂载客户端链路追踪的拦截器:仅当请求上下文非空时开启 Span, 在 Span 上记录数据库名、主机、用户名与 SQL 语句,并将错误写入 Span 状态; 上下文为空时直接透传给原处理器。

type Option

type Option func(r *Client)

Option 是 Client 的配置选项函数,以函数式选项模式在 NewClient 中装配配置。

func WithCharset

func WithCharset(charset string) Option

WithCharset 设置数据库字符集,仅 MySQL DSN 使用。

func WithDatabase

func WithDatabase(database string) Option

WithDatabase 设置要连接的数据库名称。

func WithDialTimeOut added in v3.8.17

func WithDialTimeOut(dialTimeOut string) Option

WithDialTimeOut 设置建立连接的超时时间,仅 ClickHouse DSN 使用。

func WithDriverName

func WithDriverName(driverName string) Option

WithDriverName 设置数据库驱动名称,取值见本包驱动名称常量。

func WithEnableDebug added in v3.8.21

func WithEnableDebug(disableDebug bool) Option

WithEnableDebug 设置是否开启 GORM 调试日志输出,传入 true 开启。

func WithEnableMetric added in v3.8.21

func WithEnableMetric(disableMetric bool) Option

WithEnableMetric 设置是否采集 SQL 操作指标,传入 true 开启。

func WithEnableTrace added in v3.8.21

func WithEnableTrace(disableTrace bool) Option

WithEnableTrace 设置是否挂载 SQL 链路追踪拦截器,传入 true 开启。

func WithHost

func WithHost(host string) Option

WithHost 设置数据库主机地址。

func WithMaxIdleConns

func WithMaxIdleConns(maxIdleConns int) Option

WithMaxIdleConns 设置连接池中空闲连接的最大数量,应小于最大打开连接数。

func WithMaxIdleTime

func WithMaxIdleTime(maxIdleTime time.Duration) Option

WithMaxIdleTime 设置连接池中连接的最大空闲时长。

func WithMaxLifetime

func WithMaxLifetime(maxLifetime time.Duration) Option

WithMaxLifetime 设置连接池中连接的最大存活时长。

func WithMaxOpenConns

func WithMaxOpenConns(maxOpenConns int) Option

WithMaxOpenConns 设置连接池允许同时打开的最大连接数。

func WithName added in v3.8.50

func WithName(Name string) Option

WithName 设置连接实例名称,参与连接缓存的去重标识。

func WithParseTime

func WithParseTime(parseTime bool) Option

WithParseTime 设置是否开启 DSN 中的时间解析开关,仅 MySQL DSN 使用。

func WithPassword

func WithPassword(password string) Option

WithPassword 设置数据库登录密码。

func WithPort

func WithPort(port string) Option

WithPort 设置数据库服务端口。

func WithReadTimeOut added in v3.8.17

func WithReadTimeOut(readTimeOut string) Option

WithReadTimeOut 设置读取超时时间,仅 ClickHouse DSN 使用。

func WithSslMode added in v3.8.17

func WithSslMode(sslMode bool) Option

WithSslMode 设置是否启用 SSL 连接,仅 PostgreSQL DSN 使用。

func WithTimeZone

func WithTimeZone(timeZone string) Option

WithTimeZone 设置数据库时区,MySQL 与 PostgreSQL DSN 使用。

func WithUsername

func WithUsername(username string) Option

WithUsername 设置数据库登录用户名。

type Pagination added in v3.7.25

type Pagination struct {
	// Offset 为跳过的记录条数,nil 表示未设置。
	Offset *int64
	// Limit 为返回的记录条数,nil 表示未设置。
	Limit *int64
}

Pagination 承载分页参数,Offset 为偏移量,Limit 为每页条数;两者均为指针, 未设置时对应取值方法返回 nil 错误。

func (*Pagination) GetLimit added in v3.7.25

func (obj *Pagination) GetLimit() (int64, error)

GetLimit 返回每页条数;Limit 为 nil 时返回错误,调用方须先完成参数绑定与校验。

func (*Pagination) GetOffset added in v3.7.25

func (obj *Pagination) GetOffset() (int64, error)

GetOffset 返回偏移量;Offset 为 nil 时返回错误,调用方须先完成参数绑定与校验。

type Scope added in v3.8.21

type Scope struct {
	// Start 为范围起始值,nil 表示未设置。
	Start *string
	// End 为范围结束值,nil 表示未设置。
	End *string
}

Scope 承载起止范围参数,Start 与 End 为指针,未设置时对应取值方法返回 nil 错误; 取值方法按字符串、整数、浮点三种类型分别提供转换。

func (*Scope) GetEndFloat64 added in v3.8.21

func (obj *Scope) GetEndFloat64() (float64, error)

GetEndFloat64 以 float64 形式返回结束值;End 为 nil 时返回错误。

func (*Scope) GetEndInt64 added in v3.8.21

func (obj *Scope) GetEndInt64() (int64, error)

GetEndInt64 以 int64 形式返回结束值;End 为 nil 时返回错误。

func (*Scope) GetEndString added in v3.8.21

func (obj *Scope) GetEndString() (string, error)

GetEndString 以字符串形式返回结束值;End 为 nil 时返回错误。

func (*Scope) GetStartFloat64 added in v3.8.21

func (obj *Scope) GetStartFloat64() (float64, error)

GetStartFloat64 以 float64 形式返回起始值;Start 为 nil 时返回错误。

func (*Scope) GetStartInt64 added in v3.8.21

func (obj *Scope) GetStartInt64() (int64, error)

GetStartInt64 以 int64 形式返回起始值;Start 为 nil 时返回错误。

func (*Scope) GetStartString added in v3.8.21

func (obj *Scope) GetStartString() (string, error)

GetStartString 以字符串形式返回起始值;Start 为 nil 时返回错误。

type Sort added in v3.8.49

type Sort struct {
	// Name 为排序字段名,nil 表示未设置。
	Name *string
	// Desc 指定是否降序,nil 表示未设置。
	Desc *bool
}

Sort 承载排序参数,Name 为排序字段,Desc 为是否降序;两者均为指针, 未设置时对应取值方法返回 nil 错误。

func (*Sort) GetDesc added in v3.8.49

func (obj *Sort) GetDesc() (bool, error)

GetDesc 返回是否降序;Desc 为 nil 时返回错误。

func (*Sort) GetName added in v3.8.49

func (obj *Sort) GetName() (string, error)

GetName 返回排序字段名;Name 为 nil 时返回错误。

type WrapEntry added in v3.8.17

type WrapEntry struct {
	// Logrus 为底层日志条目,日志级别与输出均由它承载。
	Logrus *logrus.Entry
	// SlowThreshold 为慢 SQL 判定阈值,超过该耗时以 Warn 级别记录;为 0 时不判定慢查询。
	SlowThreshold time.Duration
	// SourceField 为调用方源码位置在日志字段中的键名;为空时不记录源码位置。
	SourceField string
	// SkipErrRecordNotFound 开启后忽略记录不存在类错误,不作为错误日志上报。
	SkipErrRecordNotFound bool
	// Debug 是否在正常路径下输出 Debug 级别 SQL 日志。
	Debug bool
}

WrapEntry 将 logrus.Entry 适配为 gorm logger.Interface,行为与 WrapLogger 一致, 区别在于底层持有带固定上下文字段的 Entry。

零值不可直接使用,须由 NewEntry 构造;各配置项不保证并发修改安全。

func NewEntry added in v3.8.17

func NewEntry(entry *logrus.Entry) *WrapEntry

NewEntry 基于给定 logrus.Entry 构造 WrapEntry,默认忽略记录不存在错误并开启调试输出。

传入 nil 会在首次记录日志时触发空指针解引用,调用方须提供有效的日志条目。

func (*WrapEntry) Error added in v3.8.17

func (l *WrapEntry) Error(ctx context.Context, s string, args ...any)

Error 记录 Error 级别日志,上下文透传给底层 logrus。

func (*WrapEntry) Info added in v3.8.17

func (l *WrapEntry) Info(ctx context.Context, s string, args ...any)

Info 记录 Info 级别日志,上下文透传给底层 logrus。

func (*WrapEntry) LogMode added in v3.8.17

func (l *WrapEntry) LogMode(level logger.LogLevel) logger.Interface

LogMode 按 GORM 日志级别调整底层日志级别,并返回适配器自身以满足 logger.Interface 契约。

func (*WrapEntry) SetDebug added in v3.8.17

func (l *WrapEntry) SetDebug(debug bool)

SetDebug 调整调试日志开关。

func (*WrapEntry) Trace added in v3.8.17

func (l *WrapEntry) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error)

Trace 记录一次 SQL 执行轨迹:记录不存在错误被忽略时不报错,超过慢查询阈值记 Warn, 调试开关开启时常规执行记 Debug;错误在未被忽略时记 Error。

func (*WrapEntry) Warn added in v3.8.17

func (l *WrapEntry) Warn(ctx context.Context, s string, args ...any)

Warn 记录 Warn 级别日志,上下文透传给底层 logrus。

type WrapLogger added in v3.8.17

type WrapLogger struct {
	// Logrus 为底层日志实例,日志级别与输出均由它承载。
	Logrus *logrus.Logger
	// SlowThreshold 为慢 SQL 判定阈值,超过该耗时以 Warn 级别记录;为 0 时不判定慢查询。
	SlowThreshold time.Duration
	// SourceField 为调用方源码位置在日志字段中的键名;为空时不记录源码位置。
	SourceField string
	// SkipErrRecordNotFound 开启后忽略记录不存在类错误,不作为错误日志上报。
	SkipErrRecordNotFound bool
	// Debug 是否在正常路径下输出 Debug 级别 SQL 日志。
	Debug bool
}

WrapLogger 将 logrus.Logger 适配为 gorm logger.Interface,供 GORM 输出 SQL 日志。

零值不可直接使用,须由 NewLogger 构造;各 Set* 方法在运行期调整开关与阈值, 不保证并发修改安全。

func NewLogger added in v3.8.17

func NewLogger(logger *logrus.Logger) *WrapLogger

NewLogger 基于给定 logrus.Logger 构造 WrapLogger,默认忽略记录不存在错误并开启调试输出。

传入 nil 会在首次记录日志时触发空指针解引用,调用方须提供有效的日志实例。

func (*WrapLogger) Error added in v3.8.17

func (l *WrapLogger) Error(ctx context.Context, s string, args ...any)

Error 记录 Error 级别日志,上下文透传给底层 logrus。

func (*WrapLogger) Info added in v3.8.17

func (l *WrapLogger) Info(ctx context.Context, s string, args ...any)

Info 记录 Info 级别日志,上下文透传给底层 logrus。

func (*WrapLogger) LogMode added in v3.8.17

func (l *WrapLogger) LogMode(level logger.LogLevel) logger.Interface

LogMode 按 GORM 日志级别调整底层 logrus 级别,并返回适配器自身以满足 logger.Interface 契约。

func (*WrapLogger) SetDebug added in v3.8.17

func (l *WrapLogger) SetDebug(debug bool)

SetDebug 调整调试日志开关。

func (*WrapLogger) SetSkipErrRecordNotFound added in v3.8.17

func (l *WrapLogger) SetSkipErrRecordNotFound(skip bool)

SetSkipErrRecordNotFound 设置是否忽略记录不存在类错误。

func (*WrapLogger) SetSlowThreshold added in v3.8.17

func (l *WrapLogger) SetSlowThreshold(threshold time.Duration)

SetSlowThreshold 设置慢 SQL 判定阈值;传 0 可关闭慢查询判定。

func (*WrapLogger) SetSourceField added in v3.8.17

func (l *WrapLogger) SetSourceField(field string)

SetSourceField 设置调用方源码位置在日志字段中的键名;传空字符串可关闭源码位置记录。

func (*WrapLogger) Trace added in v3.8.17

func (l *WrapLogger) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error)

Trace 记录一次 SQL 执行轨迹:记录不存在错误被忽略时不报错,超过慢查询阈值记 Warn, 调试开关开启时常规执行记 Debug;错误在未被忽略时记 Error。

func (*WrapLogger) Warn added in v3.8.17

func (l *WrapLogger) Warn(ctx context.Context, s string, args ...any)

Warn 记录 Warn 级别日志,上下文透传给底层 logrus。

Jump to

Keyboard shortcuts

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