go-omni/database/README.md

database

database 包提供基于标准库 database/sql 的连接池生命周期，不绑定 ORM 或驱动：

• Config / ConfigFromEnv：连接池参数和 GO_OMNI_DB_* 环境变量。
• Open：创建连接池、设置连接上限并在返回前执行 PingContext。
• Health：用于就绪检查，等待连接和 Ping 均受 PingTimeout 限制。
• InTx：统一事务提交和回滚；工作函数返回错误或 panic 时回滚。
• Close：由嵌入的 *sql.DB 提供，应用退出时显式调用。

框架不导入 MySQL、PostgreSQL 等具体驱动。应用负责注册驱动：

import (
	"context"
	_ "github.com/go-sql-driver/mysql"
	"git.yuntuo.hk/k2safe/go-omni/database"
)

cfg, err := database.ConfigFromEnv("GO_OMNI_DB_")
if err != nil {
	return err
}
db, err := database.Open(context.Background(), cfg)
if err != nil {
	return err
}
defer db.Close()

连接池相关环境变量：

GO_OMNI_DB_DRIVER=mysql
GO_OMNI_DB_DSN=user:password@tcp(127.0.0.1:3306)/app?parseTime=true
GO_OMNI_DB_MAX_OPEN_CONNS=10
GO_OMNI_DB_MAX_IDLE_CONNS=5
GO_OMNI_DB_CONN_MAX_LIFETIME=30m
GO_OMNI_DB_CONN_MAX_IDLE_TIME=5m
GO_OMNI_DB_PING_TIMEOUT=5s

DSN 必填，驱动默认是 mysql。数据库建库、迁移、表结构和具体 Repository 属于业务项目或可选模块，不会被核心包自动执行。

MaxIdleConns=0 会禁用空闲连接。初始化 Ping 失败会关闭已创建的连接池。

go-omni new --database mysql 会生成项目自己的 MySQL Repository、ServiceContext、 数据库就绪探针和 schema.sql。核心包不需要知道业务表结构。

真实数据库验收（需要本地 Docker）：

python3 scripts/verifyDatabase.py --version v0.2.0

脚本仅操作本次创建的独立容器与数据库，验证 HTTP CRUD、服务重启持久化、事务提交与 错误/panic/取消回滚、连接池关闭、缺少表结构时启动失败，以及停库后的 readiness 503 和恢复后的 200。 结束时清理容器、匿名数据卷和临时项目。常规 go test ./... 不依赖 Docker。

项目配置叠加

database.ApplyEnv(cfg, prefix) 在已有文件/默认配置上覆盖非空环境变量，保留未覆盖的池参数。 Config 的 JSON/YAML 字段使用 lowerCamelCase，DSN 使用 json:"-"，连接密钥从环境变量加载。 API 脚手架 --database mysql 使用此流程，并要求正的 maxOpenConns，提供数据库 readiness 与幂等清理。 具体表结构、迁移和 Repository 留在业务项目，参考 examples/userService。