beego之Models-ORM（六）

模型（Models）－ beego ORM

beego ORM 是一个强大的 Go 语言 ORM 框架。她的灵感主要来自 Django ORM 和 SQLAlchemy。

目前该框架仍处于开发阶段，可能发生任何导致不兼容的改动。

已支持数据库驱动：

• MySQL：github.com/go-sql-driver/mysql
• PostgreSQL：github.com/lib/pq
• Sqlite3：github.com/mattn/go-sqlite3

以上数据库驱动均通过基本测试，但我们仍需要您的反馈。

ORM 特性：

• 支持 Go 的所有类型存储
• 轻松上手，采用简单的 CRUD 风格
• 自动 Join 关联表
• 跨数据库兼容查询
• 允许直接使用 SQL 查询／映射
• 严格完整的测试保证 ORM 的稳定与健壮

更多特性请在文档中自行品读。

安装 ORM：

go get github.com/beego/beego/v2/client/orm

快速入门

简单示例

package main

import (
    "fmt"
    "github.com/beego/beego/v2/client/orm"
    _ "github.com/go-sql-driver/mysql" // import your used driver
)

// Model Struct
type User struct {
    Id   int
    Name string `orm:"size(100)"`
}

func init() {
    // set default database
    orm.RegisterDataBase("default", "mysql", "username:password@tcp(127.0.0.1:3306)/db_name?charset=utf8&loc=Local")

    // register model
    orm.RegisterModel(new(User))

    // create table
    orm.RunSyncdb("default", false, true)
}

func main() {
    o := orm.NewOrm()

    user := User{Name: "slene"}

    // insert
    id, err := o.Insert(&user)
    fmt.Printf("ID: %d, ERR: %v\n", id, err)

    // update
    user.Name = "astaxie"
    num, err := o.Update(&user)
    fmt.Printf("NUM: %d, ERR: %v\n", num, err)

    // read one
    u := User{Id: user.Id}
    err = o.Read(&u)
    fmt.Printf("ERR: %v\n", err)

    // delete
    num, err = o.Delete(&u)
    fmt.Printf("NUM: %d, ERR: %v\n", num, err)
}

关联查询

type Post struct {
    Id    int    `orm:"auto"`
    Title string `orm:"size(100)"`
    User  *User  `orm:"rel(fk)"`
}

var posts []*Post
qs := o.QueryTable("post")
num, err := qs.Filter("User__Name", "slene").All(&posts)

SQL 查询

当您无法使用 ORM 来达到您的需求时，也可以直接使用 SQL 来完成查询／映射操作。

var maps []orm.Params
num, err := o.Raw("SELECT * FROM user").Values(&maps)
for _,term := range maps{
    fmt.Println(term["id"],":",term["name"])
}

事务处理

o.Begin()
...
user := User{Name: "slene"}
id, err := o.Insert(&user)
if err == nil {
    o.Commit()
} else {
    o.Rollback()
}

调试查询日志

在开发环境下，您可以使用以下指令来开启查询调试模式：

