tdb

package
v0.0.0-...-8ccda10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	LockForUpdate           = "FOR UPDATE"
	LockForUpdateNoWait     = "FOR UPDATE NOWAIT"
	LockForUpdateSkipLocked = "FOR UPDATE SKIP LOCKED"
	LockShare               = "FOR SHARE"
	LockInShareMode         = "LOCK IN SHARE MODE" // MySQL 旧式共享锁
)

常用的悲观锁表达式，可直接传给 Lock()。

View Source 
const ServiceName = "database"

ServiceName 是数据库生命周期服务的稳定名称。

Variables

View Source 
var (
	// ErrReadOnly 表示在只读模式实例上尝试写操作。
	ErrReadOnly = errors.New("tdb: database is read-only")
	// ErrNoRows 表示查询无结果但要求至少一行。
	ErrNoRows = errors.New("tdb: no rows in result set")
	// ErrInvalidTable 表示无法推断表名且未显式提供。
	ErrInvalidTable = errors.New("tdb: cannot infer table name; pass table explicitly")
	// ErrInvalidValue 表示传入的参数值类型/结构不合法（如 BatchInsert 非切片、
	// ScanList 目标非切片指针等）。
	ErrInvalidValue = errors.New("tdb: invalid value: type or structure not supported")
	// ErrNoWhere 表示无 WHERE 条件尝试整表写操作（需 AllowAll 显式解除）。
	ErrNoWhere = errors.New("tdb: update/delete without WHERE is forbidden; call AllowAll() to confirm")
	// ErrTableNotFound 表示反向工程时表不存在或无列。
	ErrTableNotFound = errors.New("tdb: table not found or has no columns")
	// ErrUnsupportedCapability 表示当前驱动不支持请求的数据库能力。
	ErrUnsupportedCapability = errors.New("tdb: unsupported database capability")
)

tdb 包级错误。

View Source 
var (
	EventBeforeInsert = tevent.New[ModelEventData]("model.before_insert")
	EventAfterInsert  = tevent.New[ModelEventData]("model.after_insert")
	EventBeforeUpdate = tevent.New[ModelEventData]("model.before_update")
	EventAfterUpdate  = tevent.New[ModelEventData]("model.after_update")
	EventBeforeDelete = tevent.New[ModelEventData]("model.before_delete")
	EventAfterDelete  = tevent.New[ModelEventData]("model.after_delete")
	EventBeforeQuery  = tevent.New[ModelEventData]("model.before_query")
	EventAfterQuery   = tevent.New[ModelEventData]("model.after_query")
	EventBeforeSave   = tevent.New[ModelEventData]("model.before_save")
	EventAfterSave    = tevent.New[ModelEventData]("model.after_save")
)

Functions

func Factory 

func Factory[T any](s *Seeder, tableName string, count int, factory func(int) T) error

Factory 使用工厂函数批量生成数据。

func HasTimestampTag 

func HasTimestampTag(rt reflect.Type) (create, update string)

HasTimestampTag 检查结构体的 timestamp tag 配置。

func Load 

func Load[T, R any](db *DB, model *T, relation *Relation[T, R], fieldName string) error

Load 加载单条记录的关联（懒加载）。 fieldName 是 T 结构体中用于存放关联数据的字段名。

func LoadAll 

func LoadAll[T, R any](db *DB, models *[]T, relation *Relation[T, R], fieldName string) error

LoadAll 加载多条记录的关联（懒加载）。 fieldName 是 T 结构体中用于存放关联数据的字段名。

func MakePreloader 

func MakePreloader[T, R any](relation *Relation[T, R]) preloader

MakePreloader 根据关联类型创建对应的 preloader。

func MustRegisterDriver 

func MustRegisterDriver(driver Driver)

MustRegisterDriver 在包初始化期注册驱动，失败时 panic。

func RegisterDialect 

func RegisterDialect(d Dialect)

RegisterDialect 注册自定义方言（驱动作者扩展用）。线程安全。

func RegisterDriver 

func RegisterDriver(driver Driver) error

RegisterDriver 注册统一数据库驱动。重复名称返回错误，避免初始化顺序覆盖实现。

func RegisterMigration 

func RegisterMigration(id string, up, down func(db *DB) error)

RegisterMigration 注册迁移。

func RegisterSchemaDriver 

func RegisterSchemaDriver(dialectName string, driver SchemaDriver)

RegisterSchemaDriver 按方言名注册 SchemaDriver 实现。

func RegisterSchemaDriverByName 

func RegisterSchemaDriverByName(dialectName string, driver SchemaDriver)

RegisterSchemaDriverByName 按方言名注册 SchemaDriver 实现（同 RegisterSchemaDriver）。

func RegisteredDrivers 

func RegisteredDrivers() []string

RegisteredDrivers 返回已注册的 SchemaDriver 方言名列表。

func Seed 

func Seed[T any](s *Seeder, tableName string, items []T) error

Seed 插入种子数据。

Types

type AfterDeleter 

type AfterDeleter interface {
	AfterDelete() error
}

AfterDeleter 在 DELETE 执行成功后调用。

type AfterInserter 

type AfterInserter interface {
	AfterInsert() error
}

AfterInserter 在 INSERT 执行成功后调用。

type AfterQuerier 

type AfterQuerier interface {
	AfterQuery() error
}

AfterQuerier 在 SELECT 查询结果扫描后调用（每行）。

type AfterSaver 

type AfterSaver interface {
	AfterSave() error
}

AfterSaver 在 Save（INSERT or UPDATE）执行成功后调用。

type AfterUpdater 

type AfterUpdater interface {
	AfterUpdate() error
}

AfterUpdater 在 UPDATE 执行成功后调用。

type BeforeDeleter 

type BeforeDeleter interface {
	BeforeDelete() error
}

BeforeDeleter 在 DELETE 执行前调用。

type BeforeInserter 

type BeforeInserter interface {
	BeforeInsert() error
}

BeforeInserter 在 INSERT 执行前调用。

type BeforeQuerier 

type BeforeQuerier interface {
	BeforeQuery() error
}

BeforeQuerier 在 SELECT 查询执行前调用。

type BeforeSaver 

type BeforeSaver interface {
	BeforeSave() error
}

BeforeSaver 在 Save（INSERT or UPDATE）执行前调用，用于自动时间戳等。

type BeforeUpdater 

type BeforeUpdater interface {
	BeforeUpdate() error
}

BeforeUpdater 在 UPDATE 执行前调用。

type Capabilities 

type Capabilities struct {
	Returning             bool
	Upsert                bool
	Savepoint             bool
	LastInsertID          bool
	NamedParameters       bool
	Metadata              bool
	SortingKeyMetadata    bool
	SkippingIndexMetadata bool
}

Capabilities 声明驱动真实支持的 SQL 能力，供 ORM 与生成器选择路径。

func (Capabilities) Supports 

func (c Capabilities) Supports(capability Capability) bool

Supports 判断驱动是否支持指定能力。未知能力始终返回 false。

type Capability 

type Capability string

Capability 是 ORM、元信息与生成器可检查的稳定能力标识。 

const (
	CapabilityReturning             Capability = "returning"
	CapabilityUpsert                Capability = "upsert"
	CapabilitySavepoint             Capability = "savepoint"
	CapabilityLastInsertID          Capability = "last_insert_id"
	CapabilityNamedParameters       Capability = "named_parameters"
	CapabilityMetadata              Capability = "metadata"
	CapabilitySortingKeyMetadata    Capability = "sorting_key_metadata"
	CapabilitySkippingIndexMetadata Capability = "skipping_index_metadata"
)

type CapabilityError 

type CapabilityError struct {
	Driver     string
	Capability Capability
}

CapabilityError 描述哪个驱动缺少哪项能力。

func (*CapabilityError) Error 

func (e *CapabilityError) Error() string

func (*CapabilityError) Unwrap 

func (e *CapabilityError) Unwrap() error

type Column 

type Column struct {
	Name     string // 列名
	Type     string // 数据库原生类型（保留长度、精度等修饰）
	Nullable bool   // 是否允许 NULL
	Key      string // PRI/UNI/MUL，至少保证主键归一化为 PRI
	Comment  string // 列注释
	Default  string // 默认值；无默认值与 NULL 默认值当前均为空字符串
	Extra    string // auto_increment、identity 等驱动特有信息
}

