database

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DriverMySQL    = config.DriverMySQL
	DriverPostgres = config.DriverPostgres
)

内置驱动常量（更多驱动可通过 RegisterDialect 扩展）

Variables

View Source 
var DefaultManager = &Manager{picker: &RandomPicker{}}

DefaultManager 默认数据库管理器

View Source 
var DefaultRedis = NewRedisManager()

DefaultRedis 默认 Redis 管理器，包级 facade 代理到它。

View Source 
var RedisClient *redis.Client

RedisClient 全局 Redis 客户端（兼容 facade，由 RedisManager.Init 同步维护）。 保留供存量代码直接访问；新代码建议用 GetRedis() 或持有 *RedisManager 实例。

Functions

func AutoMigrate 

func AutoMigrate() error

AutoMigrate 自动迁移数据库表结构（由应用通过 WithMigrator/WithModels 注册）

func Close 

func Close() error

Close 关闭主库连接（兼容旧代码，从库连接请使用 CloseAll）

func CloseAll 

func CloseAll() error

CloseAll 关闭所有数据库连接（包括从库）

func CloseRedis 

func CloseRedis() error

CloseRedis 关闭 Redis 连接

func Dialector 

func Dialector(cfg *config.Config) gorm.Dialector

Dialector 根据配置返回 GORM Dialector。 驱动由 cfg.Database.Driver 决定，未指定或未注册时按 MySQL 兜底（向后兼容）。

func GetDB 

func GetDB() *gorm.DB

GetDB 获取数据库实例（默认主库，兼容旧代码）

func GetDBFromContext 

func GetDBFromContext(ctx context.Context) *gorm.DB

GetDBFromContext 根据上下文选择数据库

func GetReadDB 

func GetReadDB() *gorm.DB

GetReadDB 获取读库实例（按策略选择从库）

func GetRedis 

func GetRedis() *redis.Client

GetRedis 获取 Redis 客户端

func GetReplicas 

func GetReplicas() []*gorm.DB

GetReplicas 获取所有从库实例

func GetWriteDB 

func GetWriteDB() *gorm.DB

GetWriteDB 获取写库实例（主库）

func HealthCheck 

func HealthCheck() map[string]bool

HealthCheck 健康检查

func HealthCheckRedis 

func HealthCheckRedis(ctx context.Context) error

HealthCheckRedis Redis 健康检查

func InitDB 

func InitDB(cfg *config.Config) error

InitDB 初始化数据库连接（带重试机制），驱动由配置决定

func InitDBWithReplicas 

func InitDBWithReplicas(cfg *config.Config, replicaDSNs []string) error

InitDBWithReplicas 初始化数据库主从连接，驱动由配置决定

func InitRedis 

func InitRedis(cfg *config.Config) error

InitRedis 初始化 Redis 连接

func IsDBHealthy added in v1.1.0 

func IsDBHealthy() bool

IsDBHealthy 返回主库探活健康状态（#21）。 与 HealthCheck()（实时 ping）不同，这是后台探活维护的缓存标记， 供 readiness 探针快速判断是否接流量，避免每次探针都同步 ping。

func ReadQuery 

func ReadQuery(ctx context.Context, model any, query string, args ...any) error

ReadQuery 读查询（自动路由到从库）

func RegisterDialect 

func RegisterDialect(spec DialectSpec)

RegisterDialect 注册一种数据库方言。 同时把 DSN 构建器登记到 config 包，使 cfg.Database.DSN() 也能识别新驱动。 已注册的同名驱动会被覆盖。

用法示例（接入 SQLite）： 

import "gorm.io/driver/sqlite"

database.RegisterDialect(database.DialectSpec{
    Name:      "sqlite",
    Dialector: func(dsn string) gorm.Dialector { return sqlite.Open(dsn) },
    DSN:       func(c *config.DatabaseConfig) string { return c.Name }, // 文件路径
})

func RegisteredDialects 

func RegisteredDialects() []string

RegisteredDialects 返回所有已注册的驱动名（用于诊断）

func SetDefaultRedisManager added in v1.1.0 

func SetDefaultRedisManager(m *RedisManager)

SetDefaultRedisManager 提升指定 RedisManager 为全局默认，后续包级 facade 走它。 用于多实例场景或测试注入 mock。

func SetReplicaPicker 

func SetReplicaPicker(p ReplicaPicker)

SetReplicaPicker 设置默认管理器的从库选择策略

func StartDBProbing added in v1.1.0 

func StartDBProbing(ctx context.Context)

StartDBProbing 启动主库/从库探活后台循环（#21）。 阻塞，应通过 App.Go 在独立 goroutine 运行；ctx 取消时退出。

func Transaction 

func Transaction(fn func(tx *gorm.DB) error) error

Transaction 事务操作（自动使用主库）

func TransactionWithContext 

func TransactionWithContext(ctx context.Context, fn func(tx *gorm.DB) error) error

TransactionWithContext 带上下文的事务操作

func UseMaster 

func UseMaster(ctx context.Context) context.Context

UseMaster 强制使用主库（用于事务或需要实时数据的场景）

func UseReplica 

func UseReplica(ctx context.Context) context.Context

UseReplica 强制使用从库（用于报表查询等场景）

func WriteQuery 

func WriteQuery(ctx context.Context, model any, query string, args ...any) error

WriteQuery 写查询（强制使用主库）

Types

type DialectSpec 

