xormdriver

package module
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

README

gofast-xorm

GoFast 框架的 xorm 数据库驱动插件。

框架核心 go-fast-framework 不再内置 ORM 驱动，需显式安装并注册本插件。

安装

go get github.com/zhoudm1743/gofast-xorm@latest

接入

import (
    "github.com/zhoudm1743/go-fast-framework/database"
    "github.com/zhoudm1743/go-fast-framework/foundation"
    xormdriver "github.com/zhoudm1743/gofast-xorm"
)

app.SetProviders([]foundation.ServiceProvider{
    // ...
    &database.ServiceProvider{},
    &xormdriver.ServiceProvider{},
})

database:
  connections:
    main:
      driver: xorm
      engine: mysql   # mysql | postgres | sqlite | mssql
      # ...

语义说明

  • Model(&bean).Updates(...) / Update(col, val)：bean 主键含非零值时， 主键等值条件自动并入更新（与链上 Where 取 AND 交集），与 gorm 驱动 / GORM v2 行为一致。主键全零或无主键时不附加条件，更新范围完全由链上 Where 决定——无 Where 即为全表更新，批量写请务必显式 Where 或使用 Table() 并确认影响范围。
  • Save(value)：主键全零插入；非零按主键更新（行不存在回落插入）。 注：MySQL 按"已修改行"计数 affected rows——行存在但写入值无变化时 SaveResult.RowsAffected 为 0（不报错、不误插；gorm 驱动在 MySQL 上 同为 0，PG 上两驱动均按命中行计 1），需要区分"未命中"时请结合主键 存在性判断而非只看行数。
  • Exists / FirstOrCreate / FirstOrInit 与 First/Last/Take/Scan 口径一致：dest 的非零字段不会并入查询条件，查询范围只由链上 Where/conds 决定；FirstOrCreate 未命中时按 dest 原值插入。
  • Having 带参占位符：链上拒绝（ErrUnsupported）——gorm 驱动支持， 双驱动差异固化（fullcov_chain Having过滤）。
  • Joins 非法串：链上报 ErrUnsupported——gorm 驱动透传数据库原始错误。
  • Save 双分支钩子：空主键走 Create 系钩子、非空主键走 Update 系钩子 （gorm 驱动统一只触发 Update 系——双驱动差异固化，hooks_integration_test）。
  • 超时/连接失败哨兵：statement_timeout(57014)/max_execution_time(3024) → ErrQueryTimeout；连接失败 → ErrConnFailed（fault_integration_test 实测锁定）。

双驱动联合测试方案与执行报告：../docs/md/dual-driver-test-plan.md。

原生迁移能力

  • 迁移安全模式：WithMigrateSafe() / NewMigrateDriver / Migrate(cfg, models...)， PG 下强制 default_query_exec_mode=exec，根治 ALTER COLUMN TYPE 后的 pgx 语句 缓存 0A000（stitch-mes 历史 BUG 同款机制）。
  • Dry-run 预览：MigrateSQL(cfg, models...)——postgres/mssql 事务回滚、 mysql 临时库克隆，返回待执行 DDL 列表且目标库零变化。
  • 索引收敛：CheckIndexes 体检 + WithRebuildIndexes 重建同名异构索引。
  • 完整映射对照表、schema-per-tenant 批量迁移姿势、双驱动 AutoMigrate 语义差异： docs/migration.md。

依赖

  • github.com/zhoudm1743/go-fast-framework >= v0.8.2
  • xorm.io/xorm 及各 database/sql 驱动

License

Apache-2.0

Documentation

Overview

query_scan.go 实现 contracts.Query 的 Scan 系读终结方法（Scan/Pluck/ScanMap/Row/Rows）。

与 gorm 驱动的差异：

  • Scan/Pluck/ScanMap 输出语义对齐（Scan 单 struct 指针走 Get、集合走 Find； Pluck/ScanMap 基于 QueryInterface 的 []map[string]any 结果做 []byte→string 归一，与 gormdriver.ScanMap 输出形态一致）；三者均为读终结，统一经 withCache 参与查询缓存（契约全局约定 5）。
  • Row()/Rows() 仅支持 Raw() 原生 SQL 链（gorm 驱动的 Row/Rows 还可作用于 链式查询，xorm 无对应语句级游标出口）；实现上直接经 engine.DB() 连接池 执行，事务内调用同样走独立连接，不受事务约束。

Package xormdriver 基于 xorm.io/xorm 实现框架数据库抽象层 （contracts.Driver / contracts.Query / contracts.QueryCacher）。

接入方式（可选驱动，需显式加入应用 providers）： 

import xormdriver "github.com/zhoudm1743/gofast-xorm"
app.SetProviders(append(providers, &xormdriver.ServiceProvider{}))
// 配置：database.connections.<name>.driver = "xorm"