Column 是数据库列的统一元信息。各驱动负责把数据库特有结果归一化到该结构。

func (Column) IsAutoIncrement 

func (c Column) IsAutoIncrement() bool

func (Column) IsPrimary 

func (c Column) IsPrimary() bool

type Config 

type Config struct {
	Driver          string        // 驱动名：mysql/postgres/sqlite/sqlserver
	DSN             string        // data source name（驱动特定格式）
	Dialect         string        // 方言名，缺省取 Driver
	Schema          string        // 默认 schema/库名（反向工程用，mysql=database，postgres=schema）
	Prefix          string        // 数据表前缀，模型解析表名时自动追加
	MaxOpen         int           // 最大打开连接数，<=0 表示不限制
	MaxIdle         int           // 最大空闲连接数，<=0 表示不限制
	ConnMaxLifetime time.Duration // 连接最大存活时间，<=0 表示不限制
	ConnMaxIdleTime time.Duration // 连接最大空闲时间，<=0 表示不限制
	ReadOnly        bool          // 只读模式（禁写，Insert/Update/Delete 直接报错）
	// 读写分离：ReadDSNs 为从库 DSN 列表（可选）。配置后，读操作在从库间轮询，
	// 写操作与主库（DSN）保持一致。为空表示无读写分离（读也走主库）。
	ReadDSNs []string
}

Config 数据库连接配置。驱动名需已在别处 import（如 import _ "github.com/go-sql-driver/mysql"）。

type ConnectionConfig 

type ConnectionConfig struct {
	Type            string        `json:"type"`
	Driver          string        `json:"driver"`
	DSN             string        `json:"dsn"`
	Hostname        string        `json:"hostname"`
	Database        string        `json:"database"`
	Username        string        `json:"username"`
	Password        string        `json:"password"`
	Hostport        string        `json:"hostport"`
	Charset         string        `json:"charset"`
	Prefix          string        `json:"prefix"`
	Schema          string        `json:"schema"`
	MaxOpen         int           `json:"max_open"`
	MaxIdle         int           `json:"max_idle"`
	ConnMaxLifetime time.Duration `json:"conn_max_lifetime"`
	ConnMaxIdleTime time.Duration `json:"conn_max_idle_time"`
	ReadOnly        bool          `json:"read_only"`
}

ConnectionConfig 描述一个命名数据库连接。

type Connector 

type Connector interface {
	Open(Config) (*sql.DB, error)
}

Connector 负责创建 database/sql 连接池。nil Connector 使用 sql.Open 兼容路径。

func SQLConnector 

func SQLConnector(driverName string) Connector

SQLConnector 将框架驱动名映射到实际 database/sql 注册名。 它适用于 mariadb -> mysql、oracle -> godror 等插件别名场景。

type ConnectorFunc 

type ConnectorFunc func(Config) (*sql.DB, error)

func (ConnectorFunc) Open 

func (fn ConnectorFunc) Open(config Config) (*sql.DB, error)

type ConventionConfig 

type ConventionConfig struct {
	Default     string                      `json:"default"`
	Connections map[string]ConnectionConfig `json:"connections"`
}

ConventionConfig 是从约定配置文件中解码的数据库配置。

func ConfigFromTree 

func ConfigFromTree(tree tcfg.Reader) (ConventionConfig, error)

ConfigFromTree 从分层配置树的 database 命名空间解码数据库配置。

func LoadConfig 

func LoadConfig(path string) (ConventionConfig, error)

LoadConfig 读取约定数据库配置。文件不存在表示应用未启用数据库。

func (ConventionConfig) Prefix 

func (c ConventionConfig) Prefix(name string) string

Prefix 返回配置的表前缀，供模型生成器和业务约定使用。

func (ConventionConfig) Resolve 

func (c ConventionConfig) Resolve(names ...string) (Config, error)

Resolve 返回默认或指定名称的底层连接配置。

type DB 

type DB struct {
	// contains filtered or unexported fields
}

DB 是一个数据库句柄，封装 *sql.DB 与方言。 零外部驱动依赖：具体驱动由调用方 import 注册给 database/sql。

func Connection 

func Connection(names ...string) (*DB, error)

Connection 返回默认应用的默认或命名连接。

func ConnectionFor 

func ConnectionFor(ctx context.Context, app *core.App, names ...string) (*DB, error)

ConnectionFor 从指定应用容器解析全局数据库连接。

func ConnectionForApplication 

func ConnectionForApplication(ctx context.Context, app *core.App, application string, names ...string) (*DB, error)

ConnectionForApplication 返回指定业务应用作用域的数据库连接。

func ConnectionForContext 

func ConnectionForContext(ctx *core.Ctx, names ...string) (*DB, error)

ConnectionForContext 返回当前请求所属应用作用域的数据库连接。

func MustConnection 

func MustConnection(names ...string) *DB

MustConnection 返回默认应用连接，失败时 panic。

func MustOpen 

func MustOpen(cfg Config) *DB

MustOpen 同 Open，失败 panic（启动期使用）。

func Open 

func Open(cfg Config) (*DB, error)

Open 打开一个数据库连接（驱动需已注册）。

func (*DB) AutoMigrate 

func (db *DB) AutoMigrate(models ...any) error

AutoMigrate 按模型自动建表/补列（schema 自动对齐）。详见 Schema.AutoMigrate。

func (*DB) BuildReturningClause 

func (db *DB) BuildReturningClause(columns ...string) (ReturningClause, error)

BuildReturningClause 通过当前连接的方言生成 Returning/Output 子句。

func (*DB) BuildUpsertClause 

func (db *DB) BuildUpsertClause(spec UpsertSpec) (string, error)

BuildUpsertClause 通过当前连接的方言生成 Upsert 子句。

func (*DB) Cache 

func (db *DB) Cache() *tcache.Cache

Cache 返回缓存后端。

func (*DB) Capabilities 

func (db *DB) Capabilities() Capabilities

Capabilities 返回当前驱动能力。兼容直连模式返回零值。

func (*DB) Close 

func (db *DB) Close() error

Close 关闭底层连接池（含从库）。

func (*DB) Ctx 

func (db *DB) Ctx(ctx context.Context) *DB

Ctx 返回一个绑定了指定 context 的 DB 副本（不修改原 DB）。 之后的 query/exec 默认使用该 context（用于超时/取消透传）。 注意：仅共享底层连接与配置，副本拥有独立的 ctx 与互斥锁（零值可用）。

func (*DB) Dialect 

func (db *DB) Dialect() Dialect

Dialect 返回方言。

func (*DB) Driver 

func (db *DB) Driver() Driver

Driver 返回统一驱动；兼容 database/sql 直连模式下可能为 nil。

func (*DB) EnableEvents 

func (db *DB) EnableEvents(bus *tevent.Bus)

EnableEvents 在 DB 上启用模型事件（集成 tevent 事件总线）。

用法： 

bus := tevent.NewBus(true)
db.EnableEvents(bus)

tevent.Subscribe(bus, tdb.EventAfterInsert, func(ctx context.Context, data tdb.ModelEventData) error {
    log.Printf("Inserted into %s: %+v", data.Table, data.Model)
    return nil
})

func (*DB) EventBus 

func (db *DB) EventBus() *tevent.Bus

EventBus 返回事件总线。

func (*DB) Exec 

func (db *DB) Exec(query string, args ...any) (sql.Result, error)

Exec 执行原生 SQL（写操作），返回 sql.Result。会经过连接池与读写分离（强制主库）。 这是原生 SQL 逃生舱：绕过 Model 的钩子/事件/软删除过滤，调用方需自行保证 SQL 正确与参数化。

func (*DB) InspectTable 

func (db *DB) InspectTable(table string) (*TableMeta, error)

InspectTable 读取单张表的统一元信息。

func (*DB) Migrator 

func (db *DB) Migrator(dir string) *Migrator

Migrator 创建迁移运行器。 dir 是存放迁移文件的目录。

func (*DB) Query 

func (db *DB) Query(query string, args ...any) (*sql.Rows, error)

Query 执行原生 SQL（读操作），返回 *sql.Rows，调用方负责关闭。 会经过连接池与读写分离（默认从库，DB.Ctx 或 Master 语义不适用，统一走主库读以保证原生查询可控）。

func (*DB) RequireCapability 

func (db *DB) RequireCapability(capability Capability) error

RequireCapability 验证当前驱动支持指定能力。

