# 官方 MySQL 适配器

本包可选，使用 `database/sql` 和 `go-sql-driver/mysql`，复用框架的唯一连接池、Ping、事务与健康检查。不自动建库/迁移、不重试写操作，也不强制某个 MySQL 版本或业务表。

项目使用 GORM 时，在 svc.Init 中调用 [gormx.MySQL](../gormx/README.md) 即可复用这个池、TLS 和清理流程。

生成项目选择 `--database mysql` 即接入：

```sh
go-omni new --database mysql --module example.com/billing ./billing
```

`etc/config.yaml` 使用结构化配置，环境覆盖优先：

```yaml
database:
  host: db.example.com
  port: 3306
  user: app
  database: billing
  parseTime: true
  location: UTC
  charset: utf8mb4
  collation: utf8mb4_bin
  connectTimeout: 5s
  readTimeout: 5s
  writeTimeout: 5s
  tls:
    mode: required
    caFile: /etc/certs/database-ca.pem
    serverName: db.example.com
  pool:
    maxOpenConns: 20
    maxIdleConns: 5
    connMaxLifetime: 30m
    connMaxIdleTime: 5m
    pingTimeout: 5s
```

通过 `GO_OMNI_DB_PASSWORD` 传密码；还有 HOST、PORT、USER、DATABASE、TLS_CA_FILE、TLS_CERT_FILE、TLS_KEY_FILE、POOL_MAX_OPEN_CONNS 等。业务也可自定义 env 标签。新生成服务不再读取 DSN；独立数据库迁移 CLI 和手写 `database.Open/OpenConnector` 的原接口保留。

默认启用 TLS 并校验系统信任链与主机名；私有 CA 用 caFile，双向 TLS 额外设置 certFile/keyFile。只有明确设置 `tls.mode: disabled` 才使用明文。Unix socket 用 socket，若在 socket 上使用 TLS，必须提供 serverName。不会注册全局 TLS 配置或全局驱动 Logger。

手写入口：

```go
cfg := mysqladapter.DefaultConfig()
// 从项目配置覆盖 cfg；不要打印含密码的完整配置。
db, err := mysqladapter.Open(ctx, cfg, mysqladapter.WithLogger(logger))
if err != nil { return err }
defer db.Close()
// db.DB 是标准 *sql.DB；也可用框架 Health、InTx 等方法。
```

生成项目的 `internal/svc/databaseOptions.go` 是保留的项目扩展位置：

```go
func (c *ServiceContext) DatabaseOptions() []mysqladapter.Option {
    return []mysqladapter.Option{
        mysqladapter.WithStartupCheck(func(ctx context.Context, db *database.DB) error {
            return checkProjectSchema(ctx, db)
        }),
    }
}
```

检查在 Ping 后运行，共享启动时限；失败或 panic 会关闭新连接池。版本/表结构检查放在这些回调中，不放到框架。回调必须响应 context，并且不能自行关闭借用的 db。依赖尚未完成整体初始化时不要把连接池发布到外部。

`WithDriverConfig(func(*mysql.Config) error)` 支持高级拨号、驱动参数等，配置在回调后克隆；这是项目明确选择的底层扩展。`NewConnector` 返回标准 driver.Connector，供已有基础设施使用；它不接受启动检查选项。任意驱动仍可用核心 `database.OpenConnector`。

错误有安全摘要，errors.Is/As 保留 TLS/驱动/项目检查的原因。配置验证不读证书、不连接数据库；Open 才读取证书、创建池并握手。不要自行打印原始配置或展开可能包含内部信息的 driver 字段给用户。