目录:

GORM （一）

GORM （一）

The fantastic ORM library for Golang aims to be developer friendly.

对Go开发者友好的优秀ORM库。

特性

全功能 ORM
关联 (Has One，Has Many，Belongs To，Many To Many，多态，单表继承)
Create，Save，Update，Delete，Find 中钩子方法
支持 Preload、Joins 的预加载
事务，嵌套事务，Save Point，Rollback To Saved Point
Context、预编译模式、DryRun 模式
批量插入，FindInBatches，Find/Create with Map，使用 SQL 表达式、Context Valuer 进行 CRUD
SQL 构建器，Upsert，数据库锁，Optimizer/Index/Comment Hint，命名参数，子查询
复合主键，索引，约束
Auto Migration
自定义 Logger
灵活的可扩展插件 API：Database Resolver（多数据库，读写分离）、Prometheus…
每个特性都经过了测试的重重考验
开发者友好

快速入门

安装

# 旧版GO
go get -u gorm.io/gorm
go get -u gorm.io/driver/sqlite
# 新版GO
go install  gorm.io/gorm@latest  
go install  gorm.io/driver/sqlite@latest

新建main.go

package main
import (
  "gorm.io/gorm"
  "gorm.io/driver/sqlite"
)
type Product struct {
  gorm.Model
  Code  string
  Price uint
}
func main() {
  db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})
  if err != nil {
    panic("failed to connect database")
  }
  // 迁移 schema
  db.AutoMigrate(&Product{})
  // Create
  db.Create(&Product{Code: "D42", Price: 100})
  // Read
  var product Product
  db.First(&product, 1) // 根据整型主键查找
  db.First(&product, "code = ?", "D42") // 查找 code 字段值为 D42 的记录
  // Update - 将 product 的 price 更新为 200
  db.Model(&product).Update("Price", 200)
  // Update - 更新多个字段
  db.Model(&product).Updates(Product{Price: 200, Code: "F42"}) // 仅更新非零值字段
  db.Model(&product).Updates(map[string]interface{}{"Price": 200, "Code": "F42"})
  // Delete - 删除 product
  db.Delete(&product, 1)
}

# 执行代码
go mod init
go mod tidy  
go run main.go

声明模型

约定

GORM 倾向于约定，而不是配置。默认情况下，GORM 使用 ID 作为主键，使用结构体名的 蛇形复数 作为表名，字段名的 蛇形 作为列名，并使用 CreatedAt、UpdatedAt 字段追踪创建、更新时间

gorm.Model

GORM 定义一个 gorm.Model 结构体，其包括字段 ID、CreatedAt、UpdatedAt、DeletedAt

// gorm.Model的定义
type Model struct {
    ID         uint           `gorm:primaryKey`
    CreatedAt  time.Time 
    UpdatedAt  time.Time 
    DeletedAt  gorm.DeletedAt  `gorm:"index"`
}

高级选项

字段级权限控制

可导出的字段在使用 GORM 进行 CRUD 时拥有全部的权限，此外，GORM 允许您用标签控制字段级别的权限。这样您就可以让一个字段的权限是只读、只写、只创建、只更新或者被忽略

type User struct {
  Name string `gorm:"<-:create"` // 允许读取和创建
  Name string `gorm:"<-:update"` // 允许读取和更新
  Name string `gorm:"<-"`        // 允许读写(创建和更新)update)
  Name string `gorm:"<-:false"`  // 允许读取，禁用写入权限permission
  Name string `gorm:"->"`        // 只读（除非已配置，否则禁用写入权限）
  Name string `gorm:"->;<-:create"` // 允许读取和创建
  Name string `gorm:"->:false;<-:create"` // 仅创建（禁用从数据库读取）
  Name string `gorm:"-"`            // 使用结构写入和读取时忽略此字段
  Name string `gorm:"-:all"`        // 使用struct写入、读取和迁移时忽略此字段
  Name string `gorm:"-:migration"`  // 使用结构迁移时忽略此字段
}

创建/更新时间追踪（纳秒、毫秒、秒、Time）

GORM 约定使用 CreatedAt、UpdatedAt 追踪创建/更新时间。如果您定义了这种字段，GORM 在创建、更新时会自动填充当前时间

要使用不同名称的字段，您可以配置 autoCreateTime、autoUpdateTime 标签

如果您想要保存 UNIX（毫/纳）秒时间戳，而不是 time，您只需简单地将 time.Time 修改为 int 即可

type User struct{
    CreatedAt   time.Time // 在创建时，如果该字段值为零值，则使用当前时间填充
    UpdatedAt   int       // 在创建时该字段值为零值或者在更新时，使用当前时间戳秒数填充
    Updated   int64 `gorm:"autoUpdateTime:nano"` // 使用时间戳填纳秒数充更新时间
    Updated   int64 `gorm:"autoUpdateTime:milli"` // 使用时间戳毫秒数填充更新时间
    Created   int64 `gorm:"autoCreateTime"`      // 使用时间戳秒数填充创建时间
}

嵌入结构体

对于匿名字段，GORM 会将其字段包含在父结构体中，例如：

type User struct {
  gorm.Model
  Name string
}
// 等效于
type User struct {
  ID        uint           `gorm:"primaryKey"`
  CreatedAt time.Time
  UpdatedAt time.Time
  DeletedAt gorm.DeletedAt `gorm:"index"`
  Name string
}

对于正常的结构体字段，你也可以通过标签 embedded 将其嵌入，例如：

type Author struct {
    Name  string
    Email string
}

type Blog struct {
  ID      int
  Author  Author `gorm:"embedded"`  // embedded 是嵌入的意思
  Upvotes int32
}

// 等效于
type Blog struct {
  ID    int64
  Name  string
  Email string
  Upvotes  int32
}

并且，您可以使用标签 embeddedPrefix 来为 db 中的字段名添加前缀，例如：

type Blog struct {
  ID      int
  Author  Author `gorm:"embedded;embeddedPrefix:author_"`
  Upvotes int32
}
// 等效于
type Blog struct {
  ID          int64
  AuthorName  string
  AuthorEmail string
  Upvotes     int32
}

字段标签

声明 model 时，tag 是可选的，GORM 支持以下 tag： tag 名大小写不敏感，但建议使用 camelCase 风格

标签名	说明
column	指定 db 列名
type	列数据类型，推荐使用兼容性好的通用类型，例如：所有数据库都支持 bool、int、uint、float、string、time、bytes 并且可以和其他标签一起使用，例如：`not null`、`size`, `autoIncrement`… 像 `varbinary(8)` 这样指定数据库数据类型也是支持的。在使用指定数据库数据类型时，它需要是完整的数据库数据类型，如：`MEDIUMINT UNSIGNED not NULL AUTO_INCREMENT`
serializer	指定如何将数据序列化和反序列化为db的序列化程序，例如: `serializer:json/gob/unixtime`
size	指定列数据大小/长度，例如: `size:256`
primaryKey	将列指定为主键
unique	将列指定为唯一列
default	指定列默认值
precision	指定列精度
scale	指定列比例
not null	将列指定为非NULL
autoIncrement	指定列可自动递增
autoIncrementIncrement	自动递增步长，控制连续列值之间的间隔
embedded	嵌入字段
embeddedPrefix	嵌入字段的列名前缀
autoCreateTime	跟踪当前时间创建时，对于int字段，它将跟踪unix秒，使用值nano/milli跟踪unix nano/milli秒，例如: `autoCreateTime:nano`
autoUpdateTime	创建/更新时跟踪当前时间，对于int字段，它将跟踪unix秒，使用值nano/milli跟踪unix nano/milli秒，例如: `autoUpdateTime:milli`
index	使用选项创建索引，对多个字段使用相同的名称创建复合索引
uniqueIndex	与索引相同，但创建唯一索引
check	创建检查约束，例如：检查：年龄>13，参考约束
<-	设置字段的写入权限，<-：仅创建字段，<-：仅更新字段，<-：false无写入权限，<-创建和更新权限
->	设置字段的读取权限，->：false无读取权限
-	忽略此字段，-无读/写权限，-：迁移无迁移权限，-：全部无读/写/迁移权限
comment	迁移时为字段添加注释