语义说明：

  • Schema()/Tenant() 多租户：显式 Table()/Model() 永远优先，仅当未显式指定 表名时才按 dest 推导表名并加 "schema." 前缀（与 gormdriver applySchema 修复后语义一致，投影结构体/分表不会被 dest 推导覆盖）。
  • Query().Cache() 查询结果缓存：需先通过 dbManager.UseQueryCache 启用 （驱动实现 contracts.QueryCacher）；JSON 序列化语义；写操作自动失效。
  • TxOption（隔离级别）：xorm 的 session.Begin() 无选项参数，当前降级为忽略。
  • 统一模型标签（orm tag）：连接配置 tag_identifier 切换引擎读取的 tag 键 （默认 "xorm"，置 "orm" 启用统一标签，§8.1/§8.2）；AutoMigrate 启动期 校验禁用 token/未知裸 token（§8.4）并对迁移期陷阱/ ext 降级告警（§10.3， 见 ormtag_check.go）。
  • Preload()：切换到框架级共享 Preload 引擎（database/preload，契约 §9.2）， 驱动侧仅保留 MetaAdapter/子查询构造薄包装；关联解析覆盖 rel tag → gorm tag → 约定 → 方向判定 → many2many → polymorphic 全链（query_preload.go）。 Debug()/Lock(LockShareMode)：xorm 无对应能力，文档化 no-op。
  • Model(&bean).Updates/Update（X-09）：bean 主键非零时自动并入主键等值 条件（与 gorm 驱动一致）；主键全零/无主键不附加条件，链上无 Where 即 为全表更新（批量写请显式 Where）。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Migrate added in v1.0.3 

func Migrate(cfg contracts.ConnectionConfig, models ...any) error

Migrate 一站式迁移（R3）：按连接配置建专用迁移驱动（含迁移安全模式）， 执行 orm tag 启动期校验（ormtag_check.go）与 Sync2（schema 非空时事务内 SET LOCAL search_path），用完即关。任一步失败即关闭引擎并返回错误。 需要额外驱动行为（如 WithRebuildIndexes）时，改用 NewMigrateDriver 自建驱动： 

drv, err := xormdriver.NewMigrateDriver(cfg, log)
if err != nil { ... }
defer drv.Close()
err = drv.AutoMigrate(models...)

func MigrateSQL added in v1.0.3 

func MigrateSQL(cfg contracts.ConnectionConfig, models ...any) ([]string, error)

MigrateSQL 返回 models 经 Sync2 将执行的 DDL 列表（Dry-run / Diff 预览， 供 CI / 运维预审）。引擎策略： 

postgres / mssql：DDL 事务性——事务内执行 Sync2，capture 驱动记录后整体回滚；
mysql：DDL 隐式提交——目标库克隆到临时库执行，捕获后 DROP 临时库；
sqlite：不支持（返回明确错误）。

与 AutoMigrate 同级做 orm tag 启动期校验（Parse 失败即报错）。 调用方应串行使用（进程级记录器，并发调用互斥等待）。

Types

type DriverOption added in v1.0.3 

type DriverOption func(*driverOptions)

DriverOption NewXormDriver / NewMigrateDriver 的功能选项。

func WithMigrateSafe added in v1.0.3 

func WithMigrateSafe() DriverOption

WithMigrateSafe 启用迁移安全模式：postgres 引擎下将连接 DSN 重写为 default_query_exec_mode=exec（pgx 不再使用 prepared statement，连接级语句 缓存被根除，ALTER COLUMN TYPE 场景不可能再触发 0A000）。非 postgres 引擎 降级为 no-op（记 Info 日志）。仅影响本次构造的驱动，与运行时连接配置彻底隔离。

func WithRebuildIndexes added in v1.0.3 

func WithRebuildIndexes() DriverOption

WithRebuildIndexes 启用索引收敛：AutoMigrate 执行 Sync2 之前，先按 xorm 期望定义（engine.TableInfo）对比库内实际索引，对同名异构索引执行 DROP INDEX， 使 Sync2 得以按模型定义重建。仅 postgres 引擎生效。

type IndexMismatch added in v1.0.3 

type IndexMismatch struct {
	Table      string   // 表名（裸名，不含 schema/库名）
	Index      string   // 索引期望落库名（xorm XName 规则还原后）
	ActualName string   // 库内实际匹配到的索引名（大小写不敏感匹配时可能与 Index 不同；missing 为空）
	Kind       string   // "missing"（期望索引不存在）| "mismatched"（同名异构：列集合/顺序不同）
	Expected   []string // 期望列（有序，小写）
	Actual     []string // 实际列（有序，小写；missing 时为 nil）
}

IndexMismatch 索引差异条目。

func CheckIndexes added in v1.0.3 

func CheckIndexes(cfg contracts.ConnectionConfig, models ...any) ([]IndexMismatch, error)

