db

func CreateDB ¶

func CreateDB(options Options) error

CreateDB 根据 URL 中的 scheme 自动创建对应类型的数据库连接并注册到全局 dbm。 这是一个统一入口函数，内部使用 strings.Cut 以 "://" 为分隔符将 Options.URL 拆分为 Schema（驱动类型）和 DSN（数据源名称），然后按 Schema（大小写无关，通过 strings.ToLower） 分别调用 NewMySQL、NewSQLite 或 NewClickHouse。

CreateDB automatically creates and registers a database connection based on the scheme parsed from Options.URL. It uses strings.Cut to split URL at "://" into Schema (driver type) and DSN (data source name), then dispatches (case-insensitive via strings.ToLower) to NewMySQL, NewSQLite, or NewClickHouse.

支持的 Schema / Supported Schema values:

• "mysql" → NewMySQL
• "sqlite" → NewSQLite
• "clickhouse" → NewClickHouse

返回值 / Returns:

• error: 若 Schema 不在支持列表中，返回 "unknown database schema: ..." 错误； 若底层 NewXxx 注册失败也会返回相应 error。 Returns "unknown database schema: ..." if Schema is not supported; also propagates errors from underlying NewXxx calls.

参数 / Parameters:

• options: Options 结构体，必须设置 URL（格式 scheme://dsn）和 Name。 Schema 由函数内部通过 strings.Cut 从 URL 自动解析，无需外部设置。 Options struct; URL (scheme://dsn) and Name are required. Schema is auto-parsed from URL via strings.Cut; no need to set externally.

示例 / Example:

db.CreateDB(db.Options{Name: "default", URL: "mysql://user:pass@tcp(host:3306)/mydb?charset=utf8mb4"})
db.CreateDB(db.Options{Name: "local", URL: "sqlite://:memory:"})
db.CreateDB(db.Options{Name: "analytics", URL: "clickhouse://user:pass@localhost:9000/mydb"})

func GetDB ¶

func GetDB(ctx context.Context, name string) *gorm.DB

GetDB 按名称获取 GORM 实例，懒连接 + 带 context。业务层主要入口。 Gets GORM instance by name with lazy connect and context. Main entry for business layer.

func Load ¶

func Load(db *db) *db

Load 将 DB 实例注册到全局 dbm。由 NewMySQL/NewSQLite 内部调用。 Registers DB instance into dbm. Called internally by NewMySQL/NewSQLite.

func NewClickHouse ¶

func NewClickHouse(options Options) error

NewClickHouse 创建 ClickHouse 数据库连接并注册到全局 dbm。 Creates ClickHouse connection and registers it to global dbm.

参数 / Parameters:

• options: Options 结构体，需设置 Name 和 URL 字段。 若通过 CreateDB 调用，URL 为 DSN 部分（不含 scheme "clickhouse://"），Schema 已被拆分。 若直接调用，URL 应为纯 ClickHouse DSN。 Options struct; Name and URL are required. When called via CreateDB, URL is the DSN part (without "clickhouse://" scheme). When called directly, URL should be a raw ClickHouse DSN.

返回值 / Returns:

• error: Name 为空或注册失败时返回错误 / Error if Name is empty or registration fails

行为 / Behavior:

• 内部调用 setup(options).open(clickhouse.Open)；setup 通过 LoadOptions 与 newOptions 合并非零字段与默认值 Calls setup(options).open(clickhouse.Open); setup merges non-zero fields with defaults via LoadOptions and newOptions
• 连接为懒加载：首次调用 db.GetDB(ctx, name) 时才真正建连 Lazy connect: connects on first db.GetDB(ctx, name) call
• ClickHouse 不能跳过默认事务，否则无法插入数据（在 OpenDB 中处理） ClickHouse requires default transaction for inserts (handled in OpenDB)

示例 / Example:

// 通过 CreateDB 统一入口（推荐）/ Via CreateDB (recommended)
db.CreateDB(db.Options{Name: "analytics", URL: "clickhouse://user:pass@localhost:9000/mydb"})