关联标签

GORM 允许通过标签为关联配置外键、约束、many2many 表.

连接到数据库

GORM 官方支持的数据库类型有： MySQL, PostgreSQL, SQlite, SQL Server

MySQL

go install  gorm.io/driver/mysql@latest

import (
  "gorm.io/driver/mysql"
  "gorm.io/gorm"
)
func main() {
  // 参考 https://github.com/go-sql-driver/mysql#dsn-data-source-name 获取详情
  dsn := "用户名:密码@tcp(127.0.0.1:3306)/库名?charset=utf8mb4&parseTime=True&loc=Local"
  db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
  if err != nil {
    panic("failed to connect database")
  }
}

 go mod tidy
 go run .\main.go

package main

import (
    "fmt"

    "gorm.io/driver/mysql"
    "gorm.io/gorm"
)

type UserInfo struct {
    ID     uint
    Name   string
    Gender string
    Hobby  string
}

func main() {
    // 参考 https://github.com/go-sql-driver/mysql#dsn-data-source-name 获取详情
    dsn := "root:root123@tcp(127.0.0.1:3306)/testdb?charset=utf8mb4&parseTime=True&loc=Local"
    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
    if err != nil {
        panic("failed to connect database")
    }
    // 自动迁移
    db.AutoMigrate(&UserInfo{})

    u1 := UserInfo{1, "鸣人", "男", "篮球"}
    u2 := UserInfo{2, "小樱", "女", "跳舞"}
    // 创建记录
    db.Create(&u1)
    db.Create(&u2)
    // 查询
    var u = new(UserInfo)
    db.First(u)
    fmt.Printf("%#v\n", u)
    var uu UserInfo
    db.Find(&uu, "hobby=?", "跳舞")
    fmt.Printf("%#v\n", uu)
    // 更新
    db.Model(&u).Update("hobby", "唱歌")
    // 删除
    db.Delete(&u)
}

CRUD

创建记录

user := User{Name: "张三", Age: 18, Birthday: time.Now()}
result := db.Create(&user)           // 通过数据的指针来创建
user.ID                              // 返回插入数据的主键
result.Error                         // 返回 error
result.RowsAffected                  // 返回插入记录的条数

用指定的字段创建记录

创建记录并更新给出的字段。

user := User{Name: "李四", Age: 18, Birthday: "2020-07-04 11:05:21.775"}
db.Select("Name", "Age", "CreatedAt").Create(&user)
// INSERT INTO `users` (`name`,`age`,`created_at`) VALUES ("李四", 18, "2020-07-04 11:05:21.775")

创建一个记录且一同忽略传递给略去的字段值。

db.Omit("Name", "Age", "CreatedAt").Create(&user)
// INSERT INTO `users` (`birthday`,`updated_at`) VALUES ("2020-01-01 00:00:00.000", "2020-07-04 11:05:21.775")

批量插入

要有效地插入大量记录，请将一个 slice 传递给 Create 方法。 GORM 将生成单独一条SQL语句来插入所有数据，并回填主键的值，钩子方法也会被调用。

var users = []User{{Name: "user1"}, {Name: "user2"}, {Name: "user3"}}
db.Create(&users)
for _, user := range users {
  user.ID // 1,2,3
}

使用 CreateInBatches 分批创建时，你可以指定每批的数量，例如：

var users = []User{{name: "tianlang_1"}, ...., {Name: "tianlang_10000"}}
// 数量为 100
db.CreateInBatches(users, 100)

Upsert 和 Create With Associations 也支持批量插入

注意使用CreateBatchSize 选项初始化 GORM 时，所有的创建& 关联 INSERT 都将遵循该选项

db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{
  CreateBatchSize: 1000,
})
db := db.Session(&gorm.Session{CreateBatchSize: 1000})

users = [5000]User{{Name: "user", Pets: []Pet{pet1, pet2, pet3}}...}

db.Create(&users)
// INSERT INTO users xxx (5 batches)
// INSERT INTO pets xxx (15 batches)

创建钩子

GORM 允许用户定义的钩子有 BeforeSave, BeforeCreate, AfterSave, AfterCreate 创建记录时将调用这些钩子方法。

func (u *User) BeforeCreate(tx *gorm.DB) (err error) {
  u.UUID = uuid.New()
  if u.Role == "admin" {
        return errors.New("invalid role")
    }
    return
}

如果您想跳过 钩子 方法，您可以使用 SkipHooks 会话模式，例如：

DB.Session(&gorm.Session{SkipHooks: true}).Create(&user)
DB.Session(&gorm.Session{SkipHooks: true}).Create(&users)
DB.Session(&gorm.Session{SkipHooks: true}).CreateInBatches(users, 100)

根据 Map 创建

GORM 支持根据 map[string]interface{} 和 []map[string]interface{}{} 创建记录，例如：

db.Model(&User{}).Create(map[string]interface{}{
  "Name": "tianlang", "Age": 18,
})
// batch insert from `[]map[string]interface{}{}`
db.Model(&User{}).Create([]map[string]interface{}{
  {"Name": "user_1", "Age": 18},
  {"Name": "user_2", "Age": 20},
})

注意： 根据 map 创建记录时，association 不会被调用，且主键也不会自动填充

使用 SQL 表达式、Context Valuer 创建记录

GORM 允许使用 SQL 表达式插入数据，有两种方法实现这个目标。根据 map[string]interface{} 或自定义数据类型创建，例如：

// 通过 map 创建记录
db.Model(User{}).Create(map[string]interface{}{
  "Name": "user1",
  "Location": clause.Expr{SQL: "ST_PointFromText(?)", Vars: []interface{}{"POINT(100 100)"}},
})
// INSERT INTO `users` (`name`,`location`) VALUES ("tianlang",ST_PointFromText("POINT(100 100)"));
// 通过自定义类型创建记录
type Location struct {
    X, Y int
}
// Scan 方法实现了 sql.Scanner 接口
func (loc *Location) Scan(v interface{}) error {
  // Scan a value into struct from database driver
}
func (loc Location) GormDataType() string {
  return "geometry"
}
func (loc Location) GormValue(ctx context.Context, db *gorm.DB) clause.Expr {
  return clause.Expr{
    SQL:  "ST_PointFromText(?)",
    Vars: []interface{}{fmt.Sprintf("POINT(%d %d)", loc.X, loc.Y)},
  }
}
type User struct {
  Name     string
  Location Location
}
db.Create(&User{
  Name:     "user1",
  Location: Location{X: 100, Y: 100},
})
// INSERT INTO `users` (`name`,`location`) VALUES ("tianlang",ST_PointFromText("POINT(100 100)"))

高级选项

关联创建

创建关联数据时，如果关联值是非零值，这些关联会被 upsert，且它们的 Hook 方法也会被调用

type CreditCard struct {
  gorm.Model
  Number   string
  UserID   uint
}

type User struct {
  gorm.Model
  Name       string
  CreditCard CreditCard
}

db.Create(&User{
  Name: "user01",
  CreditCard: CreditCard{Number: "18888888888"}
})

// INSERT INTO `users` ...
// INSERT INTO `credit_cards` ...

您也可以通过 Select、 Omit 跳过关联保存，例如：

db.Omit("CreditCard").Create(&user)
// 跳过所有关联
db.Omit(clause.Associations).Create(&user)

默认值

您可以通过标签 default 为字段定义默认值，如：

type User struct {
  ID   int64
  Name string `gorm:"default:galeone"`
  Age  int64  `gorm:"default:18"`
}

插入记录到数据库时，默认值 会被用于 填充值为零值的字段

注意对于声明了默认值的字段，像 0、''、false 等零值是不会保存到数据库。您需要使用指针类型或 Scanner/Valuer 来避免这个问题，例如：

type User struct {
  gorm.Model
  Name string
  Age  *int           `gorm:"default:18"`
  Active sql.NullBool `gorm:"default:true"`
}

注意若要数据库有默认、虚拟/生成的值，你必须为字段设置 default 标签。若要在迁移时跳过默认值定义，你可以使用 default:(-)，例如：

