Documentation
¶
Overview ¶
Package sql 提供基于 GORM 的关系型数据库客户端封装,支持 MySQL、ClickHouse 与 PostgreSQL。
该包通过 Client 配合 Option 完成连接配置,由 Dsn 与 Dialector 按 DriverName 生成对应 方言;SqlConn 按 DSN 缓存复用已建立的连接,可按需挂载指标采集与链路追踪拦截器。 包内同时提供 GORM 日志适配、分页/范围/排序参数辅助类型,以及可接受错误的判定工具。
Index ¶
- Constants
- Variables
- func Acceptable(err error) error
- func ErrorIn(err error, errs ...error) bool
- func LoggerCaller(skip int) map[string]string
- func RegisterInterceptor(db *gorm.DB, options *Client, interceptors ...Interceptor)
- type Client
- func (c *Client) ClickHouseDialector() (gorm.Dialector, error)
- func (c *Client) ClickHouseDsn() string
- func (c *Client) Dialector() (gorm.Dialector, error)
- func (c *Client) Dsn() (string, error)
- func (c *Client) MySqlDialector() (gorm.Dialector, error)
- func (c *Client) MySqlDsn() string
- func (c *Client) Open() (*ClientManager, error)
- func (c *Client) PostgreSQLDialector() (gorm.Dialector, error)
- func (c *Client) PostgreSQLDsn() string
- func (c *Client) SqlConn() (*gorm.DB, error)
- type ClientManager
- type Handler
- type Interceptor
- type Option
- func WithCharset(charset string) Option
- func WithDatabase(database string) Option
- func WithDialTimeOut(dialTimeOut string) Option
- func WithDriverName(driverName string) Option
- func WithEnableDebug(disableDebug bool) Option
- func WithEnableMetric(disableMetric bool) Option
- func WithEnableTrace(disableTrace bool) Option
- func WithHost(host string) Option
- func WithMaxIdleConns(maxIdleConns int) Option
- func WithMaxIdleTime(maxIdleTime time.Duration) Option
- func WithMaxLifetime(maxLifetime time.Duration) Option
- func WithMaxOpenConns(maxOpenConns int) Option
- func WithName(Name string) Option
- func WithParseTime(parseTime bool) Option
- func WithPassword(password string) Option
- func WithPort(port string) Option
- func WithReadTimeOut(readTimeOut string) Option
- func WithSslMode(sslMode bool) Option
- func WithTimeZone(timeZone string) Option
- func WithUsername(username string) Option
- type Pagination
- type Scope
- type Sort
- type WrapEntry
- func (l *WrapEntry) Error(ctx context.Context, s string, args ...any)
- func (l *WrapEntry) Info(ctx context.Context, s string, args ...any)
- func (l *WrapEntry) LogMode(level logger.LogLevel) logger.Interface
- func (l *WrapEntry) SetDebug(debug bool)
- func (l *WrapEntry) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error)
- func (l *WrapEntry) Warn(ctx context.Context, s string, args ...any)
- type WrapLogger
- func (l *WrapLogger) Error(ctx context.Context, s string, args ...any)
- func (l *WrapLogger) Info(ctx context.Context, s string, args ...any)
- func (l *WrapLogger) LogMode(level logger.LogLevel) logger.Interface
- func (l *WrapLogger) SetDebug(debug bool)
- func (l *WrapLogger) SetSkipErrRecordNotFound(skip bool)
- func (l *WrapLogger) SetSlowThreshold(threshold time.Duration)
- func (l *WrapLogger) SetSourceField(field string)
- func (l *WrapLogger) Trace(ctx context.Context, begin time.Time, fc func() (string, int64), err error)
- func (l *WrapLogger) Warn(ctx context.Context, s string, args ...any)
Constants ¶
const ( // MySQLDriverName 为 MySQL 驱动标识。 MySQLDriverName = "mysql" // ClickHouseDriverName 为 ClickHouse 驱动标识。 ClickHouseDriverName = "clickhouse" // PostgreSQLDriverName 为 PostgreSQL 驱动标识。 PostgreSQLDriverName = "postgres" // TDengineDriverName 为 TDengine 驱动标识;当前 Dsn 与 Dialector 尚未实现该分支。 TDengineDriverName = "tdengine" )
数据库驱动名称常量,供 Client.DriverName 选择 DSN 与方言构造分支。
Variables ¶
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
Acceptable 判定错误是否属于可忽略的常规情况:nil、上下文取消、记录不存在、驱动不返回 元数据等错误一律视为可接受并返回 nil;其余错误原样返回,交由调用方或日志层上报。
func LoggerCaller ¶ added in v3.8.17
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 ¶
NewClient 依据传入的 Option 构造 Client 配置对象。
该方法只完成配置装配,不立即建立数据库连接;实际连接在 Open 时才发起, 返回的 error 恒为 nil。
func (*Client) ClickHouseDialector ¶ added in v3.8.17
ClickHouseDialector 构造 ClickHouse 的 GORM 方言实例;DSN 构造失败时返回对应错误。
func (*Client) ClickHouseDsn ¶ added in v3.8.17
ClickHouseDsn 依据 Client 当前配置拼装 ClickHouse 连接字符串,附带连接与读取超时参数。
func (*Client) Dialector ¶ added in v3.8.17
Dialector 按 DriverName 生成 GORM 方言实例;驱动不受支持时返回 Dsn 产生的错误。
func (*Client) Dsn ¶ added in v3.8.17
Dsn 按 DriverName 生成对应驱动的连接字符串。
DriverName 为 mysql、clickhouse、postgres 时返回对应 DSN;其余驱动名称返回 包含驱动名的错误,当前不支持 TDengine。
func (*Client) MySqlDialector ¶ added in v3.8.17
MySqlDialector 构造 MySQL 的 GORM 方言实例;DSN 构造失败时返回对应错误。
func (*Client) MySqlDsn ¶ added in v3.8.17
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
PostgreSQLDialector 构造 PostgreSQL 的 GORM 方言实例;DSN 构造失败时返回对应错误。
func (*Client) PostgreSQLDsn ¶ added in v3.8.17
PostgreSQLDsn 依据 Client 当前配置拼装 PostgreSQL 连接字符串,按 SslMode 决定 sslmode 取值, 并附加 TimeZone 参数。
type ClientManager ¶ added in v3.8.17
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 Interceptor ¶ added in v3.8.17
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 WithDialTimeOut ¶ added in v3.8.17
WithDialTimeOut 设置建立连接的超时时间,仅 ClickHouse DSN 使用。
func WithDriverName ¶
WithDriverName 设置数据库驱动名称,取值见本包驱动名称常量。
func WithEnableDebug ¶ added in v3.8.21
WithEnableDebug 设置是否开启 GORM 调试日志输出,传入 true 开启。
func WithEnableMetric ¶ added in v3.8.21
WithEnableMetric 设置是否采集 SQL 操作指标,传入 true 开启。
func WithEnableTrace ¶ added in v3.8.21
WithEnableTrace 设置是否挂载 SQL 链路追踪拦截器,传入 true 开启。
func WithMaxIdleConns ¶
WithMaxIdleConns 设置连接池中空闲连接的最大数量,应小于最大打开连接数。
func WithMaxIdleTime ¶
WithMaxIdleTime 设置连接池中连接的最大空闲时长。
func WithMaxLifetime ¶
WithMaxLifetime 设置连接池中连接的最大存活时长。
func WithMaxOpenConns ¶
WithMaxOpenConns 设置连接池允许同时打开的最大连接数。
func WithParseTime ¶
WithParseTime 设置是否开启 DSN 中的时间解析开关,仅 MySQL DSN 使用。
func WithReadTimeOut ¶ added in v3.8.17
WithReadTimeOut 设置读取超时时间,仅 ClickHouse DSN 使用。
func WithSslMode ¶ added in v3.8.17
WithSslMode 设置是否启用 SSL 连接,仅 PostgreSQL DSN 使用。
func WithTimeZone ¶
WithTimeZone 设置数据库时区,MySQL 与 PostgreSQL DSN 使用。
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
Scope 承载起止范围参数,Start 与 End 为指针,未设置时对应取值方法返回 nil 错误; 取值方法按字符串、整数、浮点三种类型分别提供转换。
func (*Scope) GetEndFloat64 ¶ added in v3.8.21
GetEndFloat64 以 float64 形式返回结束值;End 为 nil 时返回错误。
func (*Scope) GetEndInt64 ¶ added in v3.8.21
GetEndInt64 以 int64 形式返回结束值;End 为 nil 时返回错误。
func (*Scope) GetEndString ¶ added in v3.8.21
GetEndString 以字符串形式返回结束值;End 为 nil 时返回错误。
func (*Scope) GetStartFloat64 ¶ added in v3.8.21
GetStartFloat64 以 float64 形式返回起始值;Start 为 nil 时返回错误。
func (*Scope) GetStartInt64 ¶ added in v3.8.21
GetStartInt64 以 int64 形式返回起始值;Start 为 nil 时返回错误。
func (*Scope) GetStartString ¶ added in v3.8.21
GetStartString 以字符串形式返回起始值;Start 为 nil 时返回错误。
type Sort ¶ added in v3.8.49
Sort 承载排序参数,Name 为排序字段,Desc 为是否降序;两者均为指针, 未设置时对应取值方法返回 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
NewEntry 基于给定 logrus.Entry 构造 WrapEntry,默认忽略记录不存在错误并开启调试输出。
传入 nil 会在首次记录日志时触发空指针解引用,调用方须提供有效的日志条目。
func (*WrapEntry) LogMode ¶ added in v3.8.17
LogMode 按 GORM 日志级别调整底层日志级别,并返回适配器自身以满足 logger.Interface 契约。
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 设置调用方源码位置在日志字段中的键名;传空字符串可关闭源码位置记录。