AutoMigrate

AutoMigrate 用于自动迁移您的 schema，保持您的 schema 是最新的。

注意： AutoMigrate 会创建表、缺失的外键、约束、列和索引。 It will change existing column’s type if its size, precision changed, or if it’s changing from non-nullable to nullable. 出于保护您数据的目的，它 不会 删除未使用的列

  1. db.AutoMigrate(&User{})
  3. db.AutoMigrate(&User{}, &Product{}, &Order{})
  5. // 创建表时添加后缀
  6. db.Set("gorm:table_options", "ENGINE=InnoDB").AutoMigrate(&User{})

注意 AutoMigrate 会自动创建数据库外键约束，您可以在初始化时禁用此功能，例如：

  1. db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{
  2.   DisableForeignKeyConstraintWhenMigrating: true,
  3. })

Migrator 接口

GORM 提供了 Migrator 接口，该接口为每个数据库提供了统一的 API 接口，可用来为您的数据库构建独立迁移，例如：

SQLite 不支持 ALTER COLUMN、DROP COLUMN，当你试图修改表结构，GORM 将创建一个新表、复制所有数据、删除旧表、重命名新表。

一些版本的 MySQL 不支持 rename 列，索引。GORM 将基于您使用 MySQL 的版本执行不同 SQL

  1. type Migrator interface {
  2.   // AutoMigrate
  3.   AutoMigrate(dst ...interface{}) error
  5.   // Database
  6.   CurrentDatabase() string
  7.   FullDataTypeOf(*schema.Field) clause.Expr
  9.   // Tables
  10.   CreateTable(dst ...interface{}) error
  11.   DropTable(dst ...interface{}) error
  12.   HasTable(dst interface{}) bool
  13.   RenameTable(oldName, newName interface{}) error
  14.   GetTables() (tableList []string, err error)
  16.   // Columns
  17.   AddColumn(dst interface{}, field string) error
  18.   DropColumn(dst interface{}, field string) error
  19.   AlterColumn(dst interface{}, field string) error
  20.   MigrateColumn(dst interface{}, field *schema.Field, columnType ColumnType) error
  21.   HasColumn(dst interface{}, field string) bool
  22.   RenameColumn(dst interface{}, oldName, field string) error
  23.   ColumnTypes(dst interface{}) ([]ColumnType, error)
  25.   // Views
  26.   CreateView(name string, option ViewOption) error
  27.   DropView(name string) error
  29.   // Constraints
  30.   CreateConstraint(dst interface{}, name string) error
  31.   DropConstraint(dst interface{}, name string) error
  32.   HasConstraint(dst interface{}, name string) bool
  34.   // Indexes
  35.   CreateIndex(dst interface{}, name string) error
  36.   DropIndex(dst interface{}, name string) error
  37.   HasIndex(dst interface{}, name string) bool
  38.   RenameIndex(dst interface{}, oldName, newName string) error
  39. }

当前数据库

返回当前使用的数据库名

  1. db.Migrator().CurrentDatabase()

表

  1. // 为 `User` 创建表
  2. db.Migrator().CreateTable(&User{})
  4. // 将 "ENGINE=InnoDB" 添加到创建 `User` 的 SQL 里去
  5. db.Set("gorm:table_options", "ENGINE=InnoDB").Migrator().CreateTable(&User{})
  7. // 检查 `User` 对应的表是否存在
  8. db.Migrator().HasTable(&User{})
  9. db.Migrator().HasTable("users")
  11. // 如果存在表则删除（删除时会忽略、删除外键约束)
  12. db.Migrator().DropTable(&User{})
  13. db.Migrator().DropTable("users")
  15. // 重命名表
  16. db.Migrator().RenameTable(&User{}, &UserInfo{})
  17. db.Migrator().RenameTable("users", "user_infos")

列

  1. type User struct {
  2.   Name string
  3. }
  5. // 添加 name 字段
  6. db.Migrator().AddColumn(&User{}, "Name")
  7. // 删除 name 字段
  8. db.Migrator().DropColumn(&User{}, "Name")
  9. // 修改 name 字段
  10. db.Migrator().AlterColumn(&User{}, "Name")
  11. // 检查 name 字段是否存在
  12. db.Migrator().HasColumn(&User{}, "Name")
  14. type User struct {
  15.   Name    string
  16.   NewName string
  17. }
  19. // 字段重命名
  20. db.Migrator().RenameColumn(&User{}, "Name", "NewName")
  21. db.Migrator().RenameColumn(&User{}, "name", "new_name")
  23. // 字段类型
  24. db.Migrator().ColumnTypes(&User{}) ([]gorm.ColumnType, error)
  26. type ColumnType interface {
  27.     Name() string
  28.     DatabaseTypeName() string                 // varchar
  29.     ColumnType() (columnType string, ok bool) // varchar(64)
  30.     PrimaryKey() (isPrimaryKey bool, ok bool)
  31.     AutoIncrement() (isAutoIncrement bool, ok bool)
  32.     Length() (length int64, ok bool)
  33.     DecimalSize() (precision int64, scale int64, ok bool)
  34.     Nullable() (nullable bool, ok bool)
  35.     Unique() (unique bool, ok bool)
  36.     ScanType() reflect.Type
  37.     Comment() (value string, ok bool)
  38.     DefaultValue() (value string, ok bool)
  39. }