CheckIndexes 对比 models 的期望索引定义与库内实际索引（只读），返回 missing / mismatched 差异列表；无差异返回空切片。 期望定义来自 engine.TableInfo：索引实际落库名按 xorm CreateIndexSQL 的 XName 规则还原（IDX_<table>_<name> / UQE_<table>_<name>，已带前缀的名字原样）。 支持 postgres（pg_indexes）/ mysql（information_schema.statistics）/ mssql （sys.indexes + sys.index_columns）。

type ServiceProvider 

type ServiceProvider struct{}

ServiceProvider xorm 驱动接入点（可选驱动，需显式加入应用 providers）。 将本 Provider 加入应用 providers 后，配置 driver: "xorm" 即可使用： 

import xormdriver "github.com/zhoudm1743/gofast-xorm"
app.SetProviders(append(providers, &xormdriver.ServiceProvider{}))

func (*ServiceProvider) Boot 

func (sp *ServiceProvider) Boot(app foundation.Application) error

func (*ServiceProvider) Register 

func (sp *ServiceProvider) Register(app foundation.Application)

type XormDriver 

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

XormDriver 实现 contracts.Driver（方法见 driver.go / cacher.go）。

func NewMigrateDriver added in v1.0.3 

func NewMigrateDriver(cfg contracts.ConnectionConfig, log contracts.Log) (*XormDriver, error)

NewMigrateDriver 按连接配置创建迁移专用驱动：migrate-safe 模式 + 完整驱动能力（orm tag 启动期校验、多 schema Sync2），供一次性迁移流程使用， 调用方负责 Close（或直接使用下方 Migrate 一站式函数）。 schema-per-tenant 批量迁移的受支持用法：BuildTenantPgConfig(schema) → NewMigrateDriver → AutoMigrate → Close。

func NewXormDriver 

func NewXormDriver(cfg contracts.ConnectionConfig, log contracts.Log, opts ...DriverOption) (*XormDriver, error)

NewXormDriver 根据连接配置创建 xorm 驱动实例。 各引擎对应的 xorm 驱动名（底层 database/sql 驱动经 imports.go blank import 注册）： 

mysql    → "mysql"（go-sql-driver/mysql）
postgres → "pgx"（jackc/pgx/v5 stdlib）
sqlite   → "sqlite"（glebarez/go-sqlite，纯 Go）
mssql    → "mssql"（microsoft/go-mssqldb）

opts 为可选功能行为（迁移安全模式 / 索引收敛，见 migrate.go）；不传保持原行为。 自建短生命周期驱动执行 AutoMigrate 是受支持用法（schema-per-tenant 批量迁移）， 迁移场景推荐 NewMigrateDriver / Migrate（migrate-safe 模式）。

func (*XormDriver) AutoMigrate 

func (d *XormDriver) AutoMigrate(models ...any) error

AutoMigrate 根据 struct 自动建表/迁移。 启动期校验先于 Sync2 执行（ormtag_check.go，orm-tag-design.md §8.4/§10.3）： 禁用 token/未知裸 token/非法 orm tag 语法直接报错（启动即失败），ext 中 xorm 不支持项与 identifier 陷阱只告警不中断。 PostgreSQL 多租户：在事务内显式 SET LOCAL search_path，确保 DDL 在正确的 schema 执行，不依赖连接池的 DSN 初始化值（xorm 事务签名为 func(*Session) (any, error)）。 列收敛：Sync2 按基类型判等不改已有列类型/长度/nullable，AutoMigrate 在 Sync2 后追加收敛 Pass（migrate_converge.go，与 Sync2 同事务）。 rebuildIndexes（WithRebuildIndexes，PG/MySQL/MSSQL）：Sync2 前在事务外 drop 同名异构索引——不能放在事务内：Sync2 内部经 pg_indexes 读取索引定义， 会被本事务未提交的 DROP INDEX 锁阻塞（实测确认，IO wait 死等）。

func (*XormDriver) Close 

func (d *XormDriver) Close() error

Close 关闭底层连接池。

func (*XormDriver) DriverName 

func (d *XormDriver) DriverName() string

DriverName 返回驱动标识（与 database.RegisterDriver 的注册名一致）。

func (*XormDriver) EnableCaches 

func (d *XormDriver) EnableCaches(cache contracts.Cache) error

EnableCaches 为连接启用查询缓存（实现 contracts.QueryCacher，由数据库管理器调用）。 底层使用框架 Cache 服务存储，只有显式调用 Query().Cache() 的查询才会读写缓存， 其余查询零副作用；写操作（Create/Update/Delete/Save）会自动失效全部查询缓存。 重复调用安全（仅首次启用生效）。

func (*XormDriver) Ping 

func (d *XormDriver) Ping() error

Ping 检查数据库连接可用性。

func (*XormDriver) Query 

func (d *XormDriver) Query(ctx ...context.Context) contracts.Query