func (*DB) SQL 

func (db *DB) SQL() *sql.DB

SQL 返回底层 *sql.DB（高级用法逃生舱）。

func (*DB) SchemaTool 

func (db *DB) SchemaTool() *Schema

SchemaTool 从 DB 实例创建 Schema 工具。

func (*DB) Seeder 

func (db *DB) Seeder() *Seeder

Seeder 创建 Seeder 实例。

func (*DB) SetCache 

func (db *DB) SetCache(c *tcache.Cache)

SetCache 设置 ORM 查询缓存后端（可选）。

func (*DB) SetEventBus 

func (db *DB) SetEventBus(bus *tevent.Bus)

SetEventBus 设置模型事件总线（可选）。

func (*DB) SetReadOnly 

func (db *DB) SetReadOnly(ro bool)

SetReadOnly 设置只读模式。

func (*DB) Tables 

func (db *DB) Tables() ([]string, error)

Tables 列举当前 schema 内所有基表名。

func (*DB) Transaction 

func (db *DB) Transaction(ctx context.Context, fn func(tx *Tx) error) error

Transaction 开启一个事务，回调内可读写，返回 error 时自动回滚。 支持嵌套：在回调内再次调用 tx.Transaction(...) 会基于 SAVEPOINT 开启子事务 （方言需支持 CapabilitySavepoint），子事务回滚仅回滚到保存点，不影响外层。 用法： 

err := db.Transaction(context.Background(), func(tx *Tx) error {
    ...
    if err := tx.Transaction(ctx, func(sub *Tx) error { ... }); err != nil {
        return err // 仅回滚子事务
    }
    return nil
})

func (*DB) Tx 

func (db *DB) Tx(fn func(tx *Tx) error) error

Tx 等价于 Transaction(context.Background(), fn)，保留以兼容旧调用。

func (*DB) TxCtx 

func (db *DB) TxCtx(ctx context.Context, fn func(tx *Tx) error) error

TxCtx 等价于 Transaction(ctx, fn)，保留以兼容旧调用。

type Dialect 

type Dialect interface {
	// Name 返回方言名（mysql/postgres/sqlite/sqlserver）。
	Name() string
	// Quote 引用标识符（表名/列名），如 MySQL -> `col`，postgres -> "col"。
	Quote(ident string) string
	// Placeholder 返回第 n 个（从 0 开始）占位符，如 mysql "?"，postgres "$1"。
	Placeholder(n int) string
	// Limit 生成 LIMIT/OFFSET 子句（已含前导空格或空串）。
	Limit(limit, offset int) string
}

Dialect 抽象不同数据库的 SQL 方言差异：标识符引用、占位符风格、LIMIT/OFFSET 语法。

注意：列/表元信息查询（information_schema / PRAGMA / 系统视图）已从 Dialect 剥离， 独立封装为 SchemaDriver（见 schema.go 与各 schema_*.go 文件）。

func DialectFor 

func DialectFor(name string) (Dialect, bool)

DialectFor 查找已注册方言。线程安全。

type DialectDefinition 

type DialectDefinition struct {
	DialectName     string
	QuoteLeft       string
	QuoteRight      string
	PlaceholderFunc func(int) string
	LimitFunc       func(limit, offset int) string
}

DialectDefinition 允许独立驱动声明方言差异，而无需依赖核心内部实现。 nil PlaceholderFunc 使用问号占位符，nil LimitFunc 使用 LIMIT/OFFSET。

func (DialectDefinition) Limit 

func (d DialectDefinition) Limit(limit, offset int) string

func (DialectDefinition) Name 

func (d DialectDefinition) Name() string

func (DialectDefinition) Placeholder 

func (d DialectDefinition) Placeholder(n int) string

func (DialectDefinition) Quote 

func (d DialectDefinition) Quote(ident string) string

type Driver 

type Driver interface {
	Name() string
	Connector() Connector
	Dialect() Dialect
	Metadata() SchemaDriver
	Capabilities() Capabilities
}

Driver 是 ORM、元信息和 CLI 共同依赖的统一数据库驱动协议。

func DriverFor 

func DriverFor(name string) (Driver, bool)

DriverFor 查找统一数据库驱动。

type DriverDefinition 

type DriverDefinition struct {
	DriverName         string
	DriverConnector    Connector
	DriverDialect      Dialect
	MetadataDriver     SchemaDriver
	DriverCapabilities Capabilities
}

DriverDefinition 用组合方式声明驱动，避免同族数据库复制样板实现。

func NewDriver 

func NewDriver(name string, metadata SchemaDriver, capabilities Capabilities) DriverDefinition

NewDriver 使用同名已注册方言组合数据库驱动定义。

func NewDriverFrom 

func NewDriverFrom(name, dialectName string, metadata SchemaDriver, capabilities Capabilities) DriverDefinition

NewDriverFrom 使用基础方言组合兼容数据库驱动，同族数据库无需复制方言实现。

func NewDriverFromWithConnector 

func NewDriverFromWithConnector(name, dialectName string, connector Connector, metadata SchemaDriver, capabilities Capabilities) DriverDefinition

NewDriverFromWithConnector 使用基础方言和实际 database/sql 连接器组合兼容驱动。

func NewDriverWithConnector 

func NewDriverWithConnector(name string, connector Connector, metadata SchemaDriver, capabilities Capabilities) DriverDefinition

NewDriverWithConnector 使用同名方言和显式连接器组合数据库驱动。

func (DriverDefinition) Capabilities 

func (d DriverDefinition) Capabilities() Capabilities

func (DriverDefinition) Connector 

func (d DriverDefinition) Connector() Connector

func (DriverDefinition) Dialect 

func (d DriverDefinition) Dialect() Dialect

func (DriverDefinition) Metadata 

func (d DriverDefinition) Metadata() SchemaDriver

func (DriverDefinition) Name 

func (d DriverDefinition) Name() string

type Index 

type Index struct {
	Name        string
	Columns     []string
	Unique      bool
	Primary     bool
	Kind        IndexKind
	Expression  string
	Type        string
	Granularity uint64
}

Index 是数据库索引与检索键的统一元信息。 Expression 用于无法可靠拆分为列名的函数式键；Type 和 Granularity 用于 ClickHouse 跳数索引。

func QueryIndexes 

func QueryIndexes(db *DB, query string, args ...any) ([]Index, error)

QueryIndexes 执行标准化索引查询并按查询结果顺序聚合复合索引。 query 必须依次返回 index_name、column_name、is_unique、is_primary。

type IndexKind 

type IndexKind string
const (
	IndexKindRegular  IndexKind = "index"
	IndexKindUnique   IndexKind = "unique"
	IndexKindPrimary  IndexKind = "primary"
	IndexKindSorting  IndexKind = "sorting"
	IndexKindSkipping IndexKind = "skipping"
)

type IndexSchemaDriver 

type IndexSchemaDriver interface {
	// Indexes 返回指定表的索引信息。
	Indexes(db *DB, table, schema string) ([]Index, error)
}

IndexSchemaDriver 提供索引元信息。

type LazyCollection 

type LazyCollection[T any] struct {
	// contains filtered or unexported fields
}

LazyCollection 延迟集合——大数据量场景下的游标式遍历。

与 All() 不同，LazyCollection 不会一次性将所有行加载到内存， 而是通过 sql.Rows 逐行读取，支持 for-range 迭代。

用法： 

lazy := model.Lazy()
for lazy.Next() {
    var user User
    if err := lazy.Scan(&user); err != nil {
        break
    }
    // 逐行处理
}

func (*LazyCollection[T]) Chunk 

func (l *LazyCollection[T]) Chunk(chunkSize int, fn func(int, []T) error) error

Chunk 分块处理：每 chunkSize 条记录调用一次回调。

func (*LazyCollection[T]) Close 

func (l *LazyCollection[T]) Close() error

Close 关闭游标（释放数据库连接）。

func (*LazyCollection[T]) Collect 

func (l *LazyCollection[T]) Collect() ([]T, error)

Collect 收集所有行到切片（作用等同 All()，但允许途中处理）。

func (*LazyCollection[T]) Count 

func (l *LazyCollection[T]) Count() (int64, error)

Count 返回总计数（需要再次查询 DB）。

func (*LazyCollection[T]) Each 

func (l *LazyCollection[T]) Each(fn func(int, *T) error) (int, error)