// 直接调用（URL 为纯 DSN，不含 scheme）/ Direct call (URL is raw DSN, no scheme)
db.NewClickHouse(db.Options{Name: "clickhouse", URL: "user:pass@localhost:9000/mydb"})
gormDB := db.GetDB(ctx, "clickhouse")

func NewMySQL ¶

func NewMySQL(options Options) error

NewMySQL 创建 MySQL 数据库连接并注册到全局 dbm。 Creates MySQL connection and registers it to global dbm.

参数 / Parameters:

• options: Options 结构体，需设置 Name 和 URL 字段。 若通过 CreateDB 调用，URL 为 DSN 部分（不含 scheme "mysql://"），Schema 已被拆分。 若直接调用，URL 应为纯 MySQL DSN（如 "user:pass@tcp(host:3306)/db?charset=utf8mb4"）。 Options struct; Name and URL are required. When called via CreateDB, URL is the DSN part (without "mysql://" scheme). When called directly, URL should be a raw MySQL DSN.

返回值 / Returns:

• error: Name 为空或注册失败时返回错误 / Error if Name is empty or registration fails

行为 / Behavior:

• 内部调用 setup(options).open(mysql.Open)；setup 通过 LoadOptions 与 newOptions 合并非零字段与默认值 Calls setup(options).open(mysql.Open); setup merges non-zero fields with defaults via LoadOptions and newOptions
• 连接为懒加载：首次调用 db.GetDB(ctx, name) 时才真正建连 Lazy connect: connects on first db.GetDB(ctx, name) call
• 连接失败时每 10 秒自动重试，Logger 输出重试日志 Retries every 10s on connect failure; Logger logs retries

示例 / Example:

// 通过 CreateDB 统一入口（推荐）/ Via CreateDB (recommended)
db.CreateDB(db.Options{Name: "default", URL: "mysql://user:pass@tcp(127.0.0.1:3306)/mydb?charset=utf8mb4&parseTime=True&loc=Local"})

// 直接调用（URL 为纯 DSN，不含 scheme）/ Direct call (URL is raw DSN, no scheme)
db.NewMySQL(db.Options{Name: "default", URL: "user:pass@tcp(127.0.0.1:3306)/mydb?charset=utf8mb4&parseTime=True&loc=Local"})
gormDB := db.GetDB(ctx, "default")

func NewSQLite ¶

func NewSQLite(options Options) error

NewSQLite 创建 SQLite 数据库连接并注册到全局 dbm。 Creates SQLite connection and registers it to global dbm.

参数 / Parameters:

• options: Options 结构体，需设置 Name 和 URL 字段。 若通过 CreateDB 调用，URL 为 DSN 部分（不含 scheme "sqlite://"），Schema 已被拆分。 若直接调用，URL 应为纯 SQLite DSN。 Options struct; Name and URL are required. When called via CreateDB, URL is the DSN part (without "sqlite://" scheme). When called directly, URL should be a raw SQLite DSN.

URL（DSN）格式 / URL (DSN) format:

• ":memory:" - 内存数据库，单测常用 In-memory database, common for unit tests
• "/path/to/file.db" - 文件数据库，开发/轻量部署 File-based database, for dev or light deployment

返回值 / Returns:

• error: Name 为空或注册失败时返回错误 / Error if Name is empty or registration fails

行为 / Behavior:

• 内部调用 setup(options).open(sqlite.Open)；setup 通过 LoadOptions 与 newOptions 合并非零字段与默认值 Calls setup(options).open(sqlite.Open); setup merges non-zero fields with defaults via LoadOptions and newOptions
• 连接为懒加载：首次 db.GetDB(ctx, name) 时才建连 Lazy connect: connects on first db.GetDB(ctx, name) call

示例 / Example:

// 通过 CreateDB 统一入口（推荐）/ Via CreateDB (recommended)
db.CreateDB(db.Options{Name: "default", URL: "sqlite://:memory:"})