Query 创建新的查询构建器实例；可传入 context 用于超时/取消与链路追踪。

func (*XormDriver) RawEngine 

func (d *XormDriver) RawEngine() *xorm.Engine

RawEngine 逃生口：允许高级用户直接获取 *xorm.Engine，使用 xorm 原生 API （不推荐常规使用，绕过框架的查询语义与缓存/钩子机制）。

type XormQuery 

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

XormQuery 实现 contracts.Query。 链式方法不修改自身，而是返回追加了 applier 的新实例（不可变语义，与 gormdriver 一致）；终结方法执行时按序将 applier 应用到新建（或事务内复用）的 *xorm.Session。

func (*XormQuery) Begin 

func (q *XormQuery) Begin(opts ...contracts.TxOption) contracts.Query

Begin 手动开启事务，返回携带事务会话的新查询（链式方法不修改自身）。 开启失败时经 setErr 把包装后的 ErrInvalidTransaction 记入链上首个错误， 后续终结操作由 build()/done() 拦截返回该错误。

opts 同 Transaction：xorm session.Begin() 无选项参数，降级忽略。

func (*XormQuery) Cache 

func (q *XormQuery) Cache(opts ...contracts.CacheOption) contracts.Query

Cache 对当前查询链开启结果缓存。读终结经 withCache 生效：cacheCfg 非 nil 且驱动已 EnableCaches（qc 非 nil）时命中直接反序列化返回，未命中回源后 回填；未启用缓存的连接上本方法无副作用。

func (*XormQuery) Commit 

func (q *XormQuery) Commit() error

Commit 提交事务并释放会话；无活动事务时返回 ErrInvalidTransaction （sentinel 直传即可，wrapError 结构化不匹配时原样透传）。 事务终态一次性，Commit 后直接清空 tx 字段，保证重复 Commit/Rollback 都走"无活动事务"分支而非复用已提交的会话。

func (*XormQuery) Count 

func (q *XormQuery) Count(count *int64) error

Count 统计行数。无 dest 可供表名兜底推导，要求链上已显式 Table()/Model() （与 gormdriver Count 一致）；计数结果作为标量走查询缓存。

func (*XormQuery) Create 

func (q *XormQuery) Create(value any) error

Create 插入单条记录。

func (*XormQuery) CreateInBatches 

func (q *XormQuery) CreateInBatches(value any, batchSize int) error

CreateInBatches 分批插入切片。 gorm 的 CreateInBatches 对非切片值回落为单条 Create（default 分支）， 这里对齐：非切片直接委托 Create，钩子因此只在单条路径触发一次。 仅切片走分批（数组成员不可寻址时无法按元素触发钩子，同样回落 Create）。

func (*XormQuery) CreateResult 

func (q *XormQuery) CreateResult(value any) contracts.Result

CreateResult 插入并返回结果。RowsAffected 为 Insert 受影响行数 （单条恒为 1；value 为切片时为总行数）。

func (*XormQuery) Debug 

func (q *XormQuery) Debug() contracts.Query

Debug 文档化 no-op：xorm 无 per-session 调试开关，SQL 日志由引擎级 logger（newFastLogger，接框架 log 服务与慢日志阈值）统一配置， 无法也不必在单条查询链上切换。

func (*XormQuery) Delete 

func (q *XormQuery) Delete(value any, conds ...any) error

Delete 删除记录。

func (*XormQuery) DeleteResult 

func (q *XormQuery) DeleteResult(value any, conds ...any) contracts.Result

DeleteResult 删除并返回结果（含 Delete 前后钩子）。 RowsAffected 为删除的行数。

func (*XormQuery) Distinct 

func (q *XormQuery) Distinct(args ...any) contracts.Query

Distinct 指定去重列。xorm Distinct 接受变参列名，非 string 参数在链上报错。

func (*XormQuery) Exec 

func (q *XormQuery) Exec(sql string, values ...any) error

Exec 执行原生 SQL 写操作（INSERT/UPDATE/DELETE/DDL 等）。 成功后按写终结语义失效查询缓存：原生写与 Create/Update/Delete 终结一样 会改变数据，缓存若不失效将读到旧值（gorm 驱动由 go-gorm/caches 插件在 回调层失效，此处为自研缓存的等价语义）。

func (*XormQuery) ExecResult 

func (q *XormQuery) ExecResult(sql string, values ...any) contracts.Result

ExecResult 执行原生 SQL 写操作并返回受影响行数（X-08）。 需依据行数做业务判定（如配额原子扣减、存在性更新）时使用： RowsAffected 为 SQL 受影响行数；0 行（未命中）时 Error 为 nil， 可经 IsZeroRow 判定。事务内复用事务 session，与 Exec 同路径； 成功后失效查询缓存（写终结语义与 Exec 一致）。

func (*XormQuery) Exists 