Each 遍历所有行并执行回调。返回处理的条目数和首个错误。

func (*LazyCollection[T]) Err 

func (l *LazyCollection[T]) Err() error

Err 返回迭代过程中的错误。

func (*LazyCollection[T]) Next 

func (l *LazyCollection[T]) Next() bool

Next 移动到下一行。返回 false 表示无更多行或发生错误。

func (*LazyCollection[T]) Scan 

func (l *LazyCollection[T]) Scan(dst *T) error

Scan 将当前行扫描到目标结构体。

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager 按连接名惰性创建并缓存 DB。

func NewManager 

func NewManager(config ManagerConfig) *Manager

func (*Manager) Close 

func (m *Manager) Close() error

func (*Manager) Connection 

func (m *Manager) Connection(ctx context.Context, names ...string) (*DB, error)

func (*Manager) Forget 

func (m *Manager) Forget(ctx context.Context, names ...string) error

func (*Manager) MustConnection 

func (m *Manager) MustConnection(ctx context.Context, names ...string) *DB

type ManagerConfig 

type ManagerConfig struct {
	Default     string
	Connections map[string]Config
}

ManagerConfig 描述命名数据库连接。Default 必须指向 Connections 中的一项。

type Managers 

type Managers struct {
	// contains filtered or unexported fields
}

Managers 保存应用作用域的惰性数据库管理器。

func (*Managers) Close 

func (m *Managers) Close() error

Close 关闭所有已经建立的应用数据库连接。

type Migration 

type Migration struct {
	// ID 迁移文件名（不含 .go 后缀）。
	ID string
	// Batch 批次号（同批次一起回滚）。
	Batch int
	// AppliedAt 执行时间。
	AppliedAt time.Time
}

Migration 表示一条数据库迁移记录。

type Migrator 

type Migrator struct {
	// contains filtered or unexported fields
}

Migrator 数据库迁移运行器。

负责在数据库中创建迁移记录表，按文件名排序执行 Up/Down。

用法： 

db := tdb.Open(...)
m := db.Migrator("database/migrations")
m.Up()    // 执行所有待执行迁移
m.Down()  // 回滚最近一批
m.Reset() // 回滚所有并重新执行

func (*Migrator) Down 

func (m *Migrator) Down() error

Down 回滚最近一批迁移。

func (*Migrator) DryRun 

func (m *Migrator) DryRun() *Migrator

DryRun 设置为演习模式（仅打印 SQL 和日志，不实际执行）。

func (*Migrator) Reset 

func (m *Migrator) Reset() error

Reset 回滚全部迁移并重新执行。

func (*Migrator) SetTableName 

func (m *Migrator) SetTableName(name string) *Migrator

SetTableName 设置迁移记录表名（默认 "migrations"）。

func (*Migrator) Status 

func (m *Migrator) Status() error

Status 输出迁移状态。

func (*Migrator) Up 

func (m *Migrator) Up() error

Up 执行所有未执行过的迁移文件。

type Model 

type Model[T any] struct {
	// contains filtered or unexported fields
}

Model 是绑定到表与类型 T 的泛型查询/操作模型。

Safe 双模式：

  • 默认 unsafe：链式方法原地修改 Model，高性能，适合一次性构建查询。
  • Safe() 后可复用：调用 Safe() 后，每个链式方法返回 Clone 副本， 原始 Model 保持洁净可当作"查询模板"反复使用。

func ModelPrefix 

func ModelPrefix[T any](db *DB, tableName string) *Model[T]

ModelPrefix 创建带表名的 Model（供 Seed/Factory 使用）。 这是包级函数，通过 db 创建指定表名的泛型 Model。

func NewModel 

func NewModel[T any](db *DB, table ...string) *Model[T]

NewModel 构造绑定到 DB 的泛型模型。table 可省略（从 T 推断：类型名 snake_case 或 tdb:"table:xxx" 标签）。这是用户创建查询入口的主要方式。

func NewModelTx 

func NewModelTx[T any](tx *Tx, table ...string) *Model[T]

NewModelTx 构造绑定到事务的泛型模型（在 DB.Tx 回调内使用）。

func WithCount 

func WithCount[T, R any](m *Model[T], fieldName string, relation *Relation[T, R], whereFn ...func(*Model[R]) *Model[R]) *Model[T]

WithCount 注册关联数量聚合预加载：对每条 T 记录统计其关联 R 的行数， 结果写入 T 上名为 fieldName 的字段（建议 int64）。

用法： 

users, _ := tdb.WithCount(db.Model[User](), "OrderCount",
    tdb.HasMany[User, Order]("id", "user_id")).All()

whereFn 可选，用于给关联侧追加过滤（如仅统计已支付订单）。

func WithSum 

func WithSum[T, R any](m *Model[T], fieldName, column string, relation *Relation[T, R], whereFn ...func(*Model[R]) *Model[R]) *Model[T]

WithSum 注册关联求和聚合预加载：对每条 T 记录求关联 R 的 column 字段之和， 结果写入 T 上名为 fieldName 的字段（建议 float64 / int64）。

用法： 

users, _ := tdb.WithSum(db.Model[User](), "OrderAmount", "amount",
    tdb.HasMany[User, Order]("id", "user_id")).All()

func (*Model[T]) All 

func (m *Model[T]) All() ([]T, error)

All 查询多行，返回 []T。

func (*Model[T]) AllMaps 

func (m *Model[T]) AllMaps() ([]map[string]any, error)

AllMaps 执行当前查询，返回 []map[string]any（列名→值）。 适合需要拿到原始行（如联表结果）再用 ScanList 在内存中组装嵌套结构的场景。

func (*Model[T]) AllowAll 

func (m *Model[T]) AllowAll() *Model[T]

AllowAll 显式允许无 WHERE 条件的整表 Update/Delete（危险操作护栏）。

func (*Model[T]) Array 

func (m *Model[T]) Array(col string) ([]any, error)

Array 查询单列全部值，返回 []any（顺序即查询结果顺序）。

func (*Model[T]) AutoTimestamp 

func (m *Model[T]) AutoTimestamp(createCol, updateCol string) *Model[T]

AutoTimestamp 启用自动时间戳（列名为蛇形，如 "create_time"、"update_time"）。

启用后 Insert 自动填充 createCol，Update/Save 自动填充 updateCol。 仅当对应字段值为零值时才填充（不覆盖业务方显式设置的时间）。

func (*Model[T]) BatchInsert 

func (m *Model[T]) BatchInsert(list any, batch ...int) (int64, error)

BatchInsert 批量插入多条记录，单条多值 INSERT（比循环 Insert 显著减少往返）。

list 必须是 []T 或 *[]T（T 为模型结构体）。可选 batch 指定每批最大行数， 超过则分多批执行；默认 batch=10（0 表示不分批，一次插入所有行）。

注意：

  • 自动时间戳（created_at/updated_at）仅在单条 Insert 中注入； BatchInsert 需由调用方预先在结构体中填好时间字段。
  • 自增主键由数据库生成，不会回写。

func (*Model[T]) Cache 

func (m *Model[T]) Cache(key string, ttl time.Duration) *Model[T]

Cache 启用查询缓存。 key 为空时自动基于 SQL 生成缓存键；ttl 指定缓存过期时间。

func (*Model[T]) CacheForever 

func (m *Model[T]) CacheForever(key string) *Model[T]

CacheForever 永久缓存（无过期）。

func (*Model[T]) Chunk 

func (m *Model[T]) Chunk(size int, f func(records []T) error) error

Chunk 分批游标：每批取 size 条，调用 f 处理。处理中发生错误立即中断并返回该错误。 适用于大数据集遍历，避免一次性加载内存。

func (*Model[T]) ChunkById 

func (m *Model[T]) ChunkById(size int, fn func(items []T) (bool, error)) error

ChunkById 基于主键游标分批处理全表。

适用于大数据集遍历：每次取 size 行，按主键升序推进游标，避免一次性加载内存。 回调返回 error 立即终止；返回 false 也终止遍历。主键由 tdb tag 的 primaryKey 标识，缺失时回退到名为 id 的字段（与 Save 主键解析规则一致）。

func (*Model[T]) Clone 

func (m *Model[T]) Clone() *Model[T]

Clone 深拷贝当前 Model，返回独立副本（不共享任何切片底层数组）。 safe 标志位不会被拷贝——Clone 出的新 Model 始终是 unsafe 的。