type User struct {
  ID        string `gorm:"default:uuid_generate_v3()"` // db func
  FirstName string
  LastName  string
  Age       uint8
  FullName  string `gorm:"->;type:GENERATED ALWAYS AS (concat(firstname,' ',lastname));default:(-);"`
}

使用虚拟/生成的值时，你可能需要禁用它的创建、更新权限，查看字段级权限获取详情

Upsert 及冲突

GORM 为不同数据库提供了兼容的 Upsert 支持

import "gorm.io/gorm/clause"
// 在冲突时，什么都不做
db.Clauses(clause.OnConflict{DoNothing: true}).Create(&user)
// 在`id`冲突时，将列更新为默认值
db.Clauses(clause.OnConflict{
  Columns:   []clause.Column{{Name: "id"}},
  DoUpdates: clause.Assignments(map[string]interface{}{"role": "user"}),
}).Create(&users)
// MERGE INTO "users" USING *** WHEN NOT MATCHED THEN INSERT *** WHEN MATCHED THEN UPDATE SET ***; SQL Server
// INSERT INTO `users` *** ON DUPLICATE KEY UPDATE ***; MySQL
// 使用SQL语句
db.Clauses(clause.OnConflict{
  Columns:   []clause.Column{{Name: "id"}},
  DoUpdates: clause.Assignments(map[string]interface{}{"count": gorm.Expr("GREATEST(count, VALUES(count))")}),
}).Create(&users)
// INSERT INTO `users` *** ON DUPLICATE KEY UPDATE `count`=GREATEST(count, VALUES(count));
// 在`id`冲突时，将列更新为新值
db.Clauses(clause.OnConflict{
  Columns:   []clause.Column{{Name: "id"}},
  DoUpdates: clause.AssignmentColumns([]string{"name", "age"}),
}).Create(&users)
// MERGE INTO "users" USING *** WHEN NOT MATCHED THEN INSERT *** WHEN MATCHED THEN UPDATE SET "name"="excluded"."name"; SQL Server
// INSERT INTO "users" *** ON CONFLICT ("id") DO UPDATE SET "name"="excluded"."name", "age"="excluded"."age"; PostgreSQL
// INSERT INTO `users` *** ON DUPLICATE KEY UPDATE `name`=VALUES(name),`age=VALUES(age); MySQL
// 在冲突时，更新除主键以外的所有列到新值。
db.Clauses(clause.OnConflict{
  UpdateAll: true,
}).Create(&users)
// INSERT INTO "users" *** ON CONFLICT ("id") DO UPDATE SET "name"="excluded"."name", "age"="excluded"."age", ...;

查询

检索单个对象

GORM 提供了 First、Take、Last 方法，以便从数据库中检索单个对象。当查询数据库时它添加了 LIMIT 1 条件，且没有找到记录时，它会返回 ErrRecordNotFound 错误

// 获取第一条记录（主键升序）
db.First(&user)
// select * from users order by id limit 1;

// 获取第一条记录，不指定排序
db.Take(&user)
// select * from users limit 1;

// 获取最后一条记录（主键降序）
db.Last(&user)
// select * from users order by id desc limit 1;

result := db.First(&user)
result.RowsAffected // 返回找到的记录
result.Error        // 返回错误或nil

// 检查 ErrRecordNotFound 错误
error.Is(result.Error,gorm.ErroRecorNotFound)

如果你想避免ErrRecordNotFound错误，你可以使用Find，比如db.Limit(1).Find(&user)，Find方法可以接受struct和slice的数据。

First 和 Last 会根据主键排序，分别查询第一条和最后一条记录。只有在目标 struct 是指针或者通过 db.Model() 指定 model 时，该方法才有效。此外，如果相关 model 没有定义主键，那么将按 model 的第一个字段进行排序。例如:

var user User
var users []User


result := map[string]interface{}{}
db.Model(&User{}).First(&result)

result := map[string] interface{}{}

db.Model(&User{}).First(&result)

db.Table("users").First(&result)

type Language struct{
    Code string
    Name string
}

db.First(&Language)

用主键检索

如果主键是数字类型，您可以使用内联条件来检索对象。传入字符串参数时，需要特别注意 SQL 注入问题，查看安全获取详情.

db.First(&user, 10)
// SELECT * FROM users WHERE id = 10;

db.First(&user, "10")
// SELECT * FROM users WHERE id = 10;

db.Find(&users, []int{1,2,3})
// SELECT * FROM users WHERE id IN (1,2,3);

如果主键是字符串（例如像 uuid），查询将被写成这样：

db.First(&user, "id = ?", "1b74413f-f3b8-409f-ac47-e8c062e3472a")
// SELECT * FROM users WHERE id = "1b74413f-f3b8-409f-ac47-e8c062e3472a";

当目标对象具有主键值时，主键将用于构建条件，例如:

var user = User{ID: 10}
db.First(&user)
// select * from users where id = 10;

var result User
db.Model(User{ID:10}).First(&result)
// select * from users where id = 10;

检索全部对象

// Get all records
result := db.Find(&users)

// SELECT * FROM users;
result.RowsAffected // returns found records count, equals `len(users)`

result.Error        // returns error

条件

String 条件

// Get first matched record
db.Where("name = ?","user1").First(&user)
// select * from users where name = 'user1' order by id limit 1;


// Get all metched records
db.Where("name <> ?","user1").Find(&user)
// select * from users where name <> "user1";


// IN
db.Where("name IN ?",[]string{"user1","user2"}).Find(&users)


// LIKE
db.Where("name LIKE ?","%us%").Find(&users)
// select * from users where like "%us%";


// AND
db.Where("name =? AND age >= ?","user1","22").Find(&users)
// select * from users where name = "user1" and age >=22;


// Time
db.Where("updated_at > ?",lastWeek).Find(&users)
// SELECT * FROM users WHERE updated_at > '2000-01-01 00:00:00';


// BETWEEN
db.Where("created_at BETWEEN ? AND ?", lastWeek,today).Find(&users)
// SELECT * FROM users WHERE created_at BETWEEN '2000-01-01 00:00:00' AND '2000-01-08 00:00:00';

Struct & Map 条件

// Struct
db.Where(&User{Name:"user1",Age:20}).First(&user)
// select * from users name = "user" and age = 20 order by id   limit 1;

// Map
db.Where(map[string]interface{}{"name":"user1","age":20}).Find(&users)
// SELECT * FROM users WHERE name = "tianlang" AND age = 20;

// Slice of primary keys
db.Where([]int64{20, 21, 22}).Find(&users)
// SELECT * FROM users WHERE id IN (20, 21, 22);

注意：当使用struct进行查询时，GORM将仅使用非零字段进行查询，这意味着如果字段的值为0、、false或其他零值，则不会使用它来构建查询条件，例如：

db.Where(&User{Name: "tianlang", Age: 0}).Find(&users)
// SELECT * FROM users WHERE name = "tianlang";

要在查询条件中包含零值，可以使用映射，该映射将包含所有键值作为查询条件，例如：

db.Where(map[string]interface{}{"Name": "tianlang", "Age": 0}).Find(&users)
// SELECT * FROM users WHERE name = "tianlang" AND age = 0;

指定结构体查询字段

使用struct搜索时，可以通过将相关字段名或dbname传递到Where（）来指定在查询条件中使用结构中的哪些特定值，例如：

db.Where(&User{Name:"user"},"name","Age").Find(&users)
// select * from users where name = "user" and age = 0;


db.Where(&User{Name:"user"},"Age").Find(&users)
// select * from users where age = 0

内联条件

查询条件可以以与Where类似的方式内联到First和Find等方法中。

// Get by primary key if it were a non-integer type
db.First(&user, "id = ?", "string_primary_key")
// SELECT * FROM users WHERE id = 'string_primary_key';
// Plain SQL
db.Find(&user, "name = ?", "tianlang")
// SELECT * FROM users WHERE name = "tianlang";
db.Find(&users, "name <> ? AND age > ?", "tianlang", 20)
// SELECT * FROM users WHERE name <> "tianlang" AND age > 20;
// Struct
db.Find(&users, User{Age: 20})
// SELECT * FROM users WHERE age = 20;
// Map
db.Find(&users, map[string]interface{}{"age": 20})
// SELECT * FROM users WHERE age = 20;