func (q *XormQuery) Exists(dest any, conds ...any) (bool, error)

Exists 判断是否存在命中行：LIMIT 1 让 DB 命中首行后即可短路，避免全量计数。 只关心布尔结果且无可序列化的行数据，不走查询缓存。 与 First/Last/Take/Scan 同一口径（getOne）：NoAutoCondition 禁止 xorm 把 dest 的非空字段自动并入 WHERE（MergeConds）——dest 仅是表定位与输出容器， 查询范围只由链上 Where/conds 决定。

func (*XormQuery) Find 

func (q *XormQuery) Find(dest any, conds ...any) error

Find 查询多行填充到 dest（切片指针）。 AfterFind 钩子在查询成功后调用，缓存命中（withCache 提前返回 nil）同样触发， 与 gormdriver "查到数据即回调钩子" 的语义一致；钩子之后执行链上声明的 Preload 预加载（与 gorm 回调顺序一致：AfterFind 先于 preload 回填）。

func (*XormQuery) FindInBatches 

func (q *XormQuery) FindInBatches(dest any, batchSize int, fc func(contracts.Query, int) error) error

FindInBatches 分批查询：以 LIMIT batchSize + OFFSET 游标逐批加载， 每批结果追加进 dest 后回调 fc，避免一次性载入大结果集占满内存。 dest 必须是 *[]T 或 *[]*T；整体不走查询缓存（分批写回无法整体序列化恢复）。 链上声明的 Preload 逐批执行（append 前回填本批 chunk），fc 回调拿到的是 已预加载的批，与 gorm 的 FindInBatches 语义一致。

func (*XormQuery) First 

func (q *XormQuery) First(dest any, conds ...any) error

First 取按主键升序的第一行。

func (*XormQuery) FirstOrCreate 

func (q *XormQuery) FirstOrCreate(dest any, conds ...any) error

FirstOrCreate 按条件查询，命中返回该行；未命中将 dest 插入数据库。 主键自动生成由 invokeBeforeCreate 触发（AutoGenerateID），写后失效查询缓存， 与 Create 语义一致。 查询范围只由链上 Where/conds 决定（NoAutoCondition）：dest 预置的默认值 仅用于未命中时的插入，不作为查询条件（gorm 同款语义——gorm 也不会把 dest 非零字段并入 FirstOrCreate 的查询条件）。

func (*XormQuery) FirstOrInit 

func (q *XormQuery) FirstOrInit(dest any, conds ...any) error

FirstOrInit 按条件查询，命中填充 dest 并触发 AfterFind 钩子；未命中 dest 保持 调用方传入的原值、不落库。 查询范围只由链上 Where/conds 决定（NoAutoCondition，同 FirstOrCreate）。 与 gorm 的差异：gorm 会把 struct/map 条件的属性回填进 dest，此处不做回填， 需要默认值时由调用方在 dest 中预置。

func (*XormQuery) ForceDelete 

func (q *XormQuery) ForceDelete(value any, conds ...any) error

ForceDelete 物理删除记录（等价 gorm Unscoped().Delete 语义），conds 复用 终结方法变参条件。执行期先 s.Unscoped() 再 Delete：xorm 对带 `deleted` tag 的模型默认把 Delete 改写为 "UPDATE deleted_at = 值" 的软删除，不取消该语义 时"物理删除"实为软删（分组 5 集成测试暴露）；无 tag 模型上 Unscoped 无副作用。 与 gormdriver 一致不触发 Before/AfterDelete 钩子——钩子面向业务级软删除 的 Delete 路径。写终结成功后失效查询缓存。

func (*XormQuery) GetSchema 

func (q *XormQuery) GetSchema() string

GetSchema 返回当前查询上下文的 schema 名称，供业务在原生 SQL 中拼接 schema 限定的表名；无 schema 上下文时返回空字符串。

func (*XormQuery) Group 

func (q *XormQuery) Group(name string) contracts.Query

Group 指定分组列。

func (*XormQuery) Having 

func (q *XormQuery) Having(query any, args ...any) contracts.Query

Having 指定分组后条件。xorm Session.Having 精确签名为 Having(conditions string)， 仅支持不带参数占位符的 SQL 字符串：非 string 或携带参数在链上报错，而不是 静默丢弃参数生成错误 SQL。

func (*XormQuery) Joins 

func (q *XormQuery) Joins(query string, args ...any) contracts.Query

Joins 追加联表查询，兼容 gorm 风格 JOIN 串： 

Joins("LEFT JOIN profiles ON profiles.user_id = users.id", args...)
Joins("JOIN orders ON orders.uid = users.id")