func (*Model[T]) Count 

func (m *Model[T]) Count() (int64, error)

Count 返回匹配行数。

func (*Model[T]) Ctx 

func (m *Model[T]) Ctx(ctx context.Context) *Model[T]

Ctx 为当前查询绑定 context.Context（用于超时/取消透传）。返回新的 Model 副本， 不修改原 Model。仅在底层驱动支持 Context 调用时生效（已支持 *sql.DB/Tx）。

func (*Model[T]) DB 

func (m *Model[T]) DB() *DB

DB 返回底层数据库句柄。用于执行原生 SQL 逃生舱（如 DB().Exec / DB().Query）， 或调用未封装的能力。注意：直接操作 DB 会绕开 Model 的钩子/事件/软删除过滤。

func (*Model[T]) Delete 

func (m *Model[T]) Delete() (sql.Result, error)

Delete 按当前 WHERE 条件删除。若 Model 包含 SoftDelete 字段则执行软删除。

func (*Model[T]) DisableHooks 

func (m *Model[T]) DisableHooks() *Model[T]

DisableHooks 禁用当前查询的模型钩子。

func (*Model[T]) Distinct 

func (m *Model[T]) Distinct() *Model[T]

Distinct 设置 SELECT DISTINCT。

func (*Model[T]) Exists 

func (m *Model[T]) Exists() (bool, error)

Exists 是否存在匹配行。

func (*Model[T]) Fields 

func (m *Model[T]) Fields(cols ...string) *Model[T]

Fields 指定 SELECT 字段（多调叠加；空参数重置为 *）。

func (*Model[T]) FieldsEx 

func (m *Model[T]) FieldsEx(cols ...string) *Model[T]

FieldsEx 排除指定列（其余列参与 SELECT）。与 Fields 互斥——同时调用时 Fields 优先生效。 空参数重置为不排除（即 *）。

func (*Model[T]) Find 

func (m *Model[T]) Find() (T, error)

Find 同 Scan，但无行时返回零值且无错误（便于可选查询）。

func (*Model[T]) FindOrFail 

func (m *Model[T]) FindOrFail() (T, error)

FindOrFail 查询单行，无结果时返回 ErrNoRows（便于上层决定 404）。 与 Find 的区别：Find 对「无行」静默返回零值，FindOrFail 显式报错。

func (*Model[T]) FirstOrCreate 

func (m *Model[T]) FirstOrCreate(cond func(*Model[T]) *Model[T], defaults any) (T, error)

FirstOrCreate 查询首行；不存在时以 merge 合并默认值后插入并返回。 

m.User().FirstOrCreate(
    tdb.WhereEQ("openid", openid),
    User{Name: "guest", Status: 1},
)

cond 是作用于查询的条件（任意返回 *Model[T] 的链式调用）； defaults 是插入时的缺省值（struct 或 map）。命中时返回已存在记录。

func (*Model[T]) ForceDelete 

func (m *Model[T]) ForceDelete() (sql.Result, error)

ForceDelete 强制执行物理删除，忽略软删除。

func (*Model[T]) Group 

func (m *Model[T]) Group(cols ...string) *Model[T]

Group 添加 GROUP BY 字段。

func (*Model[T]) Having 

func (m *Model[T]) Having(expr string, args ...any) *Model[T]

Having 添加 HAVING 条件。args 通过占位符 ? 嵌入 expr。

func (*Model[T]) Insert 

func (m *Model[T]) Insert(value any) (sql.Result, error)

Insert 插入一条记录（struct 或 map）。返回自增 ID（若驱动支持）。

func (*Model[T]) InsertIgnore 

func (m *Model[T]) InsertIgnore(value any) (sql.Result, error)

InsertIgnore 插入新记录，若发生唯一键/主键冲突则忽略（不报错）。 按方言适配：MySQL 使用 INSERT IGNORE，SQLite 使用 INSERT OR IGNORE， PostgreSQL 使用 INSERT ... ON CONFLICT DO NOTHING；其余方言退化为普通 INSERT。 注意：依赖数据库唯一约束，调用方需保证目标表存在相应约束。

func (*Model[T]) Join 

func (m *Model[T]) Join(table, on string, args ...any) *Model[T]

Join 内连接。

func (*Model[T]) Lazy 

func (m *Model[T]) Lazy() (*LazyCollection[T], error)

Lazy 创建延迟集合（游标式遍历）。

func (*Model[T]) LeftJoin 

func (m *Model[T]) LeftJoin(table, on string, args ...any) *Model[T]

LeftJoin 左连接。

func (*Model[T]) Limit 

func (m *Model[T]) Limit(n int) *Model[T]

Limit 设置 LIMIT。

func (*Model[T]) Lock 

func (m *Model[T]) Lock(lock string) *Model[T]

Lock 追加悲观锁子句到当前 Model（仅对 SELECT 生效）。

常用取值见本包导出的 LockForUpdate / LockForUpdateNoWait / LockForUpdateSkipLocked / LockShare / LockInShareMode。 传空串可清除锁（返回新的无锁 Model）。

用法： 

var users []User
m.Table("user").Lock(LockForUpdate).Where("balance > ?", 0).Scan(&users)
// SELECT * FROM `user` WHERE balance > ? FOR UPDATE

func (*Model[T]) Master 

func (m *Model[T]) Master() *Model[T]

Master 强制本次查询走主库（读写分离场景下，默认 SELECT 走从库）。 适用于刚写入后需立即读到的强一致场景。返回新的 Model 副本。

func (*Model[T]) Offset 

func (m *Model[T]) Offset(n int) *Model[T]

Offset 设置 OFFSET。

func (*Model[T]) On 

func (m *Model[T]) On(ev tevent.Event[ModelEventData], h tevent.Handler[ModelEventData])

On 注册模型事件监听器（委托到底层 DB 的事件总线）。 仅当 DB 已通过 EnableEvents(bus) 启用事件后才生效，否则静默忽略。

用法： 

model := db.Model[User]()
model.On(tdb.EventAfterInsert, func(ctx context.Context, data tdb.ModelEventData) error {
    log.Printf("inserted: %+v", data.Model)
    return nil
})

func (*Model[T]) OnAfterDelete 

func (m *Model[T]) OnAfterDelete(h tevent.Handler[ModelEventData])

func (*Model[T]) OnAfterInsert 

func (m *Model[T]) OnAfterInsert(h tevent.Handler[ModelEventData])

func (*Model[T]) OnAfterQuery 

func (m *Model[T]) OnAfterQuery(h tevent.Handler[ModelEventData])

func (*Model[T]) OnAfterSave 

func (m *Model[T]) OnAfterSave(h tevent.Handler[ModelEventData])

func (*Model[T]) OnAfterUpdate 

func (m *Model[T]) OnAfterUpdate(h tevent.Handler[ModelEventData])

func (*Model[T]) OnBeforeDelete 

func (m *Model[T]) OnBeforeDelete(h tevent.Handler[ModelEventData])

func (*Model[T]) OnBeforeInsert 

func (m *Model[T]) OnBeforeInsert(h tevent.Handler[ModelEventData])

OnBeforeInsert / OnAfterInsert 等便捷订阅（见 On）。

func (*Model[T]) OnBeforeQuery 

func (m *Model[T]) OnBeforeQuery(h tevent.Handler[ModelEventData])

func (*Model[T]) OnBeforeSave 

func (m *Model[T]) OnBeforeSave(h tevent.Handler[ModelEventData])

func (*Model[T]) OnBeforeUpdate 

func (m *Model[T]) OnBeforeUpdate(h tevent.Handler[ModelEventData])

func (*Model[T]) One 

func (m *Model[T]) One(dst *T) error

One 查询单行，写入 dst。无行返回 ErrNoRows。

func (*Model[T]) OnlyTrashed 

func (m *Model[T]) OnlyTrashed() *Model[T]

OnlyTrashed 仅查询已软删除的记录。

func (*Model[T]) Order 

func (m *Model[T]) Order(by string) *Model[T]

Order 添加 ORDER BY 片段（如 "created_at DESC"）。

func (*Model[T]) Page 

func (m *Model[T]) Page(page, size int) *Model[T]

Page 分页：page 从 1 开始，size 每页大小。

func (*Model[T]) Paginate 

func (m *Model[T]) Paginate(page, perPage int) (*PaginateResult[T], error)

Paginate 分页查询。