Views

Create views by ViewOption. About ViewOption:

  • Query is a subquery, which is required.
  • If Replace is true, exec CREATE OR REPLACE otherwise exec CREATE.
  • If CheckOption is not empty, append to sql, e.g. WITH LOCAL CHECK OPTION.

NOTE SQLite currently does not support Replace in ViewOption

  1. query := db.Model(&User{}).Where("age > ?", 20)
  3. // Create View
  4. db.Migrator().CreateView("users_pets", gorm.ViewOption{Query: query})
  5. // CREATE VIEW `users_view` AS SELECT * FROM `users` WHERE age > 20
  7. // Create or Replace View
  8. db.Migrator().CreateView("users_pets", gorm.ViewOption{Query: query, Replace: true})
  9. // CREATE OR REPLACE VIEW `users_pets` AS SELECT * FROM `users` WHERE age > 20
  11. // Create View With Check Option
  12. db.Migrator().CreateView("users_pets", gorm.ViewOption{Query: query, CheckOption: "WITH CHECK OPTION"})
  13. // CREATE VIEW `users_pets` AS SELECT * FROM `users` WHERE age > 20 WITH CHECK OPTION
  15. // Drop View
  16. db.Migrator().DropView("users_pets")
  17. // DROP VIEW IF EXISTS "users_pets"

Constraints

  1. type UserIndex struct {
  2.   Name  string `gorm:"check:name_checker,name <> 'jinzhu'"`
  3. }
  5. // Create constraint
  6. db.Migrator().CreateConstraint(&User{}, "name_checker")
  8. // Drop constraint
  9. db.Migrator().DropConstraint(&User{}, "name_checker")
  11. // Check constraint exists
  12. db.Migrator().HasConstraint(&User{}, "name_checker")

Create foreign keys for relations

  1. type User struct {
  2.   gorm.Model
  3.   CreditCards []CreditCard
  4. }
  6. type CreditCard struct {
  7.   gorm.Model
  8.   Number string
  9.   UserID uint
  10. }
  12. // create database foreign key for user & credit_cards
  13. db.Migrator().CreateConstraint(&User{}, "CreditCards")
  14. db.Migrator().CreateConstraint(&User{}, "fk_users_credit_cards")
  15. // ALTER TABLE `credit_cards` ADD CONSTRAINT `fk_users_credit_cards` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`)
  17. // check database foreign key for user & credit_cards exists or not
  18. db.Migrator().HasConstraint(&User{}, "CreditCards")
  19. db.Migrator().HasConstraint(&User{}, "fk_users_credit_cards")
  21. // drop database foreign key for user & credit_cards
  22. db.Migrator().DropConstraint(&User{}, "CreditCards")
  23. db.Migrator().DropConstraint(&User{}, "fk_users_credit_cards")

Indexes

  1. type User struct {
  2.   gorm.Model
  3.   Name string `gorm:"size:255;index:idx_name,unique"`
  4. }
  6. // Create index for Name field
  7. db.Migrator().CreateIndex(&User{}, "Name")
  8. db.Migrator().CreateIndex(&User{}, "idx_name")
  10. // Drop index for Name field
  11. db.Migrator().DropIndex(&User{}, "Name")
  12. db.Migrator().DropIndex(&User{}, "idx_name")
  14. // Check Index exists
  15. db.Migrator().HasIndex(&User{}, "Name")
  16. db.Migrator().HasIndex(&User{}, "idx_name")
  18. type User struct {
  19.   gorm.Model
  20.   Name  string `gorm:"size:255;index:idx_name,unique"`
  21.   Name2 string `gorm:"size:255;index:idx_name_2,unique"`
  22. }
  23. // Rename index name
  24. db.Migrator().RenameIndex(&User{}, "Name", "Name2")
  25. db.Migrator().RenameIndex(&User{}, "idx_name", "idx_name_2")

约束

GORM creates constraints when auto migrating or creating table, see Constraints or Database Indexes for details

Atlas Integration

Atlas is an open-source database migration tool that has an official integration with GORM.

While GORM’s AutoMigrate feature works in most cases, at some point you may need to switch to a versioned migrations strategy.

Once this happens, the responsibility for planning migration scripts and making sure they are in line with what GORM expects at runtime is moved to developers.

Atlas can automatically plan database schema migrations for developers using the official GORM Provider. After configuring the provider you can automatically plan migrations by running:

  1. atlas migrate diff --env gorm

To learn how to use Atlas with GORM, check out the official documentation.

Other Migration Tools

To use GORM with other Go-based migration tools, GORM provides a generic DB interface that might be helpful for you.

  1. // returns `*sql.DB`
  2. db.DB()

Refer to Generic Interface for more details.