前缀关键字 LEFT/RIGHT/INNER/FULL/CROSS 大小写不敏感、缺省 INNER；解析结果 映射到 xorm 的 s.Join(operator, table, cond, args...)（operator 原样拼在 JOIN 之前，合法取值如 "LEFT"/"INNER"/"LEFT OUTER"）。解析失败（缺 JOIN/ 缺 ON 等）记入链上错误，终结时经 done 返回 ErrUnsupported 包装。 关联表名执行期经 schemaTable 读取 q.schema，保证 Schema() 后置调用时 关联表同样带上租户前缀。

func (*XormQuery) Last 

func (q *XormQuery) Last(dest any, conds ...any) error

Last 取按主键降序的第一行。

func (*XormQuery) Limit 

func (q *XormQuery) Limit(limit int) contracts.Query

Limit 记录 LIMIT。不在链上写 session：分页统一由骨架 applyLimit 在执行期一次性 应用——xorm Statement.Limit 会无条件写入 LimitN（Limit(0) 生成 "LIMIT 0"）， 且 offset-only 场景需要 LIMIT 上限兜底，分散设置会破坏该约定。

func (*XormQuery) Lock 

func (q *XormQuery) Lock(mode contracts.LockMode) contracts.Query

Lock 悲观锁。仅 LockForUpdate 可落地：执行期调 s.ForUpdate() 生成 "FOR UPDATE"（xorm 侧 IsForUpdate 同时禁用其内建查询缓存，保证锁语义）。 xorm 无 SHARE 锁支持，LockShareMode 等其余模式无从表达，文档化 no-op。

func (*XormQuery) Model 

func (q *XormQuery) Model(value any) contracts.Query

Model 显式指定模型。链上即解析裸表名（已应用 TablePrefix mapper、尊重 TableName() 接口），解析失败记录首个错误；explicitTable 置位后，build() 不再按 dest 推导表名兜底，投影结构体等 dest 不会覆盖显式模型。

func (*XormQuery) Not 

func (q *XormQuery) Not(query any, args ...any) contracts.Query

Not 追加取反条件。

func (*XormQuery) Offset 

func (q *XormQuery) Offset(offset int) contracts.Query

Offset 记录 OFFSET（同 Limit，执行期由 applyLimit 统一应用）。

func (*XormQuery) Omit 

func (q *XormQuery) Omit(columns ...string) contracts.Query

Omit 排除列（查询投影与更新写入均跳过这些列）。

func (*XormQuery) OnlyTrashed 

func (q *XormQuery) OnlyTrashed() contracts.Query

OnlyTrashed 仅查询已软删除的记录（deleted_at != 0）。 列名 "deleted_at" 与 database.SoftDelete.DeletedAt 字段绑定， 若自定义软删除列名需自行实现此逻辑。 执行期先 s.Unscoped() 再挂条件：模型带 xorm `deleted` tag 时 xorm 会在查询 自动追加 "deleted_at = 0" 未删过滤，不与 Unscoped 取消会与 "deleted_at != 0" 取 AND 交集后恒空（分组 5 集成测试暴露）；无 tag 的业务级 deleted_at 列本 就不被 xorm 过滤，Unscoped 置位无副作用，两形态语义统一。

func (*XormQuery) OrWhere 

func (q *XormQuery) OrWhere(query any, args ...any) contracts.Query

OrWhere 追加 OR 条件。

func (*XormQuery) Order 

func (q *XormQuery) Order(value any) contracts.Query

Order 排序。xorm OrderBy 虽接受 any，这里收窄为 string（框架 Query 接口语义）， 其他类型在链上报错，避免隐式格式化产生意外排序串。

func (*XormQuery) Paginate 

func (q *XormQuery) Paginate(page, size int) contracts.Query

Paginate 按页码/页大小设置分页（页码与页大小非法时归一为 1/20）。 LIMIT/OFFSET 不在此处直接写入 session，而是记录到 limitN/startN， 统一由骨架 applyLimit 在执行期应用（规避 xorm Limit(0) 生成 "LIMIT 0" 及 offset-only 场景的方言合法性等边界问题）。

func (*XormQuery) Pluck 

func (q *XormQuery) Pluck(column string, dest any) error

Pluck 查询单列并按序收集进 dest（*[]基本类型）。 要求链上已显式 Table()/Model()：此处 build(nil) 不做 dest 表名推导，且 xorm GenQuerySQL 在未设置表名时直接返回 ErrTableNotFound，依赖 dest 推导不可行。

列选择经 s.Cols(column) 注入：已确认 xorm v1.4.1 中 Session.QueryInterface → statement.GenQuerySQL → genSelectColumnStr()，其列解析顺序为 SelectStr（显式 Select() 设置）→ ColumnStr()（由 Cols 填充的 ColumnMap 经 Quoter Join 生成， 优先于按模型推导的通配列），即 Cols 对 QueryInterface 的 SELECT 列生效； 副作用：若链上已有显式 Select()，其 SelectStr 会覆盖 Cols，届时 row[column] 可能缺键（走下方首键回退）。