用法： 

result, err := db.Model[User]().Where("status", 1).Order("id desc").Paginate(1, 20)
for _, user := range result.Items { ... }

func (*Model[T]) Restore 

func (m *Model[T]) Restore() (sql.Result, error)

Restore 恢复软删除记录（SET deleted_at = NULL）。

func (*Model[T]) RightJoin 

func (m *Model[T]) RightJoin(table, on string, args ...any) *Model[T]

RightJoin 右连接。

func (*Model[T]) Safe 

func (m *Model[T]) Safe(safe ...bool) *Model[T]

Safe 设置安全模式。无参调用等同于 Safe(true)。

func (*Model[T]) Save 

func (m *Model[T]) Save(value any) (sql.Result, error)

Save 保存记录：若主键非零值（已存在）则执行 Update，否则执行 Insert。 区别于单独调用 Insert/Update：Save 会触发 BeforeSave/AfterSave 钩子， 且依据主键自动路由，适合「有则更新、无则插入」的场景。

func (*Model[T]) Scan 

func (m *Model[T]) Scan() (T, error)

Scan 同 One，但返回 T 副本（无行返回零值与 ErrNoRows）。

func (*Model[T]) ScanList 

func (m *Model[T]) ScanList(list any, ptr any, relation string, relationKey ...string) error

ScanList 把原始查询结果（[]map[string]any，通常由 All/Scan 得到）按关联层级 组装进嵌套结构体切片。对标 gf 的 Model.ScanList。

参数：

  • list : 源数据，必须是 []map[string]any 或 *[]map[string]any。
  • ptr : 目标指针，如 *[]User（User 内嵌 Profile *Profile / Orders []Order 等关联字段）。
  • relation: 关联字段名（struct 字段名，非列名），如 "Profile"、"Orders"。

