@go/db
Maintainer Statement: 本项目由 AI 维护。代码源自 github.com/ssgo/db 的重构，支持内存安全防护、读写分离及泛型优化。
🎯 设计哲学
@go/db 是一个极致精简、意图优先的数据库抽象层。它不试图取代 SQL，而是通过智能结果绑定与 SQL 自动化生成，消除数据库操作中的样板代码。
- 智能绑定：根据结果容器类型（Struct/Map/Slice/BaseType）自动适配查询逻辑，无需手动 Scan。
- 内存防御：集成
go/safe，数据库密码在内存中加密存储，使用时物理擦除。 - 读写分离：内置连接池管理，支持配置多个只读节点实现自动负载均衡。
- 驱动透明：统一 MySQL、PostgreSQL (pgx) 与 SQLite 的 API 差异。
📦 安装
go get apigo.cc/go/db
💡 快速开始
import "apigo.cc/go/db"
import _ "apigo.cc/go/db/mysql" // 引入驱动
// 初始化连接
d := db.GetDB("mysql://user:pass@host:3306/dbname", nil)
// 1. 查询全部结果到 Struct 切片
var users []User
d.Query("SELECT * FROM users").To(&users)
// 2. 自动化插入
d.Insert("users", User{Name: "Star", Active: true})
// 3. 事务操作
tx := d.Begin()
tx.Exec("UPDATE balance SET amount = amount - 10 WHERE id = ?", 1)
tx.Commit()
🛠 API 指南
核心对象
GetDB(setting string, logger *log.Logger) *DB: 通过 DSN 或配置名获取数据库实例。DB.Insert/Replace/Update/Delete: 自动生成 SQL 并执行，支持 Struct 与 Map。QueryResult.To(target any): 将查询结果深度映射到目标容器。QueryResult.MapResults() []map[string]any: 快捷获取通用结果集。
结果容器适配规则
| 容器类型 | 行为 |
|---|---|
[]Struct |
返回所有行，按字段名自动映射 |
Struct |
返回第一行，按字段名自动映射 |
[]map[string]any |
返回所有行，保留原始字段名 |
[]BaseType |
返回所有行，仅取第一列 |
BaseType |
返回第一行第一列 |
安全与高级特性
SetEncryptKeys(key, iv []byte): 配置全局敏感数据加密密钥。- 读写分离: 在 DSN 中配置
host1,host2,host3，首个为主库，其余为随机只读库。 - SQLite 时间修复: 自动处理 SQLite 毫秒级
DATETIME格式与标准time.Time的转换。
🧪 验证状态
已通过 SQLite 集成测试。详见：TEST.md