func (*XormQuery) Preload 

func (q *XormQuery) Preload(query string, args ...any) contracts.Query

Preload 声明关联预加载。query 为字段路径（点号嵌套）。args 中 func(contracts.Query) contracts.Query 类型的项提取为子查询定制回调 （在子查询构造后、执行前应用，可排序/分页/追加条件），其余项组成首层子 查询的 Where 条件（与 gorm 语义一致）；条件类型在链上校验，非法即记入 链上错误，由终结方法返回 ErrUnsupported 包装。预加载在父查询成功装载行 后执行（Find/First/Last/Take/FindInBatches；缓存命中路径同样执行）。

func (*XormQuery) Raw 

func (q *XormQuery) Raw(sql string, values ...any) contracts.Query

Raw 记录原生 SQL 与参数，执行期经 applier 调 s.SQL 应用到 session， 后续 Find/Scan/Count 等终结方法在该原生 SQL 上执行。applier 内读取 执行期 q 的字段：链上多次 Raw 以后一次为准。原生 SQL 中的表名不自动 加 schema 前缀，多租户场景请配合 GetSchema 自行拼接。

func (*XormQuery) Restore 

func (q *XormQuery) Restore() error

Restore 恢复已软删除记录（deleted_at 置 0）。要求链上已显式 Table/Model： build(nil) 无 dest 可作表名兜底，裸链执行时 xorm 无法定位表而报错。 无 Where 条件时 xorm 不拦截全表更新（与 gorm 的 ErrMissingWhereClause 不同），恢复范围由调用方保证。写终结成功后失效查询缓存。

func (*XormQuery) Rollback 

func (q *XormQuery) Rollback() error

Rollback 回滚事务并释放会话，错误与终态语义同 Commit。

func (*XormQuery) RollbackTo 

func (q *XormQuery) RollbackTo(name string) error

RollbackTo 回滚到指定保存点，SQL 拼接与方言注意事项同 SavePoint。

func (*XormQuery) Row 

func (q *XormQuery) Row() contracts.Row

Row 执行 Raw() 记录的原生 SQL 并返回单行游标（*sql.Row 直接满足 contracts.Row）。 与 gorm 驱动的差异：xorm 驱动的 Row/Rows 仅支持 Raw() 原生 SQL；且此处不经 session 而直接走 engine.DB() 连接池执行，事务内调用同样使用独立连接，不受事务 约束（游标生命周期跨语句，无法安全绑定事务 session）。

func (*XormQuery) Rows 

func (q *XormQuery) Rows() (contracts.Rows, error)

Rows 执行 Raw() 记录的原生 SQL 并返回多行游标（*sql.Rows 直接满足 contracts.Rows：Next/Scan/Close/Columns），调用方负责 Close()。 与 gorm 驱动的差异：仅支持 Raw() 原生 SQL；事务内使用同样走独立连接， 不受事务约束。

func (*XormQuery) Save 

func (q *XormQuery) Save(value any) error

Save 保存记录：主键全零按插入处理，否则按主键更新（0 行回落插入，gorm 语义）。

func (*XormQuery) SavePoint 

func (q *XormQuery) SavePoint(name string) error

SavePoint 在当前事务内创建保存点。名字按方言引号引用（见 savepointIdent）。 与 gormdriver 交由 gorm 方言生成 SAVEPOINT 语句的行为存在差异，此处为显式拼接。

func (*XormQuery) SaveResult 

func (q *XormQuery) SaveResult(value any) contracts.Result

SaveResult 保存并返回结果（含对应插入/更新钩子）。 RowsAffected：插入路径为 Insert 受影响行数（1）；更新路径为匹配 WHERE 的行数（0 表示无匹配行，可经 IsZeroRow 判定；gorm 驱动同路径回落 upsert， 此处如上 saveOne 注释保持纯更新语义）。

func (*XormQuery) Scan 

func (q *XormQuery) Scan(dest any) error

Scan 将结果扫描进 dest：dest 为单个 struct 指针时走 Get（含 Raw SQL 单行 场景，xorm 的 GenGetSQL/GenFindSQL 在 statement.RawSQL 非空时直接返回原生 SQL，故链式与 Raw 统一适用），否则（如 *[]T、*[]*T）走 Find。 Get 返回 found=false 表示无记录，dest 保持零值属正常语义，不视为错误。 与 First/Last/Take 同一口径（getOne）：Get 前置 NoAutoCondition，dest 非空 字段不作为自动条件（MergeConds），dest 复用不会静默收窄查询范围。

func (*XormQuery) ScanMap 

func (q *XormQuery) ScanMap(dest *[]map[string]any) error

ScanMap 将结果集扫描为 []map[string]any（列名 → 归一化值）并追加进 dest， 输出形态与 gormdriver.ScanMap 一致：[]byte（MySQL 文本/二进制列经 database/sql 扫描的默认类型）转为 string，其余驱动原生类型（int64/float64/time.Time 等） 原样保留。dest 追加而非替换，与 gorm 驱动行为对齐。