// 直接调用（URL 为纯 DSN，不含 scheme）/ Direct call (URL is raw DSN, no scheme)
db.NewSQLite(db.Options{Name: "default", URL: ":memory:"})
db.NewSQLite(db.Options{Name: "local", URL: "/data/iot-mesh.db"})

func OpenClickHouse ¶

func OpenClickHouse(ctx context.Context, options Options) (*gorm.DB, error)

OpenClickHouse 立即打开 ClickHouse 连接并返回 *gorm.DB，不向全局 dbm 注册。 适用于单次任务、迁移脚本等不需要 GetDB 按名取实例的场景。

Opens ClickHouse immediately and returns *gorm.DB without registering to global dbm. Use for one-off jobs, migrations, etc., when name-based GetDB is not needed.

func OpenMySQL ¶

func OpenMySQL(ctx context.Context, options Options) (*gorm.DB, error)

OpenMySQL 立即打开 MySQL 连接并返回 *gorm.DB，不向全局 dbm 注册。 适用于单次任务、迁移脚本等不需要 GetDB 按名取实例的场景。

Opens MySQL immediately and returns *gorm.DB without registering to global dbm. Use for one-off jobs, migrations, etc., when name-based GetDB is not needed.

func OpenSQLite ¶

func OpenSQLite(ctx context.Context, options Options) (*gorm.DB, error)

OpenSQLite 立即打开 SQLite 连接并返回 *gorm.DB，不向全局 dbm 注册。 适用于单次任务、迁移脚本、本地工具等不需要 GetDB 按名取实例的场景。

Opens SQLite immediately and returns *gorm.DB without registering to global dbm. Use for one-off jobs, migrations, local tools, etc., when name-based GetDB is not needed.

func Query ¶

func Query(ctx context.Context, name string, query string, args ...any) ([]map[string]any, error)

Query 便捷查询函数，基于 StreamBatch 实现，内部以 100 行为一批， 将所有结果收集到 []map[string]any 后一次性返回。 适合结果集较小、不需要流式处理的普通查询场景。

results, err := db.Query(ctx, "default", "SELECT id, name FROM users WHERE status = ?", "active")

func Stream ¶

func Stream(ctx context.Context, name string, query string, args []any, handle func(index int64, row []any) error) (int64, error)

Stream 逐行流式查询，对每一行调用 handle 回调。 使用原生 database/sql 接口绕过 GORM，每行数据根据列的 Go 类型自动格式转换。

参数:

• ctx: 上下文，支持超时与取消
• name: 数据库实例名（已通过 NewMySQL/NewSQLite 等注册）
• query: SQL 查询语句
• args: 参数化查询的参数（防止 SQL 注入）
• handle: 回调函数，index 为当前行号（从 1 开始），row 为该行各列的值

返回处理的总行数和错误。

cnt, err := db.Stream(ctx, "default", "SELECT id, name FROM users WHERE age > ?", []any{18},
    func(index int64, row []any) error {
        fmt.Printf("Row %d: %v\n", index, row)
        return nil
    })

func StreamBatch ¶

func StreamBatch(ctx context.Context, name, query string, args []any, batch int, fun func(rows []map[string]any) error) (int64, error)

StreamBatch 分批流式查询，每积累 batch 行后调用一次 fun 回调。 结果组织为 []map[string]any（列名→值），适合批量插入、批量发送等场景。 最后不足 batch 的剩余行也会触发一次回调。

参数:

• ctx: 上下文，支持超时与取消
• name: 数据库实例名
• query: SQL 查询语句
• args: 参数化查询的参数
• batch: 每批处理的行数
• fun: 批处理回调函数，接收当前批次的所有行数据

返回处理的总行数和错误。

cnt, err := db.StreamBatch(ctx, "default", "SELECT * FROM logs", nil, 500,
    func(rows []map[string]any) error {
        return bulkInsert(rows)
    })