type DialectSpec struct {
	// Name 驱动主名称（如 "mysql"、"postgres"、"sqlite"），大小写不敏感
	Name string
	// Aliases 驱动别名（如 postgres 的 "postgresql"、"pg"）
	Aliases []string
	// Dialector 由 DSN 构造 GORM Dialector
	Dialector DialectorFactory
	// DSN 由 DatabaseConfig 拼接连接字符串。可选——
	// 不提供时使用 cfg.MySQLDSN() 兜底（适合自定义驱动通过 CustomDSN 指定连接串的场景）
	DSN config.DSNBuilder
}

DialectSpec 描述一种数据库方言：如何建立连接 + 如何拼接 DSN

type DialectorFactory 

type DialectorFactory func(dsn string) gorm.Dialector

DialectorFactory 根据 DSN 返回 GORM Dialector

func LookupDialect 

func LookupDialect(driver string) (DialectorFactory, bool)

LookupDialect 查找已注册的 Dialector 工厂

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager 数据库管理器，持有主库与从库连接实例

func NewManager 

func NewManager(cfg *config.Config) *Manager

NewManager 创建数据库管理器

func (*Manager) Close 

func (m *Manager) Close() error

Close 关闭主库与全部从库连接

func (*Manager) FromContext 

func (m *Manager) FromContext(ctx context.Context) *gorm.DB

FromContext 根据上下文选择数据库

func (*Manager) HealthCheck 

func (m *Manager) HealthCheck(ctx context.Context) error

HealthCheck 健康检查，主库不可达时返回错误

func (*Manager) InitDB 

func (m *Manager) InitDB(cfg *config.Config) error

InitDB 初始化数据库连接（带重试机制），驱动由配置决定

func (*Manager) InitDBWithReplicas 

func (m *Manager) InitDBWithReplicas(cfg *config.Config, replicaDSNs []string) error

InitDBWithReplicas 初始化数据库主从连接，驱动由配置决定 replicaDSNs: 从库连接字符串列表（需与主库驱动匹配）

func (*Manager) IsHealthy added in v1.1.0 

func (m *Manager) IsHealthy() bool

IsHealthy 返回主库当前健康状态（#21）。供 readiness/health 探针联动。

func (*Manager) Master 

func (m *Manager) Master() *gorm.DB

Master 返回主库实例

func (*Manager) Open 

func (m *Manager) Open(ctx context.Context) error

Open 打开主库连接

func (*Manager) OpenWithReplicas 

func (m *Manager) OpenWithReplicas(ctx context.Context, replicaDSNs []string) error

OpenWithReplicas 打开主库与从库连接

func (*Manager) Picker 

func (m *Manager) Picker() ReplicaPicker

Picker 返回当前从库选择策略

func (*Manager) Replica 

func (m *Manager) Replica() *gorm.DB

Replica 按策略选择一个从库；无从库时返回主库。 #21：启用探活后，自动过滤不健康的从库；全不健康时回退到全部从库（仍可服务）。

func (*Manager) Replicas 

func (m *Manager) Replicas() []*gorm.DB

Replicas 返回所有从库实例

func (*Manager) SetPicker 

func (m *Manager) SetPicker(p ReplicaPicker)

SetPicker 设置从库选择策略

func (*Manager) StartProbing added in v1.1.0 

func (m *Manager) StartProbing(ctx context.Context)

StartProbing 启动主库与从库的健康探活后台循环（#21）。 阻塞调用方，应通过 App.Go 在独立 goroutine 运行；ctx 取消时退出。 周期 ping 主库，连续失败达阈值后标记不健康（IsHealthy=false）； 同时 ping 各从库，失败则从读流量剔除，恢复后自动重新纳入。

type RandomPicker 

type RandomPicker struct{}

RandomPicker 随机选择从库

func (*RandomPicker) Pick 

func (p *RandomPicker) Pick(replicas []*gorm.DB) *gorm.DB

Pick 随机选择一个从库

type RedisManager added in v1.1.0 

type RedisManager struct {
	// contains filtered or unexported fields
}

RedisManager Redis 连接管理器（#10）。照 database.Manager 模式： 实例化 + DefaultRedis 全局默认 + 包级 facade 代理，支持多实例与测试注入。

func NewRedisManager added in v1.1.0 

func NewRedisManager() *RedisManager

NewRedisManager 创建 Redis 管理器实例。

func (*RedisManager) Client added in v1.1.0 

func (m *RedisManager) Client() *redis.Client

Client 返回当前 Redis 客户端（未初始化返回 nil）。

func (*RedisManager) Close added in v1.1.0 

func (m *RedisManager) Close() error

Close 关闭 Redis 连接。

func (*RedisManager) HealthCheck added in v1.1.0 

func (m *RedisManager) HealthCheck(ctx context.Context) error

HealthCheck Redis 健康检查。

func (*RedisManager) Init added in v1.1.0 

func (m *RedisManager) Init(cfg *config.Config) error

Init 初始化 Redis 连接并 ping 验证。

type ReplicaPicker 

type ReplicaPicker interface {
	Pick(replicas []*gorm.DB) *gorm.DB
}

ReplicaPicker 从库选择策略

type RoundRobinPicker 

type RoundRobinPicker struct {
	// contains filtered or unexported fields
}

RoundRobinPicker 轮询选择从库

func (*RoundRobinPicker) Pick 

func (p *RoundRobinPicker) Pick(replicas []*gorm.DB) *gorm.DB

Pick 轮询选择一个从库

Source Files

View all Source files

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.