func (*XormQuery) Schema 

func (q *XormQuery) Schema(name string) contracts.Query

Schema 在当前查询链上设置动态 schema（主要用于 PostgreSQL 多租户）。 后续 Table()/Model() 的表名与未显式指定表名时的 dest 兜底均按该前缀拼接 （"schema.table"），连续调用以最后一次为准；空名视为不切换直接返回。

func (*XormQuery) Scopes 

func (q *XormQuery) Scopes(funcs ...func(contracts.Query) contracts.Query) contracts.Query

Scopes 依次应用作用域函数，用于复用查询片段。每个 fn 基于当前链的独立 拷贝执行（不可变语义下 fn 返回新实例），返回 *XormQuery 则作为下一轮的 基础链（fn 内追加的 appliers/字段自然并入），否则保持原链继续；fn 为 nil 时跳过，避免可变参传入 nil 导致 panic。

func (*XormQuery) Select 

func (q *XormQuery) Select(query any, args ...any) contracts.Query

Select 指定投影列。xorm Session.Select 仅接受 string（无参数占位符语义）， 非 string 在链上报错。 Select("*") 对齐 gormdriver 语义：回归驱动默认的全列查询，此处不做任何 session 写入（no-op）——显式 "*" 会破坏 Omit 等依赖"未显式投影"的路径。

func (*XormQuery) Table 

func (q *XormQuery) Table(name string) contracts.Query

Table 显式指定表名。schema 前缀延迟到执行期经 schemaTable(q.schema) 拼接， 使 Schema() 无论先于或后于 Table() 调用都能生效。

func (*XormQuery) Take 

func (q *XormQuery) Take(dest any, conds ...any) error

Take 取任意一行（不追加排序）。

func (*XormQuery) Transaction 

func (q *XormQuery) Transaction(fc func(tx contracts.Query) error, opts ...contracts.TxOption) error

Transaction 在独立事务会话中执行 fc：成功提交，fc 返回错误则回滚。 txQ 复制当前查询并把事务会话注入 tx 字段，闭包内所有终结操作经 build() 复用该会话（xorm session 语句自动重置，可跨终结操作复用）；defer Close() 归还连接——若闭包 panic 既未提交也未回滚，xorm 的 Close 会兜底回滚事务。 注意：fc 返回错误路径显式 Rollback；panic 路径依赖 Close 兜底而非主动回滚， 与 gorm 驱动的错误才回滚语义保持一致。

opts（隔离级别/只读）：xorm 的 session.Begin() 无 *sql.TxOptions 参数， 当前降级为忽略（与 gormdriver 透传隔离级别的行为差异已在包注释声明）。

func (*XormQuery) Unscoped 

func (q *XormQuery) Unscoped() contracts.Query

Unscoped 取消软删除过滤，仅对 xorm `deleted` tag 标记的字段生效 （xorm 在查询/更新/删除时自动追加该列的未删条件，Unscoped 置位后跳过）。 框架业务级软删除（database.SoftDelete 的 deleted_at 列）不依赖该 tag， 不受本方法影响。

func (*XormQuery) Update 

func (q *XormQuery) Update(column string, value any) error

Update 更新单列（要求链上已显式 Table()/Model）。

func (*XormQuery) UpdateResult 

func (q *XormQuery) UpdateResult(column string, value any) contracts.Result

UpdateResult 更新单列并返回结果。RowsAffected 为匹配 WHERE 的行数， 0 行（未命中）时 Error 为 nil，可经 IsZeroRow 判定。 value 为 contracts.Expr 表达式时同样生效（X-08），RowsAffected 正常回填。

func (*XormQuery) Updates 

func (q *XormQuery) Updates(values any) error

Updates 批量更新字段（map 或 struct，要求链上已显式 Table()/Model）。

func (*XormQuery) UpdatesResult 

func (q *XormQuery) UpdatesResult(values any) contracts.Result

UpdatesResult 批量更新字段并返回结果。RowsAffected 语义同 UpdateResult。 map 中含 contracts.Expr 表达式键时同样生效（X-08），RowsAffected 正常回填。

func (*XormQuery) Where 

func (q *XormQuery) Where(query any, args ...any) contracts.Query

Where 追加 AND 条件。类型校验在链上完成，applier 仅在执行期落到 session。 同时把条件追加到 condSpecs（X-08）：普通查询路径不消费它，仅表达式 UPDATE （updateWithExpr）用它组装 WHERE，两路语义一致。

func (*XormQuery) WithContext 

func (q *XormQuery) WithContext(ctx context.Context) contracts.Query

WithContext 记录上下文，build 时经 s.Context 应用，查询的取消/超时随 ctx 传播到底层连接。

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.