func main() {
    orm.Debug = true
...

开启后将会输出所有查询语句，包括执行、准备、事务等。

例如：

[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [    db.Exec /     0.4ms] -   [INSERT INTO `user` (`name`) VALUES (?)] - `slene`
...

注意：我们不建议您在部署产品后这样做。

ORM 使用方法

beego/orm 的使用例子

后文例子如无特殊说明都以这个为基础。

注意的是，v2.x和v1.x在 ORM 上有一个极大的不同，即v2.x的ORM对象被设计为无状态的，因而天然是线程安全的。

也因此，我们建议在使用过程中，一个数据库应该只存在一个ORM对象。

models.go:

package main

import (
    "github.com/beego/beego/v2/client/orm"
)

type User struct {
    Id          int
    Name        string
    Profile     *Profile   `orm:"rel(one)"` // OneToOne relation
    Post        []*Post `orm:"reverse(many)"` // 设置一对多的反向关系
}

type Profile struct {
    Id          int
    Age         int16
    User        *User   `orm:"reverse(one)"` // 设置一对一反向关系(可选)
}

type Post struct {
    Id    int
    Title string
    User  *User  `orm:"rel(fk)"`    //设置一对多关系
    Tags  []*Tag `orm:"rel(m2m)"`
}

type Tag struct {
    Id    int
    Name  string
    Posts []*Post `orm:"reverse(many)"` //设置多对多反向关系
}

func init() {
    // 需要在init中注册定义的model
    orm.RegisterModel(new(User), new(Post), new(Profile), new(Tag))
}

main.go

package main

import (
    "fmt"
    "github.com/beego/beego/v2/client/orm"
    _ "github.com/go-sql-driver/mysql"
)

func init() {
    orm.RegisterDriver("mysql", orm.DRMySQL)

    orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8")
}

func main() {

    // 默认使用 default，你可以指定为其他数据库
    o := orm.NewOrm()

    profile := new(Profile)
    profile.Age = 30

    user := new(User)
    user.Profile = profile
    user.Name = "slene"

    fmt.Println(o.Insert(profile))
    fmt.Println(o.Insert(user))
}

数据库的设置

目前 ORM 支持多种数据库，以下为测试过的 driver

将你需要使用的 driver 加入 import 中

import (
    _ "github.com/go-sql-driver/mysql"
    _ "github.com/lib/pq"
    _ "github.com/mattn/go-sqlite3"
)

RegisterDriver

默认数据库类型

orm.DRMySQL
orm.DRSqlite
orm.DRPostgres
orm.DRTiDB

// < 1.6
orm.DR_MySQL
orm.DR_Sqlite
orm.DR_Postgres
// 参数1   driverName
// 参数2   数据库类型
// 这个用来设置 driverName 对应的数据库类型
// mysql / sqlite3 / postgres / tidb 这几种是默认已经注册过的，所以可以无需设置
orm.RegisterDriver("mysql", orm.DRMySQL)

RegisterDataBase

ORM 必须注册一个别名为 default 的数据库，作为默认使用。

ORM 使用 golang 自己的连接池

// 参数1        数据库的别名，用来在 ORM 中切换数据库使用
// 参数2        driverName
// 参数3        对应的链接字符串
orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8")

// 参数4(可选)  设置最大空闲连接
// 参数5(可选)  设置最大数据库连接 (go >= 1.2)
maxIdle := 30
maxConn := 30
orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", orm.MaxIdleConnections(maxIdle), orm.MaxOpenConnections(maxConn))

SetMaxIdleConns

根据数据库的别名，设置数据库的最大空闲连接

orm.SetMaxIdleConns("default", 30)

SetMaxOpenConns

根据数据库的别名，设置数据库的最大数据库连接 (go >= 1.2)

orm.SetMaxOpenConns("default", 30)

时区设置

ORM 默认使用 time.Local 本地时区

• 作用于 ORM 自动创建的时间
• 从数据库中取回的时间转换成 ORM 本地时间

如果需要的话，你也可以进行更改

// 设置为 UTC 时间
orm.DefaultTimeLoc = time.UTC

ORM 在进行 RegisterDataBase 的同时，会获取数据库使用的时区，然后在 time.Time 类型存取时做相应转换，以匹配时间系统，从而保证时间不会出错。

注意:

• 鉴于 Sqlite3 的设计，存取默认都为 UTC 时间
• 使用 go-sql-driver 驱动时，请注意参数设置
  从某一版本开始，驱动默认使用 UTC 时间，而非本地时间，所以请指定时区参数或者全部以 UTC 时间存取
  例如：root:root@/orm_test?charset=utf8&loc=Asia%2FShanghai
  参见 loc / parseTime

注册模型

如果使用 orm.QuerySeter 进行高级查询的话，这个是必须的。

反之，如果只使用 Raw 查询和 map struct，是无需这一步的。您可以去查看 Raw SQL 查询

RegisterModel

将你定义的 Model 进行注册，最佳设计是有单独的 models.go 文件，在他的 init 函数中进行注册。

迷你版 models.go

package main

import "github.com/beego/beego/v2/client/orm"

type User struct {
    Id   int
    Name string
}

func init(){
    orm.RegisterModel(new(User))
}

RegisterModel 也可以同时注册多个 model

orm.RegisterModel(new(User), new(Profile), new(Post))

详细的 struct 定义请查看文档 模型定义

RegisterModelWithPrefix

使用表名前缀

orm.RegisterModelWithPrefix("prefix_", new(User))

创建后的表名为 prefix_user

NewOrmWithDB

有时候需要自行管理连接池与数据库链接（比如：go 的链接池无法让两次查询使用同一个链接的）

但又想使用 ORM 的查询功能

var driverName, aliasName string
// driverName 是驱动的名称
// aliasName 是当前 db 的自定义别名
var db *sql.DB
...
o := orm.NewOrmWithDB(driverName, aliasName, db)

GetDB

从已注册的数据库返回 *sql.DB 对象，默认返回别名为 default 的数据库。

db, err := orm.GetDB()
if err != nil {
    fmt.Println("get default DataBase")
}

db, err := orm.GetDB("alias")
if err != nil {
    fmt.Println("get alias DataBase")
}

ResetModelCache

重置已经注册的模型 struct，一般用于编写测试用例

orm.ResetModelCache()

ORM 接口使用

使用 ORM 必然接触的 Ormer 接口，我们来熟悉一下

var o orm.Ormer
o = orm.NewOrm() // 创建一个 Ormer
// NewOrm 的同时会执行 orm.BootStrap (整个 app 只执行一次)，用以验证模型之间的定义并缓存。

大多数情况下，你可以直接使用这个。

但是在使用事务的时候，我们会返回TxOrm的实例。请参考orm 事务

和 v1.x 比起来，我们在事务上重新设计了一番，以规避相当多用户都会犯的错——即复用全局的 orm 对象来操作事务。

这体现了我们的一个新的认知——即，我们认为 orm 对象应该是一种无状态的对象。

在实际应用中，我们现在推荐大家保存全局的 orm 对象。而事务orm 对象，即 TxOrm 的实例，则应该每次使用完毕就丢弃。

QueryTable

o := orm.NewOrm()
var qs orm.QuerySeter
qs = o.QueryTable("user")
// 如果表没有定义过，会立刻 panic

Using

我们的 v2.x 移除了这个方法。因为 v1.x 的一些用户反馈，该方法容易被程序员误用。

在不恰当的切换数据库的时候，会导致使用相同 orm 实例的其余代码崩溃。

想象一下，你有一段代码本来只是想用 A 数据库的，结果另外一段代码切换到了 B 数据库。

我们推荐使用另外一个方法：
go o := orm.NewOrmUsingDB("db_name")

正如前面提及的，我们希望大家能够尽量复用 orm 实例。

Raw

使用 sql 语句直接进行操作

Raw 函数，返回一个 RawSeter 用以对设置的 sql 语句和参数进行操作

o := orm.NewOrm()
var r orm.RawSeter
r = o.Raw("UPDATE user SET name = ? WHERE name = ?", "testing", "slene")

Driver

返回当前 ORM 使用的 db 信息

type Driver interface {
    Name() string
    Type() DriverType
}
orm.RegisterDataBase("db1", "mysql", "root:root@/orm_db2?charset=utf8")
orm.RegisterDataBase("db2", "sqlite3", "data.db")

o1 := orm.NewOrmUsingDB("db1")
dr := o1.Driver()
fmt.Println(dr.Name() == "db1") // true
fmt.Println(dr.Type() == orm.DRMySQL) // true

o2 := orm.NewOrmUsingDB("db2")
dr = o2.Driver()
fmt.Println(dr.Name() == "db2") // true
fmt.Println(dr.Type() == orm.DRSqlite) // true

调试模式打印查询语句

简单的设置 Debug 为 true 打印查询的语句

可能存在性能问题，不建议使用在生产模式

func main() {
    orm.Debug = true
...

默认使用 os.Stderr 输出日志信息

改变输出到你自己的 io.Writer

var w io.Writer
...
// 设置为你的 io.Writer
...
orm.DebugLog = orm.NewLog(w)

日志格式

[ORM] - 时间 - [Queries/数据库名] - [执行操作/执行时间] - [SQL语句] - 使用标点 `,` 分隔的参数列表 - 打印遇到的错误
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [    db.Exec /     0.4ms] - [INSERT INTO `user` (`name`) VALUES (?)] - `slene`
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [    db.Exec /     0.5ms] - [UPDATE `user` SET `name` = ? WHERE `id` = ?] - `astaxie`, `14`
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [db.QueryRow /     0.4ms] - [SELECT `id`, `name` FROM `user` WHERE `id` = ?] - `14`
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [    db.Exec /     0.4ms] - [INSERT INTO `post` (`user_id`,`title`,`content`) VALUES (?, ?, ?)] - `14`, `beego orm`, `powerful amazing`
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [   db.Query /     0.4ms] - [SELECT T1.`name` `User__Name`, T0.`user_id` `User`, T1.`id` `User__Id` FROM `post` T0 INNER JOIN `user` T1 ON T1.`id` = T0.`user_id` WHERE T0.`id` = ? LIMIT 1000] - `68`
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [    db.Exec /     0.4ms] - [DELETE FROM `user` WHERE `id` = ?] - `14`
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [   db.Query /     0.3ms] - [SELECT T0.`id` FROM `post` T0 WHERE T0.`user_id` IN (?) ] - `14`
[ORM] - 2013-08-09 13:18:16 - [Queries/default] - [    db.Exec /     0.4ms] - [DELETE FROM `post` WHERE `id` IN (?)] - `68`

日志内容包括 所有的数据库操作，事务，Prepare，等

对象的 CRUD 操作

如果已知主键的值，那么可以使用这些方法进行 CRUD 操作

对 object 操作的四个方法 Read / Insert / Update / Delete

o := orm.NewOrm()
user := new(User)
user.Name = "slene"

fmt.Println(o.Insert(user))

user.Name = "Your"
fmt.Println(o.Update(user))
fmt.Println(o.Read(user))
fmt.Println(o.Delete(user))

如果需要通过条件查询获取对象，请参见高级查询

Read

o := orm.NewOrm()
user := User{Id: 1}

err := o.Read(&user)

if err == orm.ErrNoRows {
    fmt.Println("查询不到")
} else if err == orm.ErrMissPK {
    fmt.Println("找不到主键")
} else {
    fmt.Println(user.Id, user.Name)
}

Read 默认通过查询主键赋值，可以使用指定的字段进行查询：

user := User{Name: "slene"}
err = o.Read(&user, "Name")
...

复杂的单个对象查询参见 One

ReadOrCreate

尝试从数据库读取，不存在的话就创建一个。

它的实现机制，和具体的数据库有关。例如在 MYSQL 中，是使用

默认必须传入一个参数作为条件字段，同时也支持多个参数多个条件字段

o := orm.NewOrm()
user := User{Name: "slene"}
// 三个返回参数依次为：是否新创建的，对象 Id 值，错误
if created, id, err := o.ReadOrCreate(&user, "Name"); err == nil {
    if created {
        fmt.Println("New Insert an object. Id:", id)
    } else {
        fmt.Println("Get an object. Id:", id)
    }
}

Insert

第一个返回值为自增健 Id 的值

o := orm.NewOrm()
var user User
user.Name = "slene"
user.IsActive = true

id, err := o.Insert(&user)
if err == nil {
    fmt.Println(id)
}

创建后会自动对 auto 的 field 赋值

InsertMulti

同时插入多个对象

类似sql语句

insert into table (name, age) values("slene", 28),("astaxie", 30),("unknown", 20)

第一个参数 bulk 为并列插入的数量，第二个为对象的slice

返回值为成功插入的数量

users := []User{
    {Name: "slene"},
    {Name: "astaxie"},
    {Name: "unknown"},
    ...
}
successNums, err := o.InsertMulti(100, users)

bulk 为 1 时，将会顺序插入 slice 中的数据

Update

第一个返回值为影响的行数

o := orm.NewOrm()
user := User{Id: 1}
if o.Read(&user) == nil {
    user.Name = "MyName"
    if num, err := o.Update(&user); err == nil {
        fmt.Println(num)
    }
}

Update 默认更新所有的字段，可以更新指定的字段：

// 只更新 Name
o.Update(&user, "Name")
// 指定多个字段
// o.Update(&user, "Field1", "Field2", ...)
...

根据复杂条件更新字段值参见 Update

Delete

第一个返回值为影响的行数

o := orm.NewOrm()
if num, err := o.Delete(&User{Id: 1}); err == nil {
    fmt.Println(num)
}

Delete 操作会对反向关系进行操作，此例中 Post 拥有一个到 User 的外键。删除 User 的时候。如果 on_delete 设置为默认的级联操作，将删除对应的 Post

Changed in 1.0.3 删除以后不会删除 auto field 的值

高级查询

ORM 以 QuerySeter 来组织查询，每个返回 QuerySeter 的方法都会获得一个新的 QuerySeter 对象。

基本使用方法:

o := orm.NewOrm()

// 获取 QuerySeter 对象，user 为表名
qs := o.QueryTable("user")

// 也可以直接使用 Model 结构体作为表名
qs = o.QueryTable(&User)

// 也可以直接使用对象作为表名
user := new(User)
qs = o.QueryTable(user) // 返回 QuerySeter

expr

QuerySeter 中用于描述字段和 sql 操作符，使用简单的 expr 查询方法

字段组合的前后顺序依照表的关系，比如 User 表拥有 Profile 的外键，那么对 User 表查询对应的 Profile.Age 为条件，则使用 Profile__Age 注意，字段的分隔符号使用双下划线 __，除了描述字段， expr 的尾部可以增加操作符以执行对应的 sql 操作。比如 Profile__Age__gt 代表 Profile.Age > 18 的条件查询。

注释后面将描述对应的 sql 语句，仅仅是描述 expr 的类似结果，并不代表实际生成的语句。

qs.Filter("id", 1) // WHERE id = 1
qs.Filter("profile__age", 18) // WHERE profile.age = 18
qs.Filter("Profile__Age", 18) // 使用字段名和 Field 名都是允许的
qs.Filter("profile__age__gt", 18) // WHERE profile.age > 18
qs.Filter("profile__age__gte", 18) // WHERE profile.age >= 18
qs.Filter("profile__age__in", 18, 20) // WHERE profile.age IN (18, 20)

qs.Filter("profile__age__in", 18, 20).Exclude("profile__lt", 1000)
// WHERE profile.age IN (18, 20) AND NOT profile_id < 1000

Operators

当前支持的操作符号：

• exact / iexact 等于
• contains / icontains 包含
• gt / gte 大于 / 大于等于
• lt / lte 小于 / 小于等于
• startswith / istartswith 以…起始
• endswith / iendswith 以…结束
• in
• isnull

后面以 i 开头的表示：大小写不敏感

exact

Filter / Exclude / Condition expr 的默认值

qs.Filter("name", "slene") // WHERE name = 'slene'
qs.Filter("name__exact", "slene") // WHERE name = 'slene'
// 使用 = 匹配，大小写是否敏感取决于数据表使用的 collation
qs.Filter("profile_id", nil) // WHERE profile_id IS NULL

iexact

qs.Filter("name__iexact", "slene")
// WHERE name LIKE 'slene'
// 大小写不敏感，匹配任意 'Slene' 'sLENE'

contains

qs.Filter("name__contains", "slene")
// WHERE name LIKE BINARY '%slene%'
// 大小写敏感, 匹配包含 slene 的字符

icontains

qs.Filter("name__icontains", "slene")
// WHERE name LIKE '%slene%'
// 大小写不敏感, 匹配任意 'im Slene', 'im sLENE'

in

qs.Filter("age__in", 17, 18, 19, 20)
// WHERE age IN (17, 18, 19, 20)


ids:=[]int{17,18,19,20}
qs.Filter("age__in", ids)
// WHERE age IN (17, 18, 19, 20)

// 同上效果

gt / gte

qs.Filter("profile__age__gt", 17)
// WHERE profile.age > 17

qs.Filter("profile__age__gte", 18)
// WHERE profile.age >= 18

gt / gte

qs.Filter("profile__age__gt", 17)
// WHERE profile.age > 17

qs.Filter("profile__age__gte", 18)
// WHERE profile.age >= 18

lt / lte

qs.Filter("profile__age__lt", 17)
// WHERE profile.age < 17

qs.Filter("profile__age__lte", 18)
// WHERE profile.age <= 18

startswith

qs.Filter("name__startswith", "slene")
// WHERE name LIKE BINARY 'slene%'
// 大小写敏感, 匹配以 'slene' 起始的字符串

istartswith

qs.Filter("name__istartswith", "slene")
// WHERE name LIKE 'slene%'
// 大小写不敏感, 匹配任意以 'slene', 'Slene' 起始的字符串

endswith

qs.Filter("name__endswith", "slene")
// WHERE name LIKE BINARY '%slene'
// 大小写敏感, 匹配以 'slene' 结束的字符串

iendswith

qs.Filter("name__iendswithi", "slene")
// WHERE name LIKE '%slene'
// 大小写不敏感, 匹配任意以 'slene', 'Slene' 结束的字符串

isnull

qs.Filter("profile__isnull", true)
qs.Filter("profile_id__isnull", true)
// WHERE profile_id IS NULL

qs.Filter("profile__isnull", false)
// WHERE profile_id IS NOT NULL

高级查询接口使用

QuerySeter 是高级查询使用的接口，我们来熟悉下他的接口方法

type QuerySeter interface {
// add condition expression to QuerySeter.
// for example:
//  filter by UserName == 'slene'
//  qs.Filter("UserName", "slene")
//  sql : left outer join profile on t0.id1==t1.id2 where t1.age == 28
//  Filter("profile__Age", 28)
//   // time compare
//  qs.Filter("created", time.Now())
Filter(string, ...interface{}) QuerySeter
// add raw sql to querySeter.
// for example:
// qs.FilterRaw("user_id IN (SELECT id FROM profile WHERE age>=18)")
// //sql-> WHERE user_id IN (SELECT id FROM profile WHERE age>=18)
FilterRaw(string, string) QuerySeter
// add NOT condition to querySeter.
// have the same usage as Filter
Exclude(string, ...interface{}) QuerySeter
// set condition to QuerySeter.
// sql's where condition
//  cond := orm.NewCondition()
//  cond1 := cond.And("profile__isnull", false).AndNot("status__in", 1).Or("profile__age__gt", 2000)
//  //sql-> WHERE T0.`profile_id` IS NOT NULL AND NOT T0.`Status` IN (?) OR T1.`age` >  2000
//  num, err := qs.SetCond(cond1).Count()
SetCond(*Condition) QuerySeter
// get condition from QuerySeter.
// sql's where condition
//  cond := orm.NewCondition()
//  cond = cond.And("profile__isnull", false).AndNot("status__in", 1)
//  qs = qs.SetCond(cond)
//  cond = qs.GetCond()
//  cond := cond.Or("profile__age__gt", 2000)
//  //sql-> WHERE T0.`profile_id` IS NOT NULL AND NOT T0.`Status` IN (?) OR T1.`age` >  2000
//  num, err := qs.SetCond(cond).Count()
GetCond() *Condition
// add LIMIT value.
// args[0] means offset, e.g. LIMIT num,offset.
// if Limit <= 0 then Limit will be set to default limit ,eg 1000
// if QuerySeter doesn't call Limit, the sql's Limit will be set to default limit, eg 1000
//  for example:
//  qs.Limit(10, 2)
//  // sql-> limit 10 offset 2
Limit(limit interface{}, args ...interface{}) QuerySeter
// add OFFSET value
// same as Limit function's args[0]
Offset(offset interface{}) QuerySeter
// add GROUP BY expression
// for example:
//  qs.GroupBy("id")
GroupBy(exprs ...string) QuerySeter
// add ORDER expression.
// "column" means ASC, "-column" means DESC.
// for example:
//  qs.OrderBy("-status")
OrderBy(exprs ...string) QuerySeter
// add FORCE INDEX expression.
// for example:
//  qs.ForceIndex(`idx_name1`,`idx_name2`)
// ForceIndex, UseIndex , IgnoreIndex are mutually exclusive
ForceIndex(indexes ...string) QuerySeter
// add USE INDEX expression.
// for example:
//  qs.UseIndex(`idx_name1`,`idx_name2`)
// ForceIndex, UseIndex , IgnoreIndex are mutually exclusive
UseIndex(indexes ...string) QuerySeter
// add IGNORE INDEX expression.
// for example:
//  qs.IgnoreIndex(`idx_name1`,`idx_name2`)
// ForceIndex, UseIndex , IgnoreIndex are mutually exclusive
IgnoreIndex(indexes ...string) QuerySeter
// set relation model to query together.
// it will query relation models and assign to parent model.
// for example:
//  // will load all related fields use left join .
//  qs.RelatedSel().One(&user)
//  // will  load related field only profile
//  qs.RelatedSel("profile").One(&user)
//  user.Profile.Age = 32
RelatedSel(params ...interface{}) QuerySeter
// Set Distinct
// for example:
//  o.QueryTable("policy").Filter("Groups__Group__Users__User", user).
//    Distinct().
//    All(&permissions)
Distinct() QuerySeter
// set FOR UPDATE to query.
// for example:
//  o.QueryTable("user").Filter("uid", uid).ForUpdate().All(&users)
ForUpdate() QuerySeter
// return QuerySeter execution result number
// for example:
//  num, err = qs.Filter("profile__age__gt", 28).Count()
Count() (int64, error)
// check result empty or not after QuerySeter executed
// the same as QuerySeter.Count > 0
Exist() bool
// execute update with parameters
// for example:
//  num, err = qs.Filter("user_name", "slene").Update(Params{
//      "Nums": ColValue(Col_Minus, 50),
//  }) // user slene's Nums will minus 50
//  num, err = qs.Filter("UserName", "slene").Update(Params{
//      "user_name": "slene2"
//  }) // user slene's  name will change to slene2
Update(values Params) (int64, error)
// delete from table
// for example:
//  num ,err = qs.Filter("user_name__in", "testing1", "testing2").Delete()
//  //delete two user  who's name is testing1 or testing2
Delete() (int64, error)
// return a insert queryer.
// it can be used in times.
// example:
//  i,err := sq.PrepareInsert()
//  num, err = i.Insert(&user1) // user table will add one record user1 at once
//  num, err = i.Insert(&user2) // user table will add one record user2 at once
//  err = i.Close() //don't forget call Close
PrepareInsert() (Inserter, error)
// query all data and map to containers.
// cols means the columns when querying.
// for example:
//  var users []*User
//  qs.All(&users) // users[0],users[1],users[2] ...
All(container interface{}, cols ...string) (int64, error)
// query one row data and map to containers.
// cols means the columns when querying.
// for example:
//  var user User
//  qs.One(&user) //user.UserName == "slene"
One(container interface{}, cols ...string) error
// query all data and map to []map[string]interface.
// expres means condition expression.
// it converts data to []map[column]value.
// for example:
//  var maps []Params
//  qs.Values(&maps) //maps[0]["UserName"]=="slene"
Values(results *[]Params, exprs ...string) (int64, error)
// query all data and map to [][]interface
// it converts data to [][column_index]value
// for example:
//  var list []ParamsList
//  qs.ValuesList(&list) // list[0][1] == "slene"
ValuesList(results *[]ParamsList, exprs ...string) (int64, error)
// query all data and map to []interface.
// it's designed for one column record set, auto change to []value, not [][column]value.
// for example:
//  var list ParamsList
//  qs.ValuesFlat(&list, "UserName") // list[0] == "slene"
ValuesFlat(result *ParamsList, expr string) (int64, error)
// query all rows into map[string]interface with specify key and value column name.
// keyCol = "name", valueCol = "value"
// table data
// name  | value
// total | 100
// found | 200
// to map[string]interface{}{
//  "total": 100,
//  "found": 200,
// }
RowsToMap(result *Params, keyCol, valueCol string) (int64, error)
// query all rows into struct with specify key and value column name.
// keyCol = "name", valueCol = "value"
// table data
// name  | value
// total | 100
// found | 200
// to struct {
//  Total int
//  Found int
// }
RowsToStruct(ptrStruct interface{}, keyCol, valueCol string) (int64, error)
}

• 每个返回 QuerySeter 的 api 调用时都会新建一个 QuerySeter，不影响之前创建的。
• 高级查询使用 Filter 和 Exclude 来做常用的条件查询。囊括两种清晰的过滤规则：包含， 排除

Filter

用来过滤查询结果，起到 包含条件 的作用

多个 Filter 之间使用 AND 连接

qs.Filter("profile__isnull", true).Filter("name", "slene")
// WHERE profile_id IS NULL AND name = 'slene'

Exclude

用来过滤查询结果，起到 排除条件 的作用

使用 NOT 排除条件

多个 Exclude 之间使用 AND 连接

qs.Exclude("profile__isnull", true).Filter("name", "slene")
// WHERE NOT profile_id IS NULL AND name = 'slene'

SetCond

自定义条件表达式

cond := orm.NewCondition()
cond1 := cond.And("profile__isnull", false).AndNot("status__in", 1).Or("profile__age__gt", 2000)

qs := orm.QueryTable("user")
qs = qs.SetCond(cond1)
// WHERE ... AND ... AND NOT ... OR ...

cond2 := cond.AndCond(cond1).OrCond(cond.And("name", "slene"))
qs = qs.SetCond(cond2).Count()
// WHERE (... AND ... AND NOT ... OR ...) OR ( ... )

Limit

限制最大返回数据行数，第二个参数可以设置 Offset

var DefaultRowsLimit = 1000 // ORM 默认的 limit 值为 1000

// 默认情况下 select 查询的最大行数为 1000
// LIMIT 1000

qs.Limit(10)
// LIMIT 10

qs.Limit(10, 20)
// LIMIT 10 OFFSET 20 注意跟 SQL 反过来的

qs.Limit(-1)
// no limit

qs.Limit(-1, 100)
// LIMIT 18446744073709551615 OFFSET 100
// 18446744073709551615 是 1<<64 - 1 用来指定无 limit 限制 但有 offset 偏移的情况

Offset

设置 偏移行数

qs.Offset(20)
// LIMIT 1000 OFFSET 20

GroupBy

qs.GroupBy("id", "age")
// GROUP BY id,age

OrderBy

参数使用 expr

在 expr 前使用减号 - 表示 DESC 的排列

qs.OrderBy("id", "-profile__age")
// ORDER BY id ASC, profile.age DESC

qs.OrderBy("-profile__age", "profile")
// ORDER BY profile.age DESC, profile_id ASC

ForceIndex

强迫走索引。使用该选选项请确认数据库支持该特性。

qs.ForceIndex(`idx_name1`,`idx_name2`)

UseIndex

使用索引。使用该特性的时候需要确认数据库是否支持该特性，以及该特性的具体含义。例如，部分数据库对于该选项是当成一种建议来执行的。

即，即便用户使用了UseIndex方法，但是数据库在具体执行的时候，也可能不会使用设定的索引。

qs.UseIndex(`idx_name1`,`idx_name2`)

IgnoreIndex

忽略索引。请确认数据是否支持该选项。

qs.IgnoreIndex(`idx_name1`,`idx_name2`)

Distinct

对应 sql 的 distinct 语句, 返回指定字段不重复的值.

qs.Distinct()
// SELECT DISTINCT

RelatedSel

关系查询，参数使用 expr

var DefaultRelsDepth = 5 // 默认情况下直接调用 RelatedSel 将进行最大 5 层的关系查询

qs := o.QueryTable("post")

qs.RelatedSel()
// INNER JOIN user ... LEFT OUTER JOIN profile ...

qs.RelatedSel("user")
// INNER JOIN user ...
// 设置 expr 只对设置的字段进行关系查询

// 对设置 null 属性的 Field 将使用 LEFT OUTER JOIN

Count

依据当前的查询条件，返回结果行数

cnt, err := o.QueryTable("user").Count() // SELECT COUNT(*) FROM USER
fmt.Printf("Count Num: %s, %s", cnt, err)

Exist

exist := o.QueryTable("user").Filter("UserName", "Name").Exist()
fmt.Printf("Is Exist: %s", exist)

Update

依据当前查询条件，进行批量更新操作

num, err := o.QueryTable("user").Filter("name", "slene").Update(orm.Params{
    "name": "astaxie",
})
fmt.Printf("Affected Num: %s, %s", num, err)
// SET name = "astaixe" WHERE name = "slene"

原子操作增加字段值

// 假设 user struct 里有一个 nums int 字段
num, err := o.QueryTable("user").Update(orm.Params{
    "nums": orm.ColValue(orm.ColAdd, 100),
})
// SET nums = nums + 100

orm.ColValue 支持以下操作

ColAdd      // 加
ColMinus    // 减
ColMultiply // 乘
ColExcept   // 除

Delete

依据当前查询条件，进行批量删除操作

num, err := o.QueryTable("user").Filter("name", "slene").Delete()
fmt.Printf("Affected Num: %s, %s", num, err)
// DELETE FROM user WHERE name = "slene"

PrepareInsert

用于一次 prepare 多次 insert 插入，以提高批量插入的速度。

var users []*User
...
qs := o.QueryTable("user")
i, _ := qs.PrepareInsert()
for _, user := range users {
    id, err := i.Insert(user)
    if err == nil {
        ...
    }
}
// PREPARE INSERT INTO user (`name`, ...) VALUES (?, ...)
// EXECUTE INSERT INTO user (`name`, ...) VALUES ("slene", ...)
// EXECUTE ...
// ...
i.Close() // 别忘记关闭 statement

All

返回对应的结果集对象

All 的参数支持 *[]Type 和 *[]*Type 两种形式的 slice

var users []*User
num, err := o.QueryTable("user").Filter("name", "slene").All(&users)
fmt.Printf("Returned Rows Num: %s, %s", num, err)

All / Values / ValuesList / ValuesFlat 受到 Limit 的限制，默认最大行数为 1000

可以指定返回的字段：

type Post struct {
    Id      int
    Title   string
    Content string
    Status  int
}

// 只返回 Id 和 Title
var posts []Post
o.QueryTable("post").Filter("Status", 1).All(&posts, "Id", "Title")

对象的其他字段值将会是对应类型的默认值

One

尝试返回单条记录

var user User
err := o.QueryTable("user").Filter("name", "slene").One(&user)
if err == orm.ErrMultiRows {
    // 多条的时候报错
    fmt.Printf("Returned Multi Rows Not One")
}
if err == orm.ErrNoRows {
    // 没有找到记录
    fmt.Printf("Not row found")
}

可以指定返回的字段：

// 只返回 Id 和 Title
var post Post
o.QueryTable("post").Filter("Content__istartswith", "prefix string").One(&post, "Id", "Title")

对象的其他字段值将会是对应类型的默认值

Values

返回结果集的 key => value 值

key 为Model里的Field name, value的值是interface{}类型,例如，如果你要将value赋值给struct中的某字段，需要根据结构体对应字段类型使用断言获取真实值。举例:Name : m["Name"].(string)

var maps []orm.Params
num, err := o.QueryTable("user").Values(&maps)
if err == nil {
    fmt.Printf("Result Nums: %d\n", num)
    for _, m := range maps {
        fmt.Println(m["Id"], m["Name"])
    }
}

返回指定的 Field 数据

TODO: 暂不支持级联查询 RelatedSel 直接返回 Values

但可以直接指定 expr 级联返回需要的数据

var maps []orm.Params
num, err := o.QueryTable("user").Values(&maps, "id", "name", "profile", "profile__age")
if err == nil {
    fmt.Printf("Result Nums: %d\n", num)
    for _, m := range maps {
        fmt.Println(m["Id"], m["Name"], m["Profile"], m["Profile__Age"])
        // map 中的数据都是展开的，没有复杂的嵌套
    }
}

ValuesList

顾名思义，返回的结果集以slice存储

结果的排列与 Model 中定义的 Field 顺序一致

返回的每个元素值以 string 保存

var lists []orm.ParamsList
num, err := o.QueryTable("user").ValuesList(&lists)
if err == nil {
    fmt.Printf("Result Nums: %d\n", num)
    for _, row := range lists {
        fmt.Println(row)
    }
}

当然也可以指定 expr 返回指定的 Field

var lists []orm.ParamsList
num, err := o.QueryTable("user").ValuesList(&lists, "name", "profile__age")
if err == nil {
    fmt.Printf("Result Nums: %d\n", num)
    for _, row := range lists {
        fmt.Printf("Name: %s, Age: %s\m", row[0], row[1])
    }
}

ValuesFlat

只返回特定的 Field 值，将结果集展开到单个 slice 里

var list orm.ParamsList
num, err := o.QueryTable("user").ValuesFlat(&list, "name")
if err == nil {
    fmt.Printf("Result Nums: %d\n", num)
    fmt.Printf("All User Names: %s", strings.Join(list, ", "))
}

关系查询

以例子里的模型定义来看下怎么进行关系查询

User 和 Profile 是 OneToOne 的关系

已经取得了 User 对象，查询 Profile：

user := &User{Id: 1}
o.Read(user)
if user.Profile != nil {
    o.Read(user.Profile)
}

直接关联查询：

user := &User{}
o.QueryTable("user").Filter("Id", 1).RelatedSel().One(user)
// 自动查询到 Profile
fmt.Println(user.Profile)
// 因为在 Profile 里定义了反向关系的 User，所以 Profile 里的 User 也是自动赋值过的，可以直接取用。
fmt.Println(user.Profile.User)

// [SELECT T0.`id`, T0.`name`, T0.`profile_id`, T1.`id`, T1.`age` FROM `user` T0 INNER JOIN `profile` T1 ON T1.`id` = T0.`profile_id` WHERE T0.`id` = ? LIMIT 1000] - `1`

通过 User 反向查询 Profile：

var profile Profile
err := o.QueryTable("profile").Filter("User__Id", 1).One(&profile)
if err == nil {
    fmt.Println(profile)
}

Post 和 User 是 ManyToOne 关系，也就是 ForeignKey 为 User

type Post struct {
    Id    int
    Title string
    User  *User  `orm:"rel(fk)"`
    Tags  []*Tag `orm:"rel(m2m)"`
}
var posts []*Post
num, err := o.QueryTable("post").Filter("User", 1).RelatedSel().All(&posts)
if err == nil {
    fmt.Printf("%d posts read\n", num)
    for _, post := range posts {
        fmt.Printf("Id: %d, UserName: %d, Title: %s\n", post.Id, post.User.UserName, post.Title)
    }
}
// [SELECT T0.`id`, T0.`title`, T0.`user_id`, T1.`id`, T1.`name`, T1.`profile_id`, T2.`id`, T2.`age` FROM `post` T0 INNER JOIN `user` T1 ON T1.`id` = T0.`user_id` INNER JOIN `profile` T2 ON T2.`id` = T1.`profile_id` WHERE T0.`user_id` = ? LIMIT 1000] - `1`

根据 Post.Title 查询对应的 User：

RegisterModel 时，ORM 也会自动建立 User 中 Post 的反向关系，所以可以直接进行查询

var user User
err := o.QueryTable("user").Filter("Post__Title", "The Title").Limit(1).One(&user)
if err == nil {
    fmt.Printf(user)
}

Post 和 Tag 是 ManyToMany 关系

设置 rel(m2m) 以后，ORM 会自动创建中间表

type Post struct {
    Id    int
    Title string
    User  *User  `orm:"rel(fk)"`
    Tags  []*Tag `orm:"rel(m2m)"`
}
type Tag struct {
    Id    int
    Name  string
    Posts []*Post `orm:"reverse(many)"`
}

一条 Post 纪录可能对应不同的 Tag 纪录,一条 Tag 纪录可能对应不同的 Post 纪录，所以 Post 和 Tag 属于多对多关系,通过 tag name 查询哪些 post 使用了这个 tag

var posts []*Post
num, err := dORM.QueryTable("post").Filter("Tags__Tag__Name", "golang").All(&posts)

通过 post title 查询这个 post 有哪些 tag

var tags []*Tag
num, err := dORM.QueryTable("tag").Filter("Posts__Post__Title", "Introduce Beego ORM").All(&tags)

载入关系字段

LoadRelated 用于载入模型的关系字段，包括所有的 rel/reverse - one/many 关系

ManyToMany 关系字段载入

// 载入相应的 Tags
post := Post{Id: 1}
err := o.Read(&post)
num, err := o.LoadRelated(&post, "Tags")
// 载入相应的 Posts
tag := Tag{Id: 1}
err := o.Read(&tag)
num, err := o.LoadRelated(&tag, "Posts")

User 是 Post 的 ForeignKey，对应的 ReverseMany 关系字段载入

type User struct {
    Id    int
    Name  string
    Posts []*Post `orm:"reverse(many)"`
}

user := User{Id: 1}
err := dORM.Read(&user)
num, err := dORM.LoadRelated(&user, "Posts")
for _, post := range user.Posts {
    //...
}

多对多关系操作

多对多关系操作

• type QueryM2Mer interface {
  • Add(…interface{}) (int64, error)
  • Remove(…interface{}) (int64, error)
  • Exist(interface{}) bool
  • Clear() (int64, error)
  • Count() (int64, error)
• }

创建一个 QueryM2Mer 对象

o := orm.NewOrm()
post := Post{Id: 1}
m2m := o.QueryM2M(&post, "Tags")
// 第一个参数的对象，主键必须有值
// 第二个参数为对象需要操作的 M2M 字段
// QueryM2Mer 的 api 将作用于 Id 为 1 的 Post

QueryM2Mer Add

tag := &Tag{Name: "golang"}
o.Insert(tag)

num, err := m2m.Add(tag)
if err == nil {
    fmt.Println("Added nums: ", num)
}

Add 支持多种类型 Tag *Tag []*Tag []Tag []interface{}

var tags []*Tag
...
// 读取 tags 以后
...
num, err := m2m.Add(tags)
if err == nil {
    fmt.Println("Added nums: ", num)
}
// 也可以多个作为参数传入
// m2m.Add(tag1, tag2, tag3)

QueryM2Mer Remove

从M2M关系中删除 tag

Remove 支持多种类型 Tag *Tag []*Tag []Tag []interface{}

var tags []*Tag
...
// 读取 tags 以后
...
num, err := m2m.Remove(tags)
if err == nil {
    fmt.Println("Removed nums: ", num)
}
// 也可以多个作为参数传入
// m2m.Remove(tag1, tag2, tag3)

QueryM2Mer Exist

判断 Tag 是否存在于 M2M 关系中

if m2m.Exist(&Tag{Id: 2}) {
    fmt.Println("Tag Exist")
}

QueryM2Mer Clear

清除所有 M2M 关系

nums, err := m2m.Clear()
if err == nil {
    fmt.Println("Removed Tag Nums: ", nums)
}

QueryM2Mer Count

计算 Tag 的数量

nums, err := m2m.Count()
if err == nil {
    fmt.Println("Total Nums: ", nums)
}

使用SQL语句进行查询

• 使用 Raw SQL 查询，无需使用 ORM 表定义
• 多数据库，都可直接使用占位符号 ?，自动转换
• 查询时的参数，支持使用 Model Struct 和 Slice, Array

o := orm.NewOrm()
ids := []int{1, 2, 3}
var r RawSter
r = o.Raw("SELECT name FROM user WHERE id IN (?, ?, ?)", ids)

创建一个 RawSeter

o := orm.NewOrm()
var r RawSeter
r = o.Raw("UPDATE user SET name = ? WHERE name = ?", "testing", "slene")

// RawSeter raw query seter
// create From Ormer.Raw
// for example:
//  sql := fmt.Sprintf("SELECT %sid%s,%sname%s FROM %suser%s WHERE id = ?",Q,Q,Q,Q,Q,Q)
//  rs := Ormer.Raw(sql, 1)
type RawSeter interface {
    // execute sql and get result
    Exec() (sql.Result, error)
    // query data and map to container
    // for example:
    //  var name string
    //  var id int
    //  rs.QueryRow(&id,&name) // id==2 name=="slene"
    QueryRow(containers ...interface{}) error

    // query data rows and map to container
    //  var ids []int
    //  var names []int
    //  query = fmt.Sprintf("SELECT 'id','name' FROM %suser%s", Q, Q)
    //  num, err = dORM.Raw(query).QueryRows(&ids,&names) // ids=>{1,2},names=>{"nobody","slene"}
    QueryRows(containers ...interface{}) (int64, error)
    SetArgs(...interface{}) RawSeter
    // query data to []map[string]interface
    // see QuerySeter's Values
    Values(container *[]Params, cols ...string) (int64, error)
    // query data to [][]interface
    // see QuerySeter's ValuesList
    ValuesList(container *[]ParamsList, cols ...string) (int64, error)
    // query data to []interface
    // see QuerySeter's ValuesFlat
    ValuesFlat(container *ParamsList, cols ...string) (int64, error)
    // query all rows into map[string]interface with specify key and value column name.
    // keyCol = "name", valueCol = "value"
    // table data
    // name  | value
    // total | 100
    // found | 200
    // to map[string]interface{}{
    //  "total": 100,
    //  "found": 200,
    // }
    RowsToMap(result *Params, keyCol, valueCol string) (int64, error)
    // query all rows into struct with specify key and value column name.
    // keyCol = "name", valueCol = "value"
    // table data
    // name  | value
    // total | 100
    // found | 200
    // to struct {
    //  Total int
    //  Found int
    // }
    RowsToStruct(ptrStruct interface{}, keyCol, valueCol string) (int64, error)

    // return prepared raw statement for used in times.
    // for example:
    //  pre, err := dORM.Raw("INSERT INTO tag (name) VALUES (?)").Prepare()
    //  r, err := pre.Exec("name1") // INSERT INTO tag (name) VALUES (`name1`)
    Prepare() (RawPreparer, error)
}

Exec

执行 sql 语句，返回 sql.Result 对象

res, err := o.Raw("UPDATE user SET name = ?", "your").Exec()
if err == nil {
    num, _ := res.RowsAffected()
    fmt.Println("mysql row affected nums: ", num)
}

QueryRow

QueryRow 和 QueryRows 提供高级 sql mapper 功能

支持 struct

type User struct {
    Id       int
    UserName string
}

var user User
err := o.Raw("SELECT id, user_name FROM user WHERE id = ?", 1).QueryRow(&user)

QueryRows

QueryRows 支持的对象还有 map 规则是和 QueryRow 一样的，但都是 slice

type User struct {
    Id       int
    UserName string
}

var users []User
num, err := o.Raw("SELECT id, user_name FROM user WHERE id = ?", 1).QueryRows(&users)
if err == nil {
    fmt.Println("user nums: ", num)
}

SetArgs

改变 Raw(sql, args…) 中的 args 参数，返回一个新的 RawSeter

用于单条 sql 语句，重复利用，替换参数然后执行。

res, err := r.SetArgs("arg1", "arg2").Exec()
res, err := r.SetArgs("arg1", "arg2").Exec()
...

Values / ValuesList / ValuesFlat

Raw SQL 查询获得的结果集 Value 为 string 类型，NULL 字段的值为空 ``

Values

返回结果集的 key => value 值

var maps []orm.Params
num, err := o.Raw("SELECT user_name FROM user WHERE status = ?", 1).Values(&maps)
if err == nil && num > 0 {
    fmt.Println(maps[0]["user_name"]) // slene
}

ValuesList

返回结果集 slice

var lists []orm.ParamsList
num, err := o.Raw("SELECT user_name FROM user WHERE status = ?", 1).ValuesList(&lists)
if err == nil && num > 0 {
    fmt.Println(lists[0][0]) // slene
}

ValuesFlat

返回单一字段的平铺 slice 数据

var list orm.ParamsList
num, err := o.Raw("SELECT id FROM user WHERE id < ?", 10).ValuesFlat(&list)
if err == nil && num > 0 {
    fmt.Println(list) // []{"1","2","3",...}
}

RowsToMap

SQL 查询结果是这样

name	value
total	100
found	200

查询结果匹配到 map 里

res := make(orm.Params)
nums, err := o.Raw("SELECT name, value FROM options_table").RowsToMap(&res, "name", "value")
// res is a map[string]interface{}{
//  "total": 100,
//  "found": 200,
// }

RowsToStruct

SQL 查询结果是这样

name	value
total	100
found	200

查询结果匹配到 struct 里

type Options struct {
    Total int
    Found int
}

res := new(Options)
nums, err := o.Raw("SELECT name, value FROM options_table").RowsToStruct(res, "name", "value")
fmt.Println(res.Total) // 100
fmt.Println(res.Found) // 200

匹配支持的名称转换为 snake -> camel, eg: SELECT user_name … 需要你的 struct 中定义有 UserName

Prepare

用于一次 prepare 多次 exec，以提高批量执行的速度。

p, err := o.Raw("UPDATE user SET name = ? WHERE name = ?").Prepare()
res, err := p.Exec("testing", "slene")
res, err  = p.Exec("testing", "astaxie")
...
...
p.Close() // 别忘记关闭 statement

构造查询

QueryBuilder 提供了一个简便，流畅的 SQL 查询构造器。在不影响代码可读性的前提下用来快速的建立 SQL 语句。

QueryBuilder 在功能上与 ORM 重合， 但是各有利弊。ORM 更适用于简单的 CRUD 操作，而 QueryBuilder 则更适用于复杂的查询，例如查询中包含子查询和多重联结。

使用方法:

// User 包装了下面的查询结果
type User struct {
    Name string
    Age  int
}
var users []User

// 获取 QueryBuilder 对象. 需要指定数据库驱动参数。
// 第二个返回值是错误对象，在这里略过
qb, _ := orm.NewQueryBuilder("mysql")

// 构建查询对象
qb.Select("user.name",
    "profile.age").
    From("user").
    InnerJoin("profile").On("user.id_user = profile.fk_user").
    Where("age > ?").
    OrderBy("name").Desc().
    Limit(10).Offset(0)

// 导出 SQL 语句
sql := qb.String()

// 执行 SQL 语句
o := orm.NewOrm()
o.Raw(sql, 20).QueryRows(&users)

完整 API 接口:

type QueryBuilder interface {
    Select(fields ...string) QueryBuilder
    ForUpdate() QueryBuilder
    From(tables ...string) QueryBuilder
    InnerJoin(table string) QueryBuilder
    LeftJoin(table string) QueryBuilder
    RightJoin(table string) QueryBuilder
    On(cond string) QueryBuilder
    Where(cond string) QueryBuilder
    And(cond string) QueryBuilder
    Or(cond string) QueryBuilder
    In(vals ...string) QueryBuilder
    OrderBy(fields ...string) QueryBuilder
    Asc() QueryBuilder
    Desc() QueryBuilder
    Limit(limit int) QueryBuilder
    Offset(offset int) QueryBuilder
    GroupBy(fields ...string) QueryBuilder
    Having(cond string) QueryBuilder
    Update(tables ...string) QueryBuilder
    Set(kv ...string) QueryBuilder
    Delete(tables ...string) QueryBuilder
    InsertInto(table string, fields ...string) QueryBuilder
    Values(vals ...string) QueryBuilder
    Subquery(sub string, alias string) string
    String() string
}

目前支持Postgress, MySQL和TiDB的支持。

事务处理

ORM 可以简单的进行事务操作

ORM 操作事务，支持两种范式。一种通过闭包的方式，由 Beego 本身来管理事务的生命周期。

    // Beego will manage the transaction's lifecycle
    // if the @param task return error, the transaction will be rollback
    // or the transaction will be committed
    err := o.DoTx(func(ctx context.Context, txOrm orm.TxOrmer) error {
        // data
        user := new(User)
        user.Name = "test_transaction"

        // insert data
        // Using txOrm to execute SQL
        _, e := txOrm.Insert(user)
        // if e != nil the transaction will be rollback
        // or it will be committed
        return e
    })

在这种方式里面，第一个参数是task，即该事务所有完成的动作。注意的是，如果它返回了 error，那么 Beego 会将整个事务回滚。

否则提交事务。

另外一个要注意的是，如果在task执行过程中，发生了panic，那么意味着 Beego 既不会帮你把事务回滚，也不会把事务提交。

我们推荐使用这种方式。

另外一种方式，则是传统的由开发自己手动管理事务的生命周期

 o := orm.NewOrm()
    to, err := o.Begin()
    if err != nil {
        logs.Error("start the transaction failed")
        return
    }

    user := new(User)
    user.Name = "test_transaction"

    // do something with to. to is an instance of TxOrm

    // insert data
    // Using txOrm to execute SQL
    _, err = to.Insert(user)

    if err != nil {
        logs.Error("execute transaction's sql fail, rollback.", err)
        err = to.Rollback()
        if err != nil {
            logs.Error("roll back transaction failed", err)
        }
    } else {
        err = to.Commit()
        if err != nil {
            logs.Error("commit transaction failed.", err)
        }
    }

无论使用哪种方式，都应该注意到，只有通过TxOrm执行的 SQL 才会被认为是在一个事务里面。

o := orm.NewOrm()
to, err := o.Begin()

// outside the txn
o.Insert(xxx)

// inside the txn
to.Insert(xxx)

模型定义

复杂的模型定义不是必须的，此功能用作数据库数据转换和自动建表

默认的表名规则，使用驼峰转蛇形：

AuthUser -> auth_user
Auth_User -> auth__user
DB_AuthUser -> d_b__auth_user

除了开头的大写字母以外，遇到大写会增加 _，原名称中的下划线保留。

自定义表名

实现接口TableNameI:

type User struct {
    Id int
    Name string
}

func (u *User) TableName() string {
    return "auth_user"
}

如果前缀设置为 prefix_ 那么表名为：prefix_auth_user

自定义索引

实现接口TableIndexI，为单个或多个字段增加索引

type User struct {
    Id    int
    Name  string
    Email string
}

// 多字段索引
func (u *User) TableIndex() [][]string {
    return [][]string{
        []string{"Id", "Name"},
    }
}

// 多字段唯一键
func (u *User) TableUnique() [][]string {
    return [][]string{
        []string{"Name", "Email"},
    }
}

自定义引擎

仅支持 MySQL。实现接口TableEngineI。

默认使用的引擎，为当前数据库的默认引擎，这个是由你的 mysql 配置参数决定的。

你可以在模型里设置 TableEngine 函数，指定使用的引擎

type User struct {
    Id    int
    Name  string
    Email string
}

// 设置引擎为 INNODB
func (u *User) TableEngine() string {
    return "INNODB"
}

设置参数

orm:"null;rel(fk)"

多个设置间使用 ; 分隔，设置的值如果是多个，使用 , 分隔。

忽略字段

设置 - 即可忽略 struct 中的字段

type User struct {
  // ...
    AnyField string `orm:"-"`
  //...
}

auto

当 Field 类型为 int, int32, int64, uint, uint32, uint64 时，可以设置字段为自增健

• 当模型定义里没有主键时，符合上述类型且名称为 Id 的 Field 将被视为自增健。

鉴于 go 目前的设计，即使使用了 uint64，但你也不能存储到他的最大值。依然会作为 int64 处理。

pk

设置为主键，适用于自定义其他类型为主键

null

数据库表默认为 NOT NULL，设置 null 代表 ALLOW NULL

Name string `orm:"null"`

index

为单个字段增加索引

Name string `orm:"index"`

unique

为单个字段增加 unique 键

Name string `orm:"unique"`

column

为字段设置 db 字段的名称

Name string `orm:"column(user_name)"`

size

string 类型字段默认为 varchar(255)

设置 size 以后，db type 将使用 varchar(size)

Title string `orm:"size(60)"`

digits / decimals

设置 float32, float64 类型的浮点精度

Money float64 `orm:"digits(12);decimals(4)"`

总长度 12 小数点后 4 位 eg: 99999999.9999

auto_now / auto_now_add

Created time.Time `orm:"auto_now_add;type(datetime)"`
Updated time.Time `orm:"auto_now;type(datetime)"`

• auto_now 每次 model 保存时都会对时间自动更新
• auto_now_add 第一次保存时才设置时间

对于批量的 update 此设置是不生效的

type

设置为 date 时，time.Time 字段的对应 db 类型使用 date

Created time.Time `orm:"auto_now_add;type(date)"`

设置为 datetime 时，time.Time 字段的对应 db 类型使用 datetime

Created time.Time `orm:"auto_now_add;type(datetime)"`

default

在 v2.x 里面，我们提供了默认值的Filter:

import (
	"github.com/beego/beego/v2/client/orm/filter/bean"
	"github.com/beego/beego/v2/client/orm"
)

type DefaultValueTestEntity struct {
	Id            int
	Age           int `default:"12"`
	AgeInOldStyle int `orm:"default(13);bee()"`
	AgeIgnore     int
}

func XXX() {
    builder := bean.NewDefaultValueFilterChainBuilder(nil, true, true)
    orm.AddGlobalFilterChain(builder.FilterChain)
    o := orm.NewOrm()
    _, _ = o.Insert(&User{
        ID: 1,
        Name: "Tom",
    })
}		

我们一个很重要的认识，是认为显式设置值才是更加优雅的实践，所以我们将默认值的功能做成了一种可选的filter实现。

description

为字段添加注释

type User struct {
    ...
    Status int `orm:"default(1);description(这是状态字段)"`
    ...
}

注意: 注释中禁止包含引号

precision

为datetime字段设置精度值位数，不同DB支持最大精度值位数也不一致。

type User struct {
    ...
    Created time.Time `orm:"type(datetime);precision(4)"`
    ...
}

表关系设置

rel / reverse

RelOneToOne:

type User struct {
    ...
    Profile *Profile `orm:"null;rel(one);on_delete(set_null)"`
    ...
}

对应的反向关系 RelReverseOne:

type Profile struct {
    ...
    User *User `orm:"reverse(one)"`
    ...
}

RelForeignKey:

type Post struct {
    ...
    User *User `orm:"rel(fk)"` // RelForeignKey relation
    ...
}

对应的反向关系 RelReverseMany:

type User struct {
    ...
    Posts []*Post `orm:"reverse(many)"` // fk 的反向关系
    ...
}

rel_table / rel_through

此设置针对 orm:"rel(m2m)" 的关系字段

rel_table       设置自动生成的 m2m 关系表的名称
rel_through     如果要在 m2m 关系中使用自定义的 m2m 关系表
                通过这个设置其名称，格式为 pkg.path.ModelName
                eg: app.models.PostTagRel
                PostTagRel 表需要有到 Post 和 Tag 的关系

当设置 rel_table 时会忽略 rel_through

设置方法：

orm:"rel(m2m);rel_table(the_table_name)"
orm:"rel(m2m);rel_through(pkg.path.ModelName)"

on_delete

设置对应的 rel 关系删除时，如何处理关系字段。

cascade        级联删除(默认值)
set_null       设置为 NULL，需要设置 null = true
set_default    设置为默认值，需要设置 default 值
do_nothing     什么也不做，忽略

type User struct {
    ...
    Profile *Profile `orm:"null;rel(one);on_delete(set_null)"`
    ...
}
type Profile struct {
    ...
    User *User `orm:"reverse(one)"`
    ...
}

// 删除 Profile 时将设置 User.Profile 的数据库字段为 NULL

关于 on_delete 的相关例子

type User struct {
    Id int
    Name string
}

type Post struct {
    Id int
    Title string
    User *User `orm:"rel(fk)"`
}

假设 Post -> User 是 ManyToOne 的关系，也就是外键。

o.Filter("Id", 1).Delete()

这个时候即会删除 Id 为 1 的 User 也会删除其发布的 Post

不想删除的话，需要设置 set_null

type Post struct {
    Id int
    Title string
    User *User `orm:"rel(fk);null;on_delete(set_null)"`
}

那这个时候，删除 User 只会把对应的 Post.user_id 设置为 NULL

当然有时候为了高性能的需要，多存点数据无所谓啊，造成批量删除才是问题。

type Post struct {
    Id int
    Title string
    User *User `orm:"rel(fk);null;on_delete(do_nothing)"`
}

那么只要删除的时候，不操作 Post 就可以了。

模型字段与数据库类型的对应

在此列出 ORM 推荐的对应数据库类型，自动建表功能也会以此为标准。

默认所有的字段都是 NOT NULL

MySQL

go	mysql
int, int32 - 设置 auto 或者名称为 Id 时	integer AUTO_INCREMENT
int64 - 设置 auto 或者名称为 Id 时	bigint AUTO_INCREMENT
uint, uint32 - 设置 auto 或者名称为 Id 时	integer unsigned AUTO_INCREMENT
uint64 - 设置 auto 或者名称为 Id 时	bigint unsigned AUTO_INCREMENT
bool	bool
string - 默认为 size 255	varchar(size)
string - 设置 type(char) 时	char(size)
string - 设置 type(text) 时	longtext
time.Time - 设置 type 为 date 时	date
time.Time	datetime
byte	tinyint unsigned
rune	integer
int	integer
int8	tinyint
int16	smallint
int32	integer
int64	bigint
uint	integer unsigned
uint8	tinyint unsigned
uint16	smallint unsigned
uint32	integer unsigned
uint64	bigint unsigned
float32	double precision
float64	double precision
float64 - 设置 digits, decimals 时	numeric(digits, decimals)

Sqlite3

go	sqlite3
int, int32, int64, uint, uint32, uint64 - 设置 auto 或者名称为 Id 时	integer AUTOINCREMENT
bool	bool
string - 默认为 size 255	varchar(size)
string - 设置 type(char) 时	character(size)
string - 设置 type(text) 时	text
time.Time - 设置 type 为 date 时	date
time.Time	datetime
byte	tinyint unsigned
rune	integer
int	integer
int8	tinyint
int16	smallint
int32	integer
int64	bigint
uint	integer unsigned
uint8	tinyint unsigned
uint16	smallint unsigned
uint32	integer unsigned
uint64	bigint unsigned
float32	real
float64	real
float64 - 设置 digits, decimals 时	decimal

PostgreSQL

go	postgres
int, int32, int64, uint, uint32, uint64 - 设置 auto 或者名称为 Id 时	serial
bool	bool
string - 若没有指定 size 默认为 text	varchar(size)
string - 设置 type(char) 时	char(size)
string - 设置 type(text) 时	text
string - 设置 type(json) 时	json
string - 设置 type(jsonb) 时	jsonb
time.Time - 设置 type 为 date 时	date
time.Time	timestamp with time zone
byte	smallint CHECK(“column” >= 0 AND “column” <= 255)
rune	integer
int	integer
int8	smallint CHECK(“column” >= -127 AND “column” <= 128)
int16	smallint
int32	integer
int64	bigint
uint	bigint CHECK(“column” >= 0)
uint8	smallint CHECK(“column” >= 0 AND “column” <= 255)
uint16	integer CHECK(“column” >= 0)
uint32	bigint CHECK(“column” >= 0)
uint64	bigint CHECK(“column” >= 0)
float32	double precision
float64	double precision
float64 - 设置 digits, decimals 时	numeric(digits, decimals)

关系型字段

其字段类型取决于对应的主键。

• RelForeignKey
• RelOneToOne
• RelManyToMany
• RelReverseOne
• RelReverseMany

命令模式

注册模型与数据库以后，调用 RunCommand 执行 orm 命令。

func main() {
    // orm.RegisterModel...
    // orm.RegisterDataBase...
    // ...
    orm.RunCommand()
}
go build main.go
./main orm
# 直接执行可以显示帮助
# 如果你的程序可以支持的话，直接运行 go run main.go orm 也是一样的效果

自动建表

./main orm syncdb -h
Usage of orm command: syncdb:
  -db="default": DataBase alias name
  -force=false: drop tables before create
  -v=false: verbose info

使用 -force=1 可以 drop table 后再建表

使用 -v 可以查看执行的 sql 语句

---

在程序中直接调用自动建表：

// 数据库别名
name := "default"

// drop table 后再建表
force := true

// 打印执行过程
verbose := true

// 遇到错误立即返回
err := orm.RunSyncdb(name, force, verbose)
if err != nil {
    fmt.Println(err)
}

自动建表功能在非 force 模式下，是会自动创建新增加的字段的。也会创建新增加的索引。

对于改动过的旧字段，旧索引，需要用户自行进行处理。

我们收到有一些 issue，提及希望我们能够支持删除字段，或者修改字段的定义。目前来说，我们并不考虑支持这一类的功能。
这主要是从风险角度考虑。和增加字段比起来，删除这种操作要危险得多，并且难以恢复。所以我们并不是很愿意暴露这种功能。

打印建表SQL

./main orm sqlall -h
Usage of orm command: syncdb:
  -db="default": DataBase alias name

默认使用别名为 default 的数据库。

测试用例

ORM Test

测试代码参见

• 表定义 models_test.go
• 测试用例 orm_test.go

MySQL

mysql -u root -e 'create database orm_test;'
export ORM_DRIVER=mysql
export ORM_SOURCE="root:@/orm_test?charset=utf8"
go test -v github.com/beego/beego/v2/core/client/orm

Sqlite3

touch /path/to/orm_test.db
export ORM_DRIVER=sqlite3
export ORM_SOURCE=/path/to/orm_test.db
go test -v github.com/beego/beego/v2/core/client/orm

PostgreSQL

psql -c 'create database orm_test;' -U postgres
export ORM_DRIVER=postgres
export ORM_SOURCE="user=postgres dbname=orm_test sslmode=disable"
go test -v github.com/beego/beego/v2/core/client/orm

自定义字段

Custom Fields

TypeBooleanField = 1 << iota

// string
TypeCharField

// string
TypeTextField

// time.Time
TypeDateField
// time.Time
TypeDateTimeField

// int16
TypeSmallIntegerField
// int32
TypeIntegerField
// int64
TypeBigIntegerField
// uint16
TypePositiveSmallIntegerField
// uint32
TypePositiveIntegerField
// uint64
TypePositiveBigIntegerField

// float64
TypeFloatField
// float64
TypeDecimalField

RelForeignKey
RelOneToOne
RelManyToMany
RelReverseOne
RelReverseMany