# dbmgr

**Repository Path**: unignss/dbmgr

## Basic Information

- **Project Name**: dbmgr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-21
- **Last Updated**: 2026-02-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dbmgr

`dbmgr` 是一个轻量级且强大的 Go 语言数据库管理库。它旨在简化多数据库环境下的配置管理、连接池控制以及事务操作。

## 核心特性

- **🚀 自动生命周期管理**：基于引用计数的连接池，当连接不再被使用且配置过期时，自动关闭物理连接。
- **🔄 无感配置更新**：支持在线更新数据库配置（Register/Unregister），库会自动处理现有连接的过期与重连逻辑。
- **🏗️ DBHelper 操作助手**：提供简洁的操作接口，支持链式事务控制和自动回收。
- **🛡️ 线程安全**：核心层（ConfigManager/DBPool）完全并发安全，支持高并发场景。
- **🧩 高度可扩展**：允许注入自定义的 `NewDB` 创建逻辑，轻松集成 Mock 或特定驱动设置。

## 安装

```bash
go get gitee.com/unignss/dbmgr
```

## 快速上手

### 1. 注册配置

在应用启动时注册数据库配置：

```go
import "gitee.com/unignss/dbmgr"

func init() {
    dbmgr.Register("main", &dbmgr.DBConfig{
        Type:   dbmgr.DBTypeMySQL,
        Driver: "mysql",
        DSN:    "user:password@tcp(127.0.0.1:3306)/dbname?parseTime=true",
    })
}
```

### 2. 使用 DBHelper 进行普通查询

`DBHelper` 是无状态的，建议在每次操作时创建。

```go
func GetUserName(id int) (string, error) {
    helper := dbmgr.NewDBHelper("main")
    defer helper.Close() // 必须 Close 以归还连接到池中

    var name string
    err := helper.QueryRow("SELECT name FROM users WHERE id = ?", id).Scan(&name)
    return name, err
}
```

### 3. 事务处理

`DBHelper` 提供了极致简化的事务管理接口：

```go
func UpdateScore(userID int, score int) error {
    helper := dbmgr.NewDBHelper("main")
    defer helper.Close()

    if err := helper.BeginTrans(); err != nil {
        return err
    }

    // 执行多次操作
    _, err := helper.Execute("UPDATE users SET score = ? WHERE id = ?", score, userID)
    if err != nil {
        return err // AutoDoneTrans 会感知最后一次错误
    }

    // 根据最后是否有错误自动 Commit 或 Rollback
    return helper.AutoDoneTrans()
}
```

## 进阶与架构

### 连接过期机制
`dbmgr` 采用 **主动通知 + 被动检测** 的结合方案：
1. **主动通知**：当调用 `Register` 更新配置时，连接池会立刻标记对应的旧连接。如果该连接当前空闲，会立刻关闭。
2. **被动检测**：如果连接正在被 `DBHelper` 使用，`DBHelper` 在下次操作前会通过 `isExpired()` 发现过期，并在操作结束后自动触发重连流程。

### 隐藏内部实现
本库采用了精简的 API 设计。底层如 `configManager`、`dbPool` 等类型均为包内私有，防止用户意外破坏内部状态。开发者仅需关注：
- `Register` / `Unregister`
- `NewDBHelper`
- `DBConfig` 结构

## License

MIT License