database

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 7 Imported by: 0

README

database 数据库访问包

基于 gorm 的数据库接入封装:核心包提供统一接口与全局连接管理,MySQL / PostgreSQL / SQLite 三种驱动各自独立成子包,按需引入,未使用的驱动不会进入业务项目的依赖树。

特性

  • 驱动按需引入:核心包零驱动依赖,业务项目 import 哪个驱动子包才拉取哪个驱动(Go 1.17+ 模块图裁剪)
  • 统一接口:所有驱动实现 database.Database 接口(DSN() + Connect()),切换数据库只需换 import 与配置
  • 全局连接管理:连接成功后注入全局,任意位置通过 DB() 获取 gorm 句柄
  • 连接池标准化:统一的 DatabasePool 连接池配置,随连接自动生效
  • zap 日志对接:gorm 的 SQL 日志(慢查询、错误)经 zap 输出,级别可配置

目录结构

database/
├── init.go      核心包: Database 接口、DatabasePool、全局连接管理
├── zap_log.go   gorm 日志器, 输出对接 zap
├── mysql/       MySQL 驱动适配器
├── postgres/    PostgreSQL 驱动适配器
└── sqlite/      SQLite 驱动适配器(纯 Go 实现, 无需 cgo)

快速开始

以 MySQL 为例(其余驱动仅 import 路径与配置字段不同):

package main

import (
	"gitee.com/usmos/basic-go/database"
	"gitee.com/usmos/basic-go/database/mysql"
)

func main() {
	db := &mysql.MySQL{
		LoggerLevel: "warn",
		Host:        "127.0.0.1",
		Port:        3306,
		User:        "root",
		Password:    "123456",
		DB:          "note_mq",
		Charset:     "utf8mb4",
	}

	// 连接(含连接池配置与 Ping 探活), 成功后注入全局
	if err := db.Connect(); err != nil {
		panic(err)
	}
	defer database.Close()

	// 任意位置获取 gorm 句柄
	database.DB().Create(&User{Name: "note"})

	// 自动迁移表结构
	database.AutoMigrate(&User{})
}

与 config 配合,从配置文件加载:

type Root struct {
	Database mysql.MySQL `yaml:"database"`
}

var c Root
cfg, _ := config.New("yaml", config.WithFile("config.yaml"))
_ = cfg.UnmarshalWithDefault(&c)
_ = c.Database.Connect()

对应配置文件:

database:
  logger_level: warn      # silent, error, warn, info
  host: 127.0.0.1
  port: 3306
  user: root
  password: "123456"
  db: note_mq
  charset: utf8mb4
  conn_max_idle_time: 5m  # 连接最大空闲时间
  conn_max_lifetime: 30m  # 连接最大生命周期
  max_idle_conns: 10      # 最大空闲连接数
  max_open_conns: 100     # 最大打开连接数

配置字段

通用连接池(DatabasePool,各驱动内嵌,见 init.go):

字段 类型 说明
conn_max_idle_time time.Duration 连接最大空闲时间(0 = 不限制,如 5m)
conn_max_lifetime time.Duration 连接最大生命周期(0 = 不限制,如 30m)
max_idle_conns int 连接池最大空闲连接数(0 = database/sql 默认 2)
max_open_conns int 连接池最大打开连接数(0 = 不限制)

各驱动专有字段(各驱动均还含 logger_level——gorm SQL 日志级别:silent / error / warn / info,与上述连接池字段):

驱动 包 专有字段
MySQL database/mysql host port user password db charset
PostgreSQL database/postgres host port user password db ssl_mode time_zone
SQLite database/sqlite path(:memory: 为内存库)

字段均带 yaml / toml / json / mapstructure 标签,可配 default 标签配合 config 的 UnmarshalWithDefault 使用。

接口总览

核心包(init.go):

方法 说明
Database 接口 DSN() string + Connect() error,各驱动的统一抽象
DB() 获取全局 *gorm.DB 句柄(未连接时为 nil)
SetDB(db) 注入连接(各驱动 Connect() 内部自动调用)
AutoMigrate(models...) 自动迁移表结构
Close() 关闭连接并清空全局句柄,可重复调用

核心包(zap_log.go):

方法 说明
NewLogger(level) 创建对接 zap 的 gorm 日志器;慢 SQL(>200ms)Warn,错误 SQL Error

各驱动子包(以 mysql/mysql.go 为例):

方法 说明
DSN() 生成数据库连接字符串
Connect() 建连 → 应用连接池配置 → Ping 探活 → 注入全局

