[19-Gorm入门]

一 Gorm概述

1.1 Gorm介绍

Gorm 是 Golang 的一个 orm 框架。ORM 是通过实例对象的语法，完成关系型数据库的操作，是”对象-关系映射”(Object/Relational Mapping) 的缩写。使用 ORM 框架可以让我们更方便的操作数据库。

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

作者是中国人，中文文档齐全，对开发者友好，支持主流数据库。

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

Gorm最新源码地址:https://github.com/go-gorm/gorm

V1版本地址：https://github.com/jinzhu/gorm

中文文档地址：https://gorm.io/zh_CN/

1.2 安装

go get -u gorm.io/gorm
go get -u gorm.io/driver/sqlite
go get -u gorm.io/driver/mysql
go get -u gorm.io/driver/postgres
go get -u gorm.io/driver/sqlserver

1.3 快速入门

package main

import (
   "gorm.io/driver/sqlite"
   "gorm.io/gorm"
)

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")
   }

   //1 迁移 表，可以写多个
   //db.AutoMigrate(&Product{})

   //2 插入数据
   //db.Create(&Product{Code: "D42", Price: 100})
   //db.Create(&Product{Code: "D43", Price: 150})

   //3 查询数据
   var product Product  // 定义空Product结构体对象
   ////db.First(&product, 1) // 根据整型主键查找
   db.First(&product, "code = ?", "F43") // 查找 code 字段值为 D43 的记录
   //fmt.Println(product)

   //4  更新 - 将 product 的 price 更新为 200
   //db.Model(&product).Update("Price", 200)
   // Update - 更新多个字段
   //db.Model(&product).Updates(Product{Price: 200, Code: "F43"}) // 仅更新非零值字段
   //db.Model(&product).Updates(map[string]interface{}{"Price": 300, "Code": "F42"})

   //5  Delete - 删除 product
   //db.Delete(&product, 1)
}

二声明模型

2.1 模型定义

模型是标准的 struct，由 Go 的基本数据类型、实现了 Scanner 和 Valuer 接口的自定义类型及其指针或别名组成

例如：

type User struct {
  ID           uint
  Name         string
  Email        *string
  Age          uint8
  Birthday     *time.Time
  MemberNumber sql.NullString
  ActivatedAt  sql.NullTime
  CreatedAt    time.Time
  UpdatedAt    time.Time
}

2.2 约定

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

遵循 GORM 已有的约定，可以减少您的配置和代码量。如果约定不符合您的需求，GORM 允许您自定义配置它们

2.3 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"`
}

您可以将它嵌入到您的结构体中，以包含这几个字段，详情请参考嵌入结构体

2.3 高级选项

字段级权限控制

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

注意： 使用 GORM Migrator 创建表时，不会创建被忽略的字段

type User struct {
  Name string `gorm:"<-:create"` // allow read and create
  Name string `gorm:"<-:update"` // allow read and update
  Name string `gorm:"<-"`        // allow read and write (create and update)
  Name string `gorm:"<-:false"`  // allow read, disable write permission
  Name string `gorm:"->"`        // readonly (disable write permission unless it configured)
  Name string `gorm:"->;<-:create"` // allow read and create
  Name string `gorm:"->:false;<-:create"` // createonly (disabled read from db)
  Name string `gorm:"-"`            // ignore this field when write and read with struct
  Name string `gorm:"-:all"`        // ignore this field when write, read and migrate with struct
  Name string `gorm:"-:migration"`  // ignore this field when migrate with struct
}

创建/更新时间追踪（纳秒、毫秒、秒、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"`
  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	指定如何将数据序列化和反序列化到数据库中的序列化程序，如: `serializer:json/gob/unixtime`