Not 条件

db.Not("name = ?", "tianlang").First(&user)
// SELECT * FROM users WHERE NOT name = "tianlang" ORDER BY id LIMIT 1;
// Not In
db.Not(map[string]interface{}{"name": []string{"tianlang", "tianlang 2"}}).Find(&users)
// SELECT * FROM users WHERE name NOT IN ("tianlang", "tianlang 2");
// Struct
db.Not(User{Name: "tianlang", Age: 18}).First(&user)
// SELECT * FROM users WHERE name <> "tianlang" AND age <> 18 ORDER BY id LIMIT 1;
// Not In slice of primary keys
db.Not([]int64{1,2,3}).First(&user)
// SELECT * FROM users WHERE id NOT IN (1,2,3) ORDER BY id LIMIT 1;

Or 条件

db.Where("role = ?", "admin").Or("role = ?", "super_admin").Find(&users)
// SELECT * FROM users WHERE role = 'admin' OR role = 'super_admin';
// Struct
db.Where("name = 'jinzhu'").Or(User{Name: "jinzhu 2", Age: 18}).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' OR (name = 'jinzhu 2' AND age = 18);
// Map
db.Where("name = 'jinzhu'").Or(map[string]interface{}{"name": "jinzhu 2", "age": 18}).Find(&users)
// SELECT * FROM users WHERE name = 'jinzhu' OR (name = 'jinzhu 2' AND age = 18);

选择特定字段

db.Select("name", "age").Find(&users)
// SELECT name, age FROM users;
db.Select([]string{"name", "age"}).Find(&users)
// SELECT name, age FROM users;
db.Table("users").Select("COALESCE(age,?)", 42).Rows()
// SELECT COALESCE(age,'42') FROM users;

Order

db.Order("age desc, name").Find(&users)
// SELECT * FROM users ORDER BY age desc, name;
// Multiple orders
db.Order("age desc").Order("name").Find(&users)
// SELECT * FROM users ORDER BY age desc, name;
db.Clauses(clause.OrderBy{
  Expression: clause.Expr{SQL: "FIELD(id,?)", Vars: []interface{}{[]int{1, 2, 3}}, WithoutParentheses: true},
}).Find(&User{})
// SELECT * FROM users ORDER BY FIELD(id,1,2,3)

Limit & Offset

限制指定要检索的最大记录数偏移量指定开始返回记录之前要跳过的记录数

db.Limit(3).Find(&users)
// SELECT * FROM users LIMIT 3;
// Cancel limit condition with -1
db.Limit(10).Find(&users1).Limit(-1).Find(&users2)
// SELECT * FROM users LIMIT 10; (users1)
// SELECT * FROM users; (users2)
db.Offset(3).Find(&users)
// SELECT * FROM users OFFSET 3;
db.Limit(10).Offset(5).Find(&users)
// SELECT * FROM users OFFSET 5 LIMIT 10;
// Cancel offset condition with -1
db.Offset(10).Find(&users1).Offset(-1).Find(&users2)
// SELECT * FROM users OFFSET 10; (users1)
// SELECT * FROM users; (users2)

Group By & Having

type result struct {
  Date  time.Time
  Total int
}
db.Model(&User{}).Select("name, sum(age) as total").Where("name LIKE ?", "group%").Group("name").First(&result)

// SELECT name, sum(age) as total FROM `users` WHERE name LIKE "group%" GROUP BY `name` LIMIT 1


db.Model(&User{}).Select("name, sum(age) as total").Group("name").Having("name = ?", "group").Find(&result)

// SELECT name, sum(age) as total FROM `users` GROUP BY `name` HAVING name = "group"


rows, err := db.Table("orders").Select("date(created_at) as date, sum(amount) as total").Group("date(created_at)").Rows()
defer rows.Close()
for rows.Next() {
  ...
}


rows, err := db.Table("orders").Select("date(created_at) as date, sum(amount) as total").Group("date(created_at)").Having("sum(amount) > ?", 100).Rows()
defer rows.Close()
for rows.Next() {
  ...
}


type Result struct {
  Date  time.Time
  Total int64
}


db.Table("orders").Select("date(created_at) as date, sum(amount) as total").Group("date(created_at)").Having("sum(amount) > ?", 100).Scan(&results)

Distinct

db.Distinct("name", "age").Order("name, age desc").Find(&results)

Joins

type result struct {
  Name  string
  Email string
}

db.Model(&User{}).Select("users.name, emails.email").Joins("left join emails on emails.user_id = users.id").Scan(&result{})

// SELECT users.name, emails.email FROM `users` left join emails on emails.user_id = users.id

rows, err := db.Table("users").Select("users.name, emails.email").Joins("left join emails on emails.user_id = users.id").Rows()
for rows.Next() {
  ...
}

db.Table("users").Select("users.name, emails.email").Joins("left join emails on emails.user_id = users.id").Scan(&results)

// multiple joins with parameter
db.Joins("JOIN emails ON emails.user_id = users.id AND emails.email = ?", "admin@example.org").Joins("JOIN credit_cards ON credit_cards.user_id = users.id").Where("credit_cards.number = ?", "411111111111").Find(&user)

Joins 预加载

db.Joins("Company").Find(&users)
// SELECT `users`.`id`,`users`.`name`,`users`.`age`,`Company`.`id` AS `Company__id`,`Company`.`name` AS `Company__name` FROM `users` LEFT JOIN `companies` AS `Company` ON `users`.`company_id` = `Company`.`id`;


db.Joins("Company", DB.Where(&Company{Alive: true})).Find(&users)
// SELECT `users`.`id`,`users`.`name`,`users`.`age`,`Company`.`id` AS `Company__id`,`Company`.`name` AS `Company__name` FROM `users` LEFT JOIN `companies` AS `Company` ON `users`.`company_id` = `Company`.`id` AND `Company`.`alive` = true;

Joins a Derived Table

type User struct {
    Id  int
    Age int
}

type Order struct {
    UserId     int
    FinishedAt *time.Time
}

query := db.Table("order").Select("MAX(order.finished_at) as latest").Joins("left join user user on order.user_id = user.id").Where("user.age > ?", 18).Group("order.user_id")

db.Model(&Order{}).Joins("join (?) q on order.finished_at = q.latest", query).Scan(&results)

// SELECT `order`.`user_id`,`order`.`finished_at` FROM `order` join (SELECT MAX(order.finished_at) as latest FROM `order` left join user user on order.user_id = user.id WHERE user.age > 18 GROUP BY `order`.`user_id`) q on order.finished_at = q.latest

Scan

type Result struct {
  Name string
  Age  int
}

var result Result

db.Table("users").Select("name", "age").Where("name = ?", "Antonio").Scan(&result)

// Raw SQL
db.Raw("SELECT name, age FROM users WHERE name = ?", "Antonio").Scan(&result)

高级查询

智能选择字段

GORM 允许通过 Select 方法选择特定的字段，如果您在应用程序中经常使用此功能，你也可以定义一个较小的结构体，以实现调用 API 时自动选择特定的字段，例如：

type User struct {  
    ID     uint
    Name   string
    Age    int
    Gender string  
    // 假设后面还有几百个字段
...}

type APIUser struct {
    ID   uint
    Name string
}

// 查询时会自动选择 `id`, `name` 字段
db.Model(&User{}).Limit(10).Find(&APIUser{})

// SELECT `id`, `name` FROM `users` LIMIT 10

注意 QueryFields 模式会根据当前 model 的所有字段名称进行 select。

db, err := gorm.Open(
    sqlite.Open("gorm.db"), 
    &gorm.Config{  QueryFields: true,})

db.Find(&user) 
// SELECT `users`.`name`, `users`.`age`, ... FROM `users` 
// 带上这个选项
// Session 
Modedb.Session(&gorm.Session{QueryFields: true}).Find(&user)
// SELECT `users`.`name`, `users`.`age`, ... FROM `users`

Locking (FOR UPDATE)