组装规则：

  • ptr 元素类型中名为 relation 的字段必须是 *R（hasOne）或 []R/*[]R（hasMany）。
  • 每一行按关联字段匹配键（默认 relation 字段主键名 == relation+"Id" 的列， 如 Profile 用 profile_id；可用 relationKey 覆盖）。找不到则跳过该行关联填充。

典型用途：一次联表查询后，在内存中按归属键拼装出树状结构，避免多次 SQL。

func (*Model[T]) Scope 

func (m *Model[T]) Scope(fn ScopeFunc[T]) *Model[T]

Scope 追加单个查询作用域，等价于 Scopes(fn)。

func (*Model[T]) Scopes 

func (m *Model[T]) Scopes(fns ...ScopeFunc[T]) *Model[T]

Scopes 追加一个或多个查询作用域。 作用域在查询执行（All/Find/One/Paginate 等）前按注册顺序应用。

用法： 

users, _ := db.Model[User]().Scopes(OnlyActive, Recent).All()

func (*Model[T]) SimplePaginate 

func (m *Model[T]) SimplePaginate(page, perPage int) (*PaginateResult[T], error)

SimplePaginate 简单分页（不查总数，仅判断是否有下一页）。

func (*Model[T]) Table 

func (m *Model[T]) Table() string

Table 返回当前表名（调试/动态 SQL 用）。

func (*Model[T]) Together 

func (m *Model[T]) Together() *Model[T]

Together 级联/聚合模式标记。tingo 的预加载底层已采用「一次 IN 查询聚合所有父记录」 的批量策略（等价于 gf 的 together 模式），故 Together() 不改变执行行为，仅作为 链式可读性标记与 API 对齐存在。

典型用法（与 WithCount/WithSum 组合）： 

q := db.Model[User]().
    With("Orders", tdb.HasMany[User, Order]("id", "user_id")).
    Together()
users, _ := q.All()

func (*Model[T]) Update 

func (m *Model[T]) Update(value any) (sql.Result, error)

Update 按当前 WHERE 条件更新。value 为 struct（非零字段）或 map[string]any。

func (*Model[T]) Upsert 

func (m *Model[T]) Upsert(value any, conflictColumns ...string) (sql.Result, error)

Upsert 插入记录，并在唯一键冲突时更新非冲突列。 PostgreSQL/SQLite 必须传 conflictColumns；MySQL 由数据库唯一键自动识别冲突目标。

func (*Model[T]) Value 

func (m *Model[T]) Value(col string) (any, error)

Value 查询单列首行值。col 指定列名（如 "name"）。 无结果时返回 (nil, nil)。

func (*Model[T]) Where 

func (m *Model[T]) Where(expr string, args ...any) *Model[T]

Where 添加 WHERE 条件。支持两种形式：

  • Where("age > ? AND name = ?", 18, "bob")：占位符 ?，参数顺序绑定
  • Where("age > ?", 18)：单条件

func (*Model[T]) WhereEQ 

func (m *Model[T]) WhereEQ(col string, val any) *Model[T]

WhereEQ 便捷等值条件：WhereEQ("status", 1)。

func (*Model[T]) WhereIn 

func (m *Model[T]) WhereIn(col string, vals ...any) *Model[T]

WhereIn 添加 WHERE col IN (?, ?, ...) 条件。

func (*Model[T]) WhereMap 

func (m *Model[T]) WhereMap(mp map[string]any) *Model[T]

WhereMap 批量等值条件。map[string]any{"status": 1, "name": "bob"} → AND key=?, key=?

func (*Model[T]) WhereNotIn 

func (m *Model[T]) WhereNotIn(col string, vals ...any) *Model[T]

WhereNotIn 添加 WHERE col NOT IN (?, ?, ...) 条件。

func (*Model[T]) WhereOrModel 

func (m *Model[T]) WhereOrModel(other *Model[T]) *Model[T]

WhereOrModel 将另一个 Model 的 WHERE 条件以 OR 形式合并到当前 Model。 用法：m.WhereOrModel(NewModel[User](db).Where("age > ?", 30).Where("status = ?", 1))

func (*Model[T]) With 

func (m *Model[T]) With(name string, loader preloader) *Model[T]

With 注册关联预加载（单个）。 用法：model.With(RelationName, relationPreloader)

func (*Model[T]) WithAll 

func (m *Model[T]) WithAll(loaders map[string]preloader) *Model[T]

WithAll 一次性注册多个关联预加载。

func (*Model[T]) WithTrashed 

func (m *Model[T]) WithTrashed() *Model[T]

WithTrashed 查询时包含已软删除的记录。

func (*Model[T]) Without 

func (m *Model[T]) Without(name string) *Model[T]

Without 排除某个预加载。

func (*Model[T]) WithoutCache 

func (m *Model[T]) WithoutCache() *Model[T]

WithoutCache 禁用当前查询的缓存。

type ModelEventData 

type ModelEventData struct {
	Table  string `json:"table"`
	Event  string `json:"event"`
	Model  any    `json:"model,omitempty"`  // 关联的模型实例
	Result any    `json:"result,omitempty"` // 操作结果
}

ModelEventData 模型事件携带的数据。

type NowDialect 

type NowDialect interface {
	Now() string
}

NowDialect 是 Dialect 的可选扩展：提供「当前时间」的 SQL 表达式。 软删除默认通过绑定 time.Time 参数写入（对所有已注册方言都安全）， 若方言实现 NowDialect，则对 time 类型软删除字段优先使用服务端时间表达式 （如 NOW()/CURRENT_TIMESTAMP/datetime('now')），避免依赖客户端时区。 该扩展不破坏已有第三方方言实现（可选实现）。

type PaginateResult 

type PaginateResult[T any] struct {
	Items       []T   `json:"items"`
	Total       int64 `json:"total"`
	PerPage     int   `json:"per_page"`
	CurrentPage int   `json:"current_page"`
	LastPage    int   `json:"last_page"`
	HasMore     bool  `json:"has_more"`
}

PaginateResult 分页查询结果。

type RawQuery 

type RawQuery[T any] struct {
	// contains filtered or unexported fields
}

RawQuery 是原生 SQL 查询构建器，用于执行未封装到 Model 的 SQL 并直接映射到结构体。 绕过 Model 的钩子/事件/软删除过滤——调用方需自行保证 SQL 正确并对用户输入参数化。

用法（通过包级函数 Raw 构造）： 

var users []User
err := tdb.Raw[User](db, "SELECT * FROM user WHERE age > ?", 18).Scan(&users)

func Raw 

func Raw[T any](db *DB, query string, args ...any) *RawQuery[T]

Raw 是泛型便捷构造函数，返回一个原生 SQL 构建器，链式调用后可 Scan 到结构体。 用法： 

var users []User
err := tdb.Raw[User](db, "SELECT * FROM user WHERE age > ?", 18).Scan(&users)

绕过 Model 的钩子/事件/软删除过滤，仅做结果扫描映射。 （Go 不支持泛型方法，故以包级函数提供；db.Query/db.Exec 提供更低层的 *sql.Rows 逃生舱。）

func (*RawQuery[T]) Scan 

func (r *RawQuery[T]) Scan(dst *[]T) error

Scan 执行原生 SQL 并将多行结果映射到 dst（*[]T）。

func (*RawQuery[T]) ScanOne 

func (r *RawQuery[T]) ScanOne(dst *T) error

ScanOne 执行原生 SQL 并将首行映射到 dst（*T），无行返回 ErrNoRows。

type Relation 

type Relation[T, R any] struct {
	// contains filtered or unexported fields
}

Relation 描述两个模型之间的关联关系。

使用泛型 Relation[T, R] 来描述当前模型 T 与关联模型 R 的关系。 关联在注册期声明，查询期通过 With()/Load() 触发预加载。

func BelongsTo 

func BelongsTo[T, R any](relatedFK, pk string) *Relation[T, R]

BelongsTo 声明当前模型 T 属于某个关联模型 R（T.relatedFK = R.pk）。

例如：Order{UserId} BelongsTo User{Id} → Order.UserId = User.Id

func BelongsToMany 

func BelongsToMany[T, R any](pivot, pivotFK, pivotRelatedFK, localKey, relatedKey string) *Relation[T, R]

BelongsToMany 声明多对多关联。

pivot 是中间表名，pivotFK 指向当前模型，pivotRelatedFK 指向关联模型。 例如：User{Id} BelongsToMany Role{Id} 经 user_role(user_id, role_id)

func HasMany 

func HasMany[T, R any](foreignKey, relatedFK string) *Relation[T, R]

HasMany 声明当前模型 T 有多条关联模型 R（T.foreignKey = R.relatedFK）。

例如：User{Id} HasMany Order{UserId} → User.Id = Order.UserId

func HasOne 

func HasOne[T, R any](foreignKey, relatedFK string) *Relation[T, R]

HasOne 声明当前模型 T 有一条关联模型 R（T.foreignKey = R.relatedFK）。

例如：User{Id} HasOne Profile{UserId} → User.Id = Profile.UserId

func HasOneThrough 

func HasOneThrough[T, R any](localKey, pivotFK, pivotRelatedFK, relatedKey string) *Relation[T, R]

HasOneThrough 通过中间表获取一条远端关联。

例如：Supplier → History (经 user 表)： 

HasOneThrough[User, History]("id", "user_id", "id", "history")

对应 SQL：SELECT h.* FROM history h INNER JOIN user_history uh ON uh.history_id = h.id WHERE uh.user_id IN (1,2,3)

参数含义：

  • localKey T 上用于匹配中间表的键（通常是主键）
  • pivotFK 中间表中指向 T 的列
  • pivotRelatedFK 中间表中指向 R 的列
  • relatedKey R 上用于匹配中间表的键（通常是主键）

func MorphMany 

func MorphMany[T, R any](morphType string, morphTypeField, morphIDField string) *Relation[T, R]

MorphMany 声明多条多态一对多关联。

例如：Post{MorphMany(Comment: "commentable_type", "commentable_id")} 对应 SQL：SELECT * FROM comments WHERE commentable_type='post' AND commentable_id IN (...)

func MorphOne 

func MorphOne[T, R any](morphType string, morphTypeField, morphIDField string) *Relation[T, R]

MorphOne 声明一条多态一对一关联。

例如：User{MorphOne(Image: "imageable_type", "imageable_id")} 对应 SQL：SELECT * FROM images WHERE imageable_type='user' AND imageable_id IN (...)

func MorphTo 

func MorphTo[T, R any](morphTypeField, morphIDField string) *Relation[T, R]

MorphTo 声明多态反向关联（属于）。

R 的具体类型由源记录中的 type 字段运行时确定。 例如：Comment{CommentableType, CommentableId} MorphTo(User or Post)

func (*Relation[T, R]) SetPivot 

func (r *Relation[T, R]) SetPivot(pivot string) *Relation[T, R]

SetPivot 设置 hasOneThrough 使用的中间表名。

func (*Relation[T, R]) Type 

func (r *Relation[T, R]) Type() string

Type 返回关联类型。

type ReturningClause 

type ReturningClause struct {
	SQL      string
	Position ReturningPosition
}

ReturningClause 是方言格式化后的返回子句。

type ReturningDialect 

type ReturningDialect interface {
	ReturningClause(columns []string) (ReturningClause, error)
}

ReturningDialect 是 Dialect 的可选扩展。

type ReturningPosition 

type ReturningPosition uint8

ReturningPosition 表示返回子句在 INSERT 语句中的插入位置。 

const (
	ReturningSuffix ReturningPosition = iota
	ReturningBeforeValues
)

type Schema 

type Schema struct {
	// contains filtered or unexported fields
}

Schema 提供数据库结构变更 DSL（Schema Builder / Migration）。

使用 DB.SchemaTool() 获取 Schema 实例，然后链式调用 CreateTable/DropTable 等。

用法： 

type User struct {
    Id   int    `tdb:"id,primaryKey,autoIncrement"`
    Name string `tdb:"name,type:varchar(100)"`
    Age  int    `tdb:"age,type:int,nullable"`
}

err := db.SchemaTool().CreateTableFrom(User{})

func (*Schema) AddColumn 

func (s *Schema) AddColumn(tableName, columnName, definition string) error

AddColumn 添加列。

func (*Schema) AddForeignKey 

func (s *Schema) AddForeignKey(tableName, constraintName, column, refTable, refColumn string, onDelete, onUpdate string) error

AddForeignKey 添加外键约束。

用法示例： 

s.SchemaTool().AddForeignKey("orders", "fk_orders_user", "user_id", "users", "id", "CASCADE", "RESTRICT")

func (*Schema) AddIndex 

func (s *Schema) AddIndex(tableName, indexName, columns string, unique bool) error

AddIndex 创建索引。

func (*Schema) AutoMigrate 

func (s *Schema) AutoMigrate(models ...any) error

AutoMigrate 按模型自动建表/补列（schema 自动对齐）。

行为：

  • 表不存在：通过 CreateTableFrom 创建（内部 CREATE TABLE IF NOT EXISTS，幂等）。
  • 表存在且方言注册了 SchemaDriver（InspectTable 可用）：对比模型字段， 为缺失的列执行 AddColumn（新增列安全）；默认【不】做已有列的类型修改 （类型变更跨 dialect 不可靠且可能丢数据，需显式迁移处理）。
  • 表存在但未注册 SchemaDriver（无法内省）：仅保证表存在，不补列。

调用示例： 

db.AutoMigrate(&User{}, &Order{})

func (*Schema) CreateTable 

func (s *Schema) CreateTable(tableName string, columns map[string]string) error

CreateTable 手动指定表名和列定义。

func (*Schema) CreateTableFrom 

func (s *Schema) CreateTableFrom(model any) error

CreateTableFrom 从结构体定义创建表。 使用 struct tag 定义列属性。

func (*Schema) DropColumn 

func (s *Schema) DropColumn(tableName, columnName string) error

DropColumn 删除列。

func (*Schema) DropForeignKey 

func (s *Schema) DropForeignKey(tableName, constraintName string) error

DropForeignKey 删除外键约束。

用法示例： 

s.SchemaTool().DropForeignKey("orders", "fk_orders_user")

func (*Schema) DropIndex 

func (s *Schema) DropIndex(tableName, indexName string) error

DropIndex 删除索引。

func (*Schema) DropTable 

func (s *Schema) DropTable(tableName string) error

DropTable 删除表。

func (*Schema) DryRun 

func (s *Schema) DryRun() *Schema

DryRun 设置为仅生成 SQL 不执行。

func (*Schema) ModifyColumn 

func (s *Schema) ModifyColumn(tableName, columnName, definition string) error

ModifyColumn 修改列。

type SchemaDriver 

type SchemaDriver interface {
	// Columns 返回指定表的列信息。
	Columns(db *DB, table, schema string) ([]Column, error)
	// Tables 返回指定 schema 下的所有表名。
	Tables(db *DB, schema string) ([]string, error)
}

SchemaDriver 是数据库元信息驱动接口。 各数据库方言实现该接口以支持 InspectTable、Tables 等逆向元信息操作。

func SchemaDriverFor 

func SchemaDriverFor(dialectName string) (SchemaDriver, bool)

SchemaDriverFor 按方言名查找 SchemaDriver。

type ScopeFunc 

type ScopeFunc[T any] func(*Model[T]) *Model[T]

ScopeFunc 是查询作用域函数：接收当前模型，返回附加了查询条件的新模型。

用法： 

func OnlyActive(m *tdb.Model[User]) *tdb.Model[User] {
    return m.Where("status", 1)
}
func Recent(m *tdb.Model[User]) *tdb.Model[User] {
    return m.Order("id desc")
}

users, _ := db.Model[User]().Scopes(OnlyActive, Recent).All()

type Seeder 

type Seeder struct {
	// contains filtered or unexported fields
}

Seeder 数据填充器——用于在测试或开发环境中批量插入种子数据。

用法： 

seeder := db.Seeder()
seeder.Seed("users", []User{
    {Name: "Admin", Age: 30},
    {Name: "User1", Age: 25},
})

或使用工厂模式批量生成： 

seeder.Factory("users", 100, func(i int) User {
    return User{Name: fmt.Sprintf("User%d", i), Age: 20 + rand.Intn(30)}
})

func (*Seeder) DisableForeignKeyChecks 

func (s *Seeder) DisableForeignKeyChecks() func()

DisableForeignKeyChecks 禁用外键检查（MySQL），恢复函数返回。

func (*Seeder) Truncate 

func (s *Seeder) Truncate(tableName string) error

Truncate 清空表并重置自增 ID。

func (*Seeder) TruncateAll 

func (s *Seeder) TruncateAll(tableNames ...string) error

TruncateAll 清空所有指定表。

func (*Seeder) WithBatchSize 

func (s *Seeder) WithBatchSize(n int) *Seeder

WithBatchSize 设置批量插入大小（默认 100）。

func (*Seeder) WithContext 

func (s *Seeder) WithContext(ctx context.Context) *Seeder

WithContext 设置上下文。

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service 把约定数据库配置注册到应用容器。

func NewService 

func NewService(path string) *Service

NewService 创建数据库生命周期服务。

func (*Service) Boot 

func (*Service) Boot(context.Context, *core.App) error

func (*Service) DependsOn 

func (*Service) DependsOn() []string

func (*Service) Name 

func (*Service) Name() string

func (*Service) Register 

func (s *Service) Register(app *core.App) error

func (*Service) Shutdown 

func (*Service) Shutdown(context.Context) error

type SoftDelete 

type SoftDelete struct {
	sql.NullTime
}

SoftDeleter 软删除接口 —— Model embed 该字段后即启用软删除。

当 Delete() 被调用时，如果目标实体实现了 SoftDeleter 接口， 则 tdb 会自动将 DELETE 转换为 UPDATE SET deleted_at = <当前时间>。 time 类型优先使用方言的 Now() 表达式（服务端时间），未实现 NowDialect 的 自定义方言回退为绑定 time.Now() 参数；int 类型始终绑定 Unix 秒参数。 同时，所有 SELECT 查询会自动追加 WHERE deleted_at IS NULL。

用法示例： 

type User struct {
    Id        int
    Name      string
    DeletedAt SoftDelete `tdb:"deleted_at"`
}

func (*SoftDelete) Delete 

func (s *SoftDelete) Delete()

Delete 标记为已删除（当前时间）。

func (SoftDelete) IsDeleted 

func (s SoftDelete) IsDeleted() bool

IsDeleted 判断是否已被软删除。

func (*SoftDelete) Restore 

func (s *SoftDelete) Restore()

Restore 恢复软删除。

type SoftDeleteInt 

type SoftDeleteInt int64

SoftDeleteInt 是 int64 类型的软删除字段（Unix 时间戳）。 用法与 SoftDelete 相同，但列类型为 BIGINT 存储 Unix 秒。 

type User struct {
    Id        int
    Name      string
    DeletedAt SoftDeleteInt `tdb:"deleted_at"`
}

func (*SoftDeleteInt) Delete 

func (s *SoftDeleteInt) Delete()

Delete 标记为已删除（当前秒）。

func (SoftDeleteInt) IsDeleted 

func (s SoftDeleteInt) IsDeleted() bool

IsDeleted 判断是否已被软删除。

func (*SoftDeleteInt) Restore 

func (s *SoftDeleteInt) Restore()

Restore 恢复软删除。

func (SoftDeleteInt) Time 

func (s SoftDeleteInt) Time() time.Time

Time 返回 time.Time。

type Table 

type Table struct {
	Name    string
	Schema  string
	Comment string
	Type    string
}

Table 是数据库表的统一元信息。

type TableDescriptor 

type TableDescriptor struct {
	Name    string
	Schema  string
	Comment string
	Type    string
}

TableDescriptor 是表描述元信息。

type TableMeta 

type TableMeta struct {
	Name       string
	Schema     string
	Comment    string
	Type       string
	Columns    []Column
	Indexes    []Index
	PrimaryKey string // 兼容单主键调用；复合主键时取第一列
}

TableMeta 是一张表的元信息。

func (*TableMeta) PrimaryKeys 

func (m *TableMeta) PrimaryKeys() []string

PrimaryKeys 优先按主键约束/索引定义顺序返回；无索引元信息时回退到列定义顺序。

type TableSchemaDriver 

type TableSchemaDriver interface {
	// Table 返回表的描述元信息。
	Table(db *DB, table, schema string) (TableDescriptor, error)
}

TableSchemaDriver 提供表级元信息（表注释、类型等）。

type TimestampConfig 

type TimestampConfig struct {
	CreateAt string // 创建时间列名（空=不自动填充）
	UpdateAt string // 更新时间列名（空=不自动填充）
	DeleteAt string // 删除时间列名（空=使用结构体标签检测）
	Format   string // 时间格式："datetime"（默认）或 "int"
}

TimestampConfig 描述模型的自动时间戳策略。

func DefaultTimestampConfig 

func DefaultTimestampConfig() TimestampConfig

DefaultTimestampConfig 返回常见约定的时间戳配置。 列名自动检测 create_time / update_time / delete_time， 类型根据字段具体类型自动适配。

type Tx 

type Tx struct {
	// contains filtered or unexported fields
}

Tx 是一个事务句柄，实现与 DB 一致的查询/执行能力，但作用域限定在本次事务。 由 DB.Transaction 创建，用户不应自行构造。

func (*Tx) Commit 

func (tx *Tx) Commit() error

Commit 提交（仅在脱离 DB.Transaction 回调手动管理时需要）。

func (*Tx) Rollback 

func (tx *Tx) Rollback() error

Rollback 回滚。

func (*Tx) SQL 

func (tx *Tx) SQL() *sql.Tx

SQL 返回底层 *sql.Tx。

func (*Tx) Schema 

func (tx *Tx) Schema() *Schema

SchemaFromTx 从 Tx 实例创建 Schema（操作在同一事务中）。

func (*Tx) Transaction 

func (tx *Tx) Transaction(ctx context.Context, fn func(tx *Tx) error) error

Transaction 在已有事务内开启嵌套事务（基于 SAVEPOINT）。

  • 若方言支持 CapabilitySavepoint：通过 SAVEPOINT/ROLLBACK TO/RELEASE 提供子回滚隔离， 回调返回 error 仅回滚到该保存点，不影响外层事务；回调成功则 RELEASE 保存点。
  • 若不支持 savepoint：退化为在当前事务内直接执行（扁平化，无子回滚隔离）。

嵌套事务仍使用同一个底层 *sql.Tx，因此对所有写操作可见。

type UpsertDialect 

type UpsertDialect interface {
	UpsertClause(UpsertSpec) (string, error)
}

UpsertDialect 是 Dialect 的可选扩展，不破坏已有第三方方言实现。

type UpsertSpec 

type UpsertSpec struct {
	ConflictColumns []string
	UpdateColumns   []string
}

UpsertSpec 描述冲突目标和发生冲突时需要更新的列。 MySQL 按唯一键自动识别冲突目标，因此可忽略 ConflictColumns。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.