size	指定列数据大小/长度, 如: `size:256`
primaryKey	指定列作为主键
unique	指定列作为unique
default	指定列的默认值
precision	指定列的精度
scale	指定列的比例
not 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	使用选项创建索引，对多个字段使用相同的名称创建复合索引, 详情参照 Indexes
uniqueIndex	与’index’相同，但创建唯一索引
check	创建检查约束, 如: `check:age > 13`, 参照 Constraints
<-	设置字段的写入权限, `<-:create` 仅创建字段, `<-:update` 仅更新字段, `<-:false` 没有写权限, `<-` 创建和更新权限
->	设置字段读权限, `->:false` 没有读权限
-	忽略该字段, `-` 没有读写权限, `-:migration` 没有迁移权限, `-:all` 没有 read/write/migrate 权限
comment	迁移时为字段添加注释

关联标签

GORM 允许通过标签为关联配置外键、约束、many2many 表，详情请参考关联部分

三连接到数据库

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

3.1 MySQL

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

func main() {
  // 参考 https://github.com/go-sql-driver/mysql#dsn-data-source-name 获取详情
  dsn := "user:pass@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
  db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
  //db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{Logger:logger.Default.LogMode(logger.Info)})  打印sql日志
}

注意：想要正确的处理 time.Time ，您需要带上 parseTime 参数， (更多参数) 要支持完整的 UTF-8 编码，您需要将 charset=utf8 更改为 charset=utf8mb4 查看此文章获取详情

MySQl 驱动程序提供了一些高级配置可以在初始化过程中使用，例如：

db, err := gorm.Open(mysql.New(mysql.Config{
  DSN: "gorm:gorm@tcp(127.0.0.1:3306)/gorm?charset=utf8&parseTime=True&loc=Local", // DSN data source name
  DefaultStringSize: 256, // string 类型字段的默认长度
  DisableDatetimePrecision: true, // 禁用 datetime 精度，MySQL 5.6 之前的数据库不支持
  DontSupportRenameIndex: true, // 重命名索引时采用删除并新建的方式，MySQL 5.7 之前的数据库和 MariaDB 不支持重命名索引
  DontSupportRenameColumn: true, // 用 `change` 重命名列，MySQL 8 之前的数据库和 MariaDB 不支持重命名列
  SkipInitializeWithVersion: false, // 根据当前 MySQL 版本自动配置
}), &gorm.Config{})

自定义驱动

GORM 允许通过 DriverName 选项自定义 MySQL 驱动，例如：

import (
  _ "example.com/my_mysql_driver"
  "gorm.io/gorm"
)

db, err := gorm.Open(mysql.New(mysql.Config{
  DriverName: "my_mysql_driver",
  DSN: "gorm:gorm@tcp(localhost:9910)/gorm?charset=utf8&parseTime=True&loc=Local", // Data Source Name，参考 https://github.com/go-sql-driver/mysql#dsn-data-source-name
}), &gorm.Config{})

现有的数据库连接

GORM 允许通过一个现有的数据库连接来初始化 *gorm.DB

import (
  "database/sql"
  "gorm.io/driver/mysql"
  "gorm.io/gorm"
)

sqlDB, err := sql.Open("mysql", "mydb_dsn")
gormDB, err := gorm.Open(mysql.New(mysql.Config{
  Conn: sqlDB,
}), &gorm.Config{})

3.2 PostgreSQL

import (
  "gorm.io/driver/postgres"
  "gorm.io/gorm"
)

dsn := "host=localhost user=gorm password=gorm dbname=gorm port=9920 sslmode=disable TimeZone=Asia/Shanghai"
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})

我们使用 pgx 作为 postgres 的 database/sql 驱动，默认情况下，它会启用 prepared statement 缓存，你可以这样禁用它：

// https://github.com/go-gorm/postgres
db, err := gorm.Open(postgres.New(postgres.Config{
  DSN: "user=gorm password=gorm dbname=gorm port=9920 sslmode=disable TimeZone=Asia/Shanghai",
  PreferSimpleProtocol: true, // disables implicit prepared statement usage
}), &gorm.Config{})

自定义驱动

GORM 允许通过 DriverName 选项自定义 PostgreSQL 驱动，例如：