按需引入机制

驱动适配器与核心包分属不同 Go 包,依赖随 import 精确传播:

import "gitee.com/usmos/basic-go/database/mysql" // 仅此路径引入 gorm.io/driver/mysql
  • 业务项目只 import 用到的驱动子包,未使用驱动的模块不进入其 go.mod、不会被下载、不参与编译
  • 核心包 database 可独立使用(配合 SetDB 手动注入任意 gorm 连接)
  • SQLite 采用 github.com/glebarez/sqlite 纯 Go 驱动,无 cgo 依赖,交叉编译友好

注意事项

  • SQLite 单写者模型:高并发写入场景建议 MaxOpenConns: 1,避免 database is locked
  • PostgreSQL SSLMode:本地开发通常 disable,生产环境建议 require 及以上
  • 全局单连接:SetDB 全局仅保存一个连接,多数据源场景请直接使用 gorm 多实例,不走本包全局方法
  • 日志依赖:gorm 日志经 zap.L() 输出,业务项目需完成 zap 初始化(或接受默认输出)

Documentation

Overview

Package database 提供基于 gorm 的数据库接入封装。

核心包定义统一接口与全局连接管理: 所有驱动实现 Database 接口(DSN + Connect), 连接成功后注入全局, 任意位置通过 DB() 获取 gorm 句柄, AutoMigrate 自动迁移表结构; MySQL / PostgreSQL / SQLite 三种驱动各自独立成子包(mysql/postgres/sqlite), 业务项目仅 import 用到的驱动子包, 未使用的驱动不会进入依赖树。

使用示例(以 MySQL 为例, 其余驱动仅 import 路径与配置字段不同):

db := &mysql.MySQL{
	Host:     "127.0.0.1",
	Port:     3306,
	User:     "root",
	Password: "123456",
	DB:       "note",
	Charset:  "utf8mb4",
}
if err := db.Connect(); err != nil { // 建连(含连接池配置与 Ping 探活), 成功后注入全局
	panic(err)
}
defer database.Close()

database.DB().Create(&User{Name: "note"}) // 任意位置获取 gorm 句柄
_ = database.AutoMigrate(&User{})         // 自动迁移表结构

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AutoMigrate

func AutoMigrate(dist ...any) error

AutoMigrate 自动迁移数据库表

func Close

func Close() error

Close 关闭数据库连接

func DB

func DB() *gorm.DB

DB 获取数据库连接

func NewLogger

func NewLogger(level string) logger.Interface

NewLogger 创建 gorm 日志器, 输出对接 zap, 供各驱动子包使用

func SetDB

func SetDB(d *gorm.DB)

SetDB 设置数据库连接

Types

type Database

type Database interface {
	DSN() string    // 数据库连接字符串
	Connect() error // 连接数据库
}

Database 数据库接口, 定义数据库连接和关闭方法以及数据库使用方法 统一数据库操作接口, 方便切换数据库驱动

type DatabasePool

type DatabasePool struct {
	ConnMaxIdleTime time.Duration `yaml:"conn_max_idle_time" toml:"conn_max_idle_time" json:"conn_max_idle_time" mapstructure:"conn_max_idle_time"` // 数据库连接最大空闲时间
	ConnMaxLifetime time.Duration `yaml:"conn_max_lifetime" toml:"conn_max_lifetime" json:"conn_max_lifetime" mapstructure:"conn_max_lifetime"`     // 数据库连接最大生命周期
	MaxIdleConns    int           `yaml:"max_idle_conns" toml:"max_idle_conns" json:"max_idle_conns" mapstructure:"max_idle_conns"`                 // 数据库连接池最大空闲连接数
	MaxOpenConns    int           `yaml:"max_open_conns" toml:"max_open_conns" json:"max_open_conns" mapstructure:"max_open_conns"`                 // 数据库连接池最大打开连接数
}

DatabasePool 数据库连接池

Directories

Path Synopsis
Package mysql 提供 MySQL 数据库驱动接入。
Package mysql 提供 MySQL 数据库驱动接入。
Package postgres 提供 PostgreSQL 数据库驱动接入。
Package postgres 提供 PostgreSQL 数据库驱动接入。
Package sqlite 提供 SQLite 数据库驱动接入(纯 Go 实现, 无需 cgo)。
Package sqlite 提供 SQLite 数据库驱动接入(纯 Go 实现, 无需 cgo)。

Jump to

Keyboard shortcuts

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