GORM 支持多种类型的锁，例如：

db.Clauses(clause.Locking{Strength: "UPDATE"}).Find(&users)

// SELECT * FROM `users` FOR UPDATE

db.Clauses(clause.Locking{  Strength: "SHARE",  Table: clause.Table{Name: clause.CurrentTable},}).Find(&users)
// SELECT * FROM `users` FOR SHARE OF `users`

db.Clauses(clause.Locking{  Strength: "UPDATE",  Options: "NOWAIT",}).Find(&users)
// SELECT * FROM `users` FOR UPDATE NOWAIT

查看原生 SQL 及构造器获取详情

子查询

子查询可以嵌套在查询中，GORM 允许在使用 *gorm.DB 对象作为参数时生成子查询

db.Where("amount > (?)", db.Table("orders").Select("AVG(amount)")).Find(&orders)

// SELECT * FROM "orders" WHERE amount > (SELECT AVG(amount) FROM "orders");

subQuery := db.Select("AVG(age)").Where("name LIKE ?", "name%").Table("users")db.Select("AVG(age) as avgage").Group("name").Having("AVG(age) > (?)", subQuery).Find(&results)

// SELECT AVG(age) as avgage FROM `users` GROUP BY `name` HAVING AVG(age) > (SELECT AVG(age) FROM `users` WHERE name LIKE "name%")

From 子查询

GORM 允许您在 Table 方法中通过 FROM 子句使用子查询，例如：

db.Table("(?) as u", db.Model(&User{}).Select("name", "age")).Where("age = ?", 18}).Find(&User{})
// SELECT * FROM (SELECT `name`,`age` FROM `users`) as u WHERE `age` = 18

subQuery1 := db.Model(&User{}).Select("name")
subQuery2 := db.Model(&Pet{}).Select("name")db.Table("(?) as u, (?) as p", subQuery1, subQuery2).Find(&User{})
// SELECT * FROM (SELECT `name` FROM `users`) as u, (SELECT `name` FROM `pets`) as p

Group 条件

使用 Group 条件可以更轻松的编写复杂 SQL

db.Where(
    db.Where("pizza = ?", "pepperoni")
      .Where(db.Where("size = ?", "small")
      .Or("size = ?", "medium")),)
      .Or(db.Where("pizza = ?", "hawaiian")
            .Where("size = ?", "xlarge"),)
      .Find(&Pizza{}).Statement

// SELECT * FROM `pizzas` WHERE (pizza = "pepperoni" AND (size = "small" OR size = "medium")) OR (pizza = "hawaiian" AND size = "xlarge")

带多个列的 In

带多个列的 In 查询

db.Where("(name, age, role) IN ?", [][]interface{}{{"jinzhu", 18, "admin"}, {"jinzhu2", 19, "user"}}).Find(&users)

// SELECT * FROM users WHERE (name, age, role) IN (("jinzhu", 18, "admin"), ("jinzhu 2", 19, "user"));

命名参数

GORM 支持 sql.NamedArg 和 map[string]interface{}{} 形式的命名参数，例如：

db.Where("name1 = @name OR name2 = @name", sql.Named("name", "jinzhu")).Find(&user)

// SELECT * FROM `users` WHERE name1 = "jinzhu" OR name2 = "jinzhu"

db.Where("name1 = @name OR name2 = @name", map[string]interface{}{"name": "jinzhu"}).First(&user)

// SELECT * FROM `users` WHERE name1 = "jinzhu" OR name2 = "jinzhu" ORDER BY `users`.`id` LIMIT 1

Find 至 map

GORM 允许扫描结果至 map[string]interface{} 或 []map[string]interface{}，此时别忘了指定 Model 或 Table，例如：

result := map[string]interface{}{}db.Model(&User{}).First(&result, "id = ?", 1)
var results []map[string]interface{}db.Table("users").Find(&results)

FirstOrInit

获取第一条匹配的记录，或者根据给定的条件初始化一个实例（仅支持 sturct 和 map 条件）

// 未找到 user，则根据给定的条件初始化一条记录
db.FirstOrInit(&user, User{Name: "non_existing"})
// user -> User{Name: "non_existing"}
// 找到了 `name` = `jinzhu` 的 
userdb.Where(User{Name: "jinzhu"}).FirstOrInit(&user)
// user -> User{ID: 111, Name: "Jinzhu", Age: 18}
// 找到了 `name` = `jinzhu` 的 
userdb.FirstOrInit(&user, map[string]interface{}{"name": "jinzhu"})
// user -> User{ID: 111, Name: "Jinzhu", Age: 18}

如果没有找到记录，可以使用包含更多的属性的结构体初始化 user，Attrs 不会被用于生成查询 SQL

// 未找到 user，则根据给定的条件以及 Attrs 初始化 
userdb.Where(User{Name: "non_existing"}).Attrs(User{Age: 20}).FirstOrInit(&user)
// SELECT * FROM USERS WHERE name = 'non_existing' ORDER BY id LIMIT 1;
// user -> User{Name: "non_existing", Age: 20}
// 未找到 user，则根据给定的条件以及 Attrs 初始化 
userdb.Where(User{Name: "non_existing"}).Attrs("age", 20).FirstOrInit(&user)
// SELECT * FROM USERS WHERE name = 'non_existing' ORDER BY id LIMIT 1;
// user -> User{Name: "non_existing", Age: 20}
// 找到了 `name` = `jinzhu` 的 user，则忽略 
Attrsdb.Where(User{Name: "Jinzhu"}).Attrs(User{Age: 20}).FirstOrInit(&user)
// SELECT * FROM USERS WHERE name = jinzhu' ORDER BY id LIMIT 1;
// user -> User{ID: 111, Name: "Jinzhu", Age: 18}

不管是否找到记录，Assign 都会将属性赋值给 struct，但这些属性不会被用于生成查询 SQL，也不会被保存到数据库

// 未找到 user，根据条件和 Assign 属性初始化 
structdb.Where(User{Name: "non_existing"}).Assign(User{Age: 20}).FirstOrInit(&user)
// user -> User{Name: "non_existing", Age: 20}
// 找到 `name` = `jinzhu` 的记录，依然会更新 Assign 相关的属性
db.Where(User{Name: "Jinzhu"}).Assign(User{Age: 20}).FirstOrInit(&user)
// SELECT * FROM USERS WHERE name = jinzhu' ORDER BY id LIMIT 1;
// user -> User{ID: 111, Name: "Jinzhu", Age: 20}

FirstOrCreate

Get first matched record or create a new one with given conditions (only works with struct, map conditions), RowsAffected returns created/updated record’s count

// User not found, create a new record with give conditions
result := db.FirstOrCreate(&user, User{Name: "non_existing"})
// INSERT INTO "users" (name) VALUES ("non_existing");
// user -> User{ID: 112, Name: "non_existing"}
// result.RowsAffected // => 0
// Found user with `name` = `jinzhu`
result := db.Where(User{Name: "jinzhu"}).FirstOrCreate(&user)
// user -> User{ID: 111, Name: "jinzhu", "Age": 18}
// result.RowsAffected // => 0

如果没有找到记录，可以使用包含更多的属性的结构体创建记录，Attrs 不会被用于生成查询 SQL 。

// 未找到 user，根据条件和 Assign 属性创建记录
db.Where(User{Name: "non_existing"}).Attrs(User{Age: 20}).FirstOrCreate(&user)
// SELECT * FROM users WHERE name = 'non_existing' ORDER BY id LIMIT 1;
// INSERT INTO "users" (name, age) VALUES ("non_existing", 20);
// user -> User{ID: 112, Name: "non_existing", Age: 20}
// 找到了 `name` = `jinzhu` 的 user，则忽略 Attrs
db.Where(User{Name: "jinzhu"}).Attrs(User{Age: 20}).FirstOrCreate(&user)
// SELECT * FROM users WHERE name = 'jinzhu' ORDER BY id LIMIT 1;
// user -> User{ID: 111, Name: "jinzhu", Age: 18}

不管是否找到记录，Assign 都会将属性赋值给 struct，并将结果写回数据库