import (
  _ "github.com/GoogleCloudPlatform/cloudsql-proxy/proxy/dialers/postgres"
  "gorm.io/gorm"
)

db, err := gorm.Open(postgres.New(postgres.Config{
  DriverName: "cloudsqlpostgres",
  DSN: "host=project:region:instance user=postgres dbname=postgres password=password sslmode=disable",
})

现有的数据库连接

GORM 允许通过一个现有的数据库连接来初始化 *gorm.DB

import (
  "database/sql"
  "gorm.io/driver/postgres"
  "gorm.io/gorm"
)

sqlDB, err := sql.Open("pgx", "mydb_dsn")
gormDB, err := gorm.Open(postgres.New(postgres.Config{
  Conn: sqlDB,
}), &gorm.Config{})

3.3 SQLite

import (
  "gorm.io/driver/sqlite" // Sqlite driver based on GGO
  // "github.com/glebarez/sqlite" // Pure go SQLite driver, checkout https://github.com/glebarez/sqlite for details
  "gorm.io/gorm"
)

// github.com/mattn/go-sqlite3
db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{})

注意： 您也可以使用 file::memory:?cache=shared 替代文件路径。这会告诉 SQLite 在系统内存中使用一个临时数据库。 (查看 SQLite 文档获取详情)

3.4 SQL Server

import (
  "gorm.io/driver/sqlserver"
  "gorm.io/gorm"
)

// github.com/denisenkom/go-mssqldb
dsn := "sqlserver://gorm:LoremIpsum86@localhost:9930?database=gorm"
db, err := gorm.Open(sqlserver.Open(dsn), &gorm.Config{})

3.5 Clickhouse

https://github.com/go-gorm/clickhouse

import (
  "gorm.io/driver/clickhouse"
  "gorm.io/gorm"
)

func main() {
  dsn := "tcp://localhost:9000?database=gorm&username=gorm&password=gorm&read_timeout=10&write_timeout=20"
  db, err := gorm.Open(clickhouse.Open(dsn), &gorm.Config{})

  // Auto Migrate
  db.AutoMigrate(&User{})
  // Set table options
  db.Set("gorm:table_options", "ENGINE=Distributed(cluster, default, hits)").AutoMigrate(&User{})

  // 插入
  db.Create(&user)

  // 查询
  db.Find(&user, "id = ?", 10)

  // 批量插入
  var users = []User{user1, user2, user3}
  db.Create(&users)
  // ...
}

3.6 连接池

GORM 使用 database/sql 维护连接池

sqlDB, err := db.DB()

// SetMaxIdleConns 设置空闲连接池中连接的最大数量
sqlDB.SetMaxIdleConns(10)

// SetMaxOpenConns 设置打开数据库连接的最大数量。
sqlDB.SetMaxOpenConns(100)

// SetConnMaxLifetime 设置了连接可复用的最大时间。
sqlDB.SetConnMaxLifetime(time.Hour)

查看通用接口获取详情。

不支持的数据库

有些数据库可能兼容 mysql、postgres 的方言，在这种情况下，你可以直接使用这些数据库的方言。

对于其它不支持的数据，[我们鼓励且欢迎大家伙开发更多数据库类型的驱动！]

Tags: Go Gin框架

← [20-Gorm增删查改] [18-项目的关闭与重启] →

赏

使用支付宝打赏

使用微信打赏

点击上方按钮,请我喝杯咖啡！

扫描二维码，分享此文章

[19-Gorm入门]

[19-Gorm入门]

一 Gorm概述

1.1 Gorm介绍

1.2 安装

1.3 快速入门

二 声明模型

2.1 模型定义

2.2 约定

2.3 gorm.Model

2.3 高级选项

字段级权限控制

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

嵌入结构体

字段标签

关联标签

三连接到数据库

3.1 MySQL

自定义驱动

现有的数据库连接

3.2 PostgreSQL

自定义驱动

现有的数据库连接

3.3 SQLite

3.4 SQL Server

3.5 Clickhouse

3.6 连接池

不支持的数据库

二声明模型