database

package
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 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 (
	// RedisClient 全局 Redis 客户端
	RedisClient *redis.Client
)

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 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 SetReplicaPicker 

func SetReplicaPicker(p ReplicaPicker)

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

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) 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 按策略选择一个从库；无从库时返回主库

func (*Manager) Replicas 

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

Replicas 返回所有从库实例

func (*Manager) SetPicker 

func (m *Manager) SetPicker(p ReplicaPicker)

SetPicker 设置从库选择策略

type RandomPicker 

type RandomPicker struct{}

RandomPicker 随机选择从库

func (*RandomPicker) Pick 

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

Pick 随机选择一个从库

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.