// 未找到 user，根据条件和 Assign 属性创建记录
db.Where(User{Name: "non_existing"}).Assign(User{Age: 20}).FirstOrCreate(&user)
// SELECT * FROM users WHERE name = 'non_existing' ORDER BY id LIMIT 1;
// INSERT INTO "users" (name, age) VALUES ("non_existing", 20);
// user -> User{ID: 112, Name: "non_existing", Age: 20}
// 找到了 `name` = `jinzhu` 的 user，依然会根据 Assign 更新记录
db.Where(User{Name: "jinzhu"}).Assign(User{Age: 20}).FirstOrCreate(&user)
// SELECT * FROM users WHERE name = 'jinzhu' ORDER BY id LIMIT 1;
// UPDATE users SET age=20 WHERE id = 111;
// user -> User{ID: 111, Name: "jinzhu", Age: 20}

优化器、索引提示

优化器提示用于控制查询优化器选择某个查询执行计划，GORM 通过 gorm.io/hints 提供支持，例如：

import "gorm.io/hints"

db.Clauses(hints.New("MAX_EXECUTION_TIME(10000)")).Find(&User{})

// SELECT * /*+ MAX_EXECUTION_TIME(10000) */ FROM `users`

索引提示允许传递索引提示到数据库，以防查询计划器出现混乱。

import "gorm.io/hints"

db.Clauses(hints.UseIndex("idx_user_name")).Find(&User{})

// SELECT * FROM `users` USE INDEX (`idx_user_name`)db.Clauses(hints.ForceIndex("idx_user_name", "idx_user_id").ForJoin()).Find(&User{})

// SELECT * FROM `users` FORCE INDEX FOR JOIN (`idx_user_name`,`idx_user_id`)"

参考优化器提示、索引、备注获取详情

迭代

GORM 支持通过行进行迭代

rows, err := db.Model(&User{}).Where("name = ?", "jinzhu").Rows()

defer rows.Close()

for rows.Next() {
    var user User  // ScanRows 方法用于将一行记录扫描至结构体  
    db.ScanRows(rows, &user)  // 业务逻辑...
}

FindInBatches

用于批量查询并处理记录

// 每次批量处理 100 条
result := db.Where("processed = ?", false).FindInBatches(&results, 100, func(tx *gorm.DB, batch int) error {
  for _, result := range results {
    // 批量处理找到的记录
  }
  tx.Save(&results)
  tx.RowsAffected // 本次批量操作影响的记录数
  batch // Batch 1, 2, 3
  // 如果返回错误会终止后续批量操作
  return nil
})
result.Error // returned error
result.RowsAffected // 整个批量操作影响的记录数

查询钩子

对于查询操作，GORM 支持 AfterFind 钩子，查询记录后会调用它，详情请参考钩子

func (u *User) AfterFind(tx *gorm.DB) (err error) {
    if u.Role == "" {
        u.Role = "user"
     }
        return
 }

Pluck

Pluck 用于从数据库查询单个列，并将结果扫描到切片。如果您想要查询多列，您应该使用 Select 和 Scan

var ages []int64db.Model(&users).Pluck("age", &ages)
var names []stringdb.Model(&User{}).Pluck("name", &names)db.Table("deleted_users").Pluck("name", &names)

// Distinct Pluckdb.Model(&User{}).Distinct().Pluck("Name", &names)
// SELECT DISTINCT `name` FROM `users`
// 超过一列的查询，应该使用 `Scan` 或者 `Find`，例如：db.Select("name", "age").Scan(&users)db.Select("name", "age").Find(&users)

Scope

Scopes 允许你指定常用的查询，可以在调用方法时引用这些查询

func AmountGreaterThan1000(db *gorm.DB) *gorm.DB {
    return db.Where("amount > ?", 1000)
}

func PaidWithCreditCard(db *gorm.DB) *gorm.DB {
    return db.Where("pay_mode_sign = ?", "C")
}

func PaidWithCod(db *gorm.DB) *gorm.DB {
    return db.Where("pay_mode_sign = ?", "C")
}

func OrderStatus(status []string) func (db *gorm.DB) *gorm.DB {
    return func (db *gorm.DB) *gorm.DB {
        return db.Where("status IN (?)", status)
    }
}

db.Scopes(AmountGreaterThan1000, PaidWithCreditCard).Find(&orders)

// 查找所有金额大于 1000 的信用卡订单
db.Scopes(AmountGreaterThan1000, PaidWithCod).Find(&orders)

// 查找所有金额大于 1000 的货到付款订单

db.Scopes(AmountGreaterThan1000, OrderStatus([]string{"paid", "shipped"})).Find(&orders)

// 查找所有金额大于 1000 且已付款或已发货的订单

查看 Scopes 获取详情

Count

Count 用于获取匹配的记录数

var count int64
db.Model(&User{}).Where("name = ?", "jinzhu").Or("name = ?", "jinzhu 2").Count(&count)
// SELECT count(1) FROM users WHERE name = 'jinzhu' OR name = 'jinzhu 2'
db.Model(&User{}).Where("name = ?", "jinzhu").Count(&count)
// SELECT count(1) FROM users WHERE name = 'jinzhu'; (count)
db.Table("deleted_users").Count(&count)
// SELECT count(1) FROM deleted_users;
// Count with Distinct
db.Model(&User{}).Distinct("name").Count(&count)
// SELECT COUNT(DISTINCT(`name`)) FROM `users`
db.Table("deleted_users").Select("count(distinct(name))").Count(&count)
// SELECT count(distinct(name)) FROM deleted_users
// Count with Group
users := []User{
  {Name: "name1"},
  {Name: "name2"},
  {Name: "name3"},
  {Name: "name3"},
}
db.Model(&User{}).Group("name").Count(&count)
count // => 3

更新

保存所有字段

Save 会保存所有的字段，即使字段是零值

db.First(&user)
user.Name = "jinzhu 2"
user.Age = 100
db.Save(&user)

// UPDATE users SET name='jinzhu 2', age=100, birthday='2016-01-01', updated_at = '2013-11-17 21:34:10' WHERE id=111;

更新单个列

当使用 Update 更新单个列时，你需要指定条件，否则会返回 ErrMissingWhereClause 错误，查看 Block Global Updates 获取详情。当使用了 Model 方法，且该对象主键有值，该值会被用于构建条件，例如：

// 条件更新
db.Model(&User{}).Where("active = ?", true).Update("name", "hello")
// UPDATE users SET name='hello', updated_at='2013-11-17 21:34:10' WHERE active=true;
// User 的 ID 是 `111`db.Model(&user).Update("name", "hello")
// UPDATE users SET name='hello', updated_at='2013-11-17 21:34:10' WHERE id=111;
// 根据条件和 model 的值进行更新
db.Model(&user).Where("active = ?", true).Update("name", "hello")
// UPDATE users SET name='hello', updated_at='2013-11-17 21:34:10' WHERE id=111 AND active=true;

更新多列

Updates 方法支持 struct 和 map[string]interface{} 参数。当使用 struct 更新时，默认情况下，GORM 只会更新非零值的字段

// 根据 `struct` 更新属性，只会更新非零值的字段
db.Model(&user).Updates(User{Name: "hello", Age: 18, Active: false})
// UPDATE users SET name='hello', age=18, updated_at = '2013-11-17 21:34:10' WHERE id = 111;
// 根据 `map` 更新属性
db.Model(&user).Updates(map[string]interface{}{"name": "hello", "age": 18, "active": false})
// UPDATE users SET name='hello', age=18, active=false, updated_at='2013-11-17 21:34:10' WHERE id=111;

注意当通过 struct 更新时，GORM 只会更新非零字段。如果您想确保指定字段被更新，你应该使用 Select 更新选定字段，或使用 map 来完成更新操作

更新选定字段

如果您想要在更新时选定、忽略某些字段，您可以使用 Select、Omit

// 使用 Map 进行 Select
// User's ID is `111`:

db.Model(&user).Select("name").Updates(map[string]interface{}{"name": "hello", "age": 18, "active": false})

// UPDATE users SET name='hello' WHERE id=111;

db.Model(&user).Omit("name").Updates(map[string]interface{}{"name": "hello", "age": 18, "active": false})

// UPDATE users SET age=18, active=false, updated_at='2013-11-17 21:34:10' WHERE id=111;
// 使用 Struct 进行 Select（会 select 零值的字段）

db.Model(&user).Select("Name", "Age").Updates(User{Name: "new_name", Age: 0})

// UPDATE users SET name='new_name', age=0 WHERE id=111;
// Select 所有字段（查询包括零值字段的所有字段）
db.Model(&user).Select("*").Update(User{Name: "jinzhu", Role: "admin", Age: 0})

// Select 除 Role 外的所有字段（包括零值字段的所有字段）
db.Model(&user).Select("*").Omit("Role").Update(User{Name: "jinzhu", Role: "admin", Age: 0})

更新 Hook

对于更新操作，GORM 支持 BeforeSave、BeforeUpdate、AfterSave、AfterUpdate 钩子，这些方法将在更新记录时被调用，详情请参阅钩子

func (u *User) BeforeUpdate(tx *gorm.DB) (err error) {
    if u.Role == "admin" {
        return errors.New("admin user not allowed to update")
    }
    return
}

批量更新

如果您尚未通过 Model 指定记录的主键，则 GORM 会执行批量更新

// 根据 struct 更新
db.Model(User{}).Where("role = ?", "admin").Updates(User{Name: "hello", Age: 18})

// UPDATE users SET name='hello', age=18 WHERE role = 'admin';
// 根据 map 更新
db.Table("users").Where("id IN ?", []int{10, 11}).Updates(map[string]interface{}{"name": "hello", "age": 18})

// UPDATE users SET name='hello', age=18 WHERE id IN (10, 11);

阻止全局更新

如果在没有任何条件的情况下执行批量更新，默认情况下，GORM 不会执行该操作，并返回 ErrMissingWhereClause 错误

对此，你必须加一些条件，或者使用原生 SQL，或者启用 AllowGlobalUpdate 模式，例如：

db.Model(&User{}).Update("name", "jinzhu").Error 

// gorm.ErrMissingWhereClause

db.Model(&User{}).Where("1 = 1").Update("name", "jinzhu")

// UPDATE users SET `name` = "jinzhu" WHERE 1=1db.Exec("UPDATE users SET name = ?", "jinzhu")
// UPDATE users SET name = "jinzhu"db.Session(&gorm.Session{AllowGlobalUpdate: true}).Model(&User{}).Update("name", "jinzhu")

// UPDATE users SET `name` = "jinzhu"

更新的记录数

获取受更新影响的行数

// 通过 `RowsAffected` 得到更新的记录数
result := db.Model(User{}).Where("role = ?", "admin").Updates(User{Name: "hello", Age: 18})

// UPDATE users SET name='hello', age=18 WHERE role = 'admin';result.RowsAffected 
// 更新的记录数result.Error        
// 更新的错误

高级选项

使用 SQL 表达式更新

GORM 允许使用 SQL 表达式更新列，例如：

// product 的 ID 是 `3`

db.Model(&product).Update("price", gorm.Expr("price * ? + ?", 2, 100))

// UPDATE "products" SET "price" = price * 2 + 100, "updated_at" = '2013-11-17 21:34:10' WHERE "id" = 3;

db.Model(&product).Updates(map[string]interface{}{"price": gorm.Expr("price * ? + ?", 2, 100)})

// UPDATE "products" SET "price" = price * 2 + 100, "updated_at" = '2013-11-17 21:34:10' WHERE "id" = 3;

db.Model(&product).UpdateColumn("quantity", gorm.Expr("quantity - ?", 1))
// UPDATE "products" SET "quantity" = quantity - 1 WHERE "id" = 3;

db.Model(&product).Where("quantity > 1").UpdateColumn("quantity", gorm.Expr("quantity - ?", 1))
// UPDATE "products" SET "quantity" = quantity - 1 WHERE "id" = 3 AND quantity > 1;

并且 GORM 也允许使用 SQL 表达式、自定义数据类型的 Context Valuer 来更新，例如：

// 根据自定义数据类型创建
type Location struct {
    X, Y int
}

func (loc Location) GormValue(ctx context.Context, db *gorm.DB) clause.Expr {
    return clause.Expr{
        SQL:  "ST_PointFromText(?)",
        Vars: []interface{}{fmt.Sprintf("POINT(%d %d)", loc.X, loc.Y)},
   }
}

db.Model(&User{ID: 1}).Updates(User{
    Name:  "jinzhu",
    Location: Location{X: 100, Y: 100},
})

// UPDATE `user_with_points` SET `name`="jinzhu",`location`=ST_PointFromText("POINT(100 100)") WHERE `id` = 1

根据子查询进行更新

使用子查询更新表

db.Model(&user).Update("company_name",  db.Model(&Company{}).Select("name").Where("companies.id = users.company_id"))

// UPDATE "users" SET "company_name" = (SELECT name FROM companies WHERE companies.id = users.company_id);

db.Table("users as u").Where("name = ?", "jinzhu").Update("company_name", db.Table("companies as c").Select("name").Where("c.id = u.company_id"))db.Table("users as u").Where("name = ?", "jinzhu").Updates(map[string]interface{}{}{"company_name": db.Table("companies as c").Select("name").Where("c.id = u.company_id")})

不使用 Hook 和时间追踪

如果您想在更新时跳过 Hook 方法且不追踪更新时间，可以使用 UpdateColumn、UpdateColumns，其用法类似于 Update、Updates

// 更新单个列
db.Model(&user).UpdateColumn("name", "hello")
// UPDATE users SET name='hello' WHERE id = 111;

// 更新多个列
db.Model(&user).UpdateColumns(User{Name: "hello", Age: 18})
// UPDATE users SET name='hello', age=18 WHERE id = 111;
// 更新选中的列
db.Model(&user).Select("name", "age").UpdateColumns(User{Name: "hello", Age: 0})
// UPDATE users SET name='hello', age=0 WHERE id = 111;

返回修改行的数据

返回被修改的数据，仅适用于支持 Returning 的数据库，例如：

// 返回所有列
var users []

UserDB.Model(&users).Clauses(clause.Returning{}).Where("role = ?", "admin").Update("salary", gorm.Expr("salary * ?", 2))
// UPDATE `users` SET `salary`=salary * 2,`updated_at`="2021-10-28 17:37:23.19" WHERE role = "admin" RETURNING *

// users => []User{{ID: 1, Name: "jinzhu", Role: "admin", Salary: 100}, {ID: 2, Name: "jinzhu.2", Role: "admin", Salary: 1000}}

// 返回指定的列
DB.Model(&users).Clauses(clause.Returning{Columns: []clause.Column{{Name: "name"}, {Name: "salary"}}}).Where("role = ?", "admin").Update("salary", gorm.Expr("salary * ?", 2))

// UPDATE `users` SET `salary`=salary * 2,`updated_at`="2021-10-28 17:37:23.19" WHERE role = "admin" RETURNING `name`, `salary`
// users => []User{{ID: 0, Name: "jinzhu", Role: "", Salary: 100}, {ID: 0, Name: "jinzhu.2", Role: "", Salary: 1000}}

检查字段是否有变更？

GORM 提供了 Changed 方法，它可以被用在 Before Update Hook 里，它会返回字段是否有变更的布尔值

Changed 方法只能与 Update、Updates 方法一起使用，并且它只是检查 Model 对象字段的值与 Update、Updates 的值是否相等，如果值有变更，且字段没有被忽略，则返回 true

func (u *User) BeforeUpdate(tx *gorm.DB) (err error) {
    // 如果 Role 字段有变更
    if tx.Statement.Changed("Role") {
        return errors.New("role not allowed to change")
    }
    if tx.Statement.Changed("Name", "Admin") {
        // 如果 Name 或 Role 字段有变更
        tx.Statement.SetColumn("Age", 18)
    }  // 如果任意字段有变更
    if tx.Statement.Changed() {
        tx.Statement.SetColumn("RefreshedAt", time.Now())
    }
    return nil}

db.Model(&User{ID: 1, Name: "jinzhu"}).Updates(map[string]interface{"name": "jinzhu2"})

// Changed("Name") => truedb.Model(&User{ID: 1, Name: "jinzhu"}).Updates(map[string]interface{"name": "jinzhu"})

// Changed("Name") => false, 因为 `Name` 没有变更
db.Model(&User{ID: 1, Name: "jinzhu"}).Select("Admin").Updates(map[string]interface{  "name": "jinzhu2", "admin": false,})
// Changed("Name") => false, 因为 `Name` 没有被 Select 选中并更新

db.Model(&User{ID: 1, Name: "jinzhu"}).Updates(User{Name: "jinzhu2"})
// Changed("Name") => truedb.Model(&User{ID: 1, Name: "jinzhu"}).Updates(User{Name: "jinzhu"})

// Changed("Name") => false, 因为 `Name` 没有变更db.Model(&User{ID: 1, Name: "jinzhu"}).Select("Admin").Updates(User{Name: "jinzhu2"})

// Changed("Name") => false, 因为 `Name` 没有被 Select 选中并更新

在 Update 时修改值

若要在 Before 钩子中改变要更新的值，如果它是一个完整的更新，可以使用 Save；否则，应该使用 SetColumn ，例如：

 func (user *User) BeforeSave(tx *gorm.DB) (err error) {
     if pw, err := bcrypt.GenerateFromPassword(user.Password, 0); err == nil {
         tx.Statement.SetColumn("EncryptedPassword", pw)    
     }
     if tx.Statement.Changed("Code") {
         user.Age += 20
         tx.Statement.SetColumn("Age", user.Age)
     }}
db.Model(&user).Update("Name", "jinzhu")

删除

删除一条记录

删除一条记录时，删除对象需要指定主键，否则会触发批量 Delete，例如：

// Email 的 ID 是 `10`
db.Delete(&email)
// DELETE from emails where id = 10;
// 带额外条件的删除
db.Where("name = ?", "jinzhu").Delete(&email)
// DELETE from emails where id = 10 AND name = "jinzhu";

根据主键删除

GORM 允许通过主键(可以是复合主键)和内联条件来删除对象，它可以使用数字（如以下例子。也可以使用字符串——译者注）。查看查询-内联条件（Query Inline Conditions）了解详情。

db.Delete(&User{}, 10)
// DELETE FROM users WHERE id = 10;
db.Delete(&User{}, "10")
// DELETE FROM users WHERE id = 10;
db.Delete(&users, []int{1,2,3})
// DELETE FROM users WHERE id IN (1,2,3);

Delete Hook

对于删除操作，GORM 支持 BeforeDelete、AfterDelete Hook，在删除记录时会调用这些方法，查看 Hook 获取详情

func (u *User) BeforeDelete(tx *gorm.DB) (err error) {
    if u.Role == "admin" {
        return errors.New("admin user not allowed to delete")
    }
     return
 }

批量删除

如果指定的值不包括主属性，那么 GORM 会执行批量删除，它将删除所有匹配的记录

db.Where("email LIKE ?", "%jinzhu%").Delete(&Email{})
// DELETE from emails where email LIKE "%jinzhu%";
db.Delete(&Email{}, "email LIKE ?", "%jinzhu%")
// DELETE from emails where email LIKE "%jinzhu%";

阻止全局删除

如果在没有任何条件的情况下执行批量删除，GORM 不会执行该操作，并返回 ErrMissingWhereClause 错误

对此，你必须加一些条件，或者使用原生 SQL，或者启用 AllowGlobalUpdate 模式，例如：

db.Delete(&User{}).Error 
// gorm.ErrMissingWhereClause

db.Where("1 = 1").Delete(&User{})

// DELETE FROM `users` WHERE 1=1

db.Exec("DELETE FROM users")
// DELETE FROM users
db.Session(&gorm.Session{AllowGlobalUpdate: true}).Delete(&User{})
// DELETE FROM users

返回删除行的数据

返回被删除的数据，仅适用于支持 Returning 的数据库，例如：

// 返回所有列
var users []
UserDB.Clauses(clause.Returning{}).Where("role = ?", "admin").Delete(&users)
// DELETE FROM `users` WHERE role = "admin" RETURNING *
// users => []User{{ID: 1, Name: "jinzhu", Role: "admin", Salary: 100}, {ID: 2, Name: "jinzhu.2", Role: "admin", Salary: 1000}}

// 返回指定的列
DB.Clauses(clause.Returning{Columns: []clause.Column{{Name: "name"}, {Name: "salary"}}}).Where("role = ?", "admin").Delete(&users)

// DELETE FROM `users` WHERE role = "admin" RETURNING `name`, `salary`
// users => []User{{ID: 0, Name: "jinzhu", Role: "", Salary: 100}, {ID: 0, Name: "jinzhu.2", Role: "", Salary: 1000}}

软删除

如果您的模型包含了一个 gorm.deletedat 字段（gorm.Model 已经包含了该字段)，它将自动获得软删除的能力！

拥有软删除能力的模型调用 Delete 时，记录不会从数据库中被真正删除。但 GORM 会将 DeletedAt 置为当前时间，并且你不能再通过普通的查询方法找到该记录。

// user 的 ID 是 `111`
db.Delete(&user)
// UPDATE users SET deleted_at="2013-10-29 10:23" WHERE id = 111;
// 批量删除
db.Where("age = ?", 20).Delete(&User{})
// UPDATE users SET deleted_at="2013-10-29 10:23" WHERE age = 20;
// 在查询时会忽略被软删除的记录
db.Where("age = 20").Find(&user)
// SELECT * FROM users WHERE age = 20 AND deleted_at IS NULL;

如果您不想引入 gorm.Model，您也可以这样启用软删除特性：

type User struct {
    ID      int
    Deleted gorm.DeletedAt  
    Name    string
}

查找被软删除的记录

您可以使用 Unscoped 找到被软删除的记录

db.Unscoped().Where("age = 20").Find(&users)

// SELECT * FROM users WHERE age = 20;

永久删除

您也可以使用 Unscoped 永久删除匹配的记录

db.Unscoped().Delete(&order)
// DELETE FROM orders WHERE id=10;

Delete Flag

将 unix 时间戳作为 delete flag

import "gorm.io/plugin/soft_delete"

type User struct {
    ID        uint
    Name      string
    DeletedAt soft_delete.DeletedAt
}
// 查询SELECT * FROM users WHERE deleted_at = 0;
// 删除UPDATE users SET deleted_at = /* current unix second */ WHERE ID = 1;

INFO 在配合 unique 字段使用软删除时，您需要使用这个基于 unix 时间戳的 DeletedAt 字段创建一个复合索引，例如：

go import “gorm.io/plugin/soft_delete”

type User struct {
     ID uint
     Name string gorm:"uniqueIndex:udx_name"
     DeletedAt soft_delete.DeletedAt
     gorm:"uniqueIndex:udx_name"
 }

使用 1 / 0 作为 delete flag

import "gorm.io/plugin/soft_delete"

type User struct {
    ID uint
    Name  string
    IsDel soft_delete.DeletedAt `gorm:"softDelete:flag"`
}
// 查询SELECT * FROM users WHERE is_del = 0;
// 删除UPDATE users SET is_del = 1 WHERE ID = 1;

原生 SQL

type Result struct {
  ID   int
  Name string
  Age  int
}
var result Result
db.Raw("SELECT id, name, age FROM users WHERE name = ?", 3).Scan(&result)
db.Raw("SELECT id, name, age FROM users WHERE name = ?", 3).Scan(&result)
var age int
db.Raw("SELECT SUM(age) FROM users WHERE role = ?", "admin").Scan(&age)
var users []User
db.Raw("UPDATE users SET name = ? WHERE age = ? RETURNING id, name", "tianlang", 20).Scan(&users)

db.Exec("DROP TABLE users")
db.Exec("UPDATE orders SET shipped_at = ? WHERE id IN ?", time.Now(), []int64{1, 2, 3})
// Exec with SQL Expression
db.Exec("UPDATE users SET money = ? WHERE name = ?", gorm.Expr("money * ? + ?", 10000, 1), "tianlang")