Automatically migrate your schema, to keep your schema up to date.
NOTE: AutoMigrate will create tables, missing foreign keys, constraints, columns and indexes. It will change existing column’s type if its size, precision changed, or if it’s changing from non-nullable to nullable. It WON’T delete unused columns to protect your data.
db.AutoMigrate(&User{})
db.AutoMigrate(&User{}, &Product{}, &Order{})
// Add table suffix when creating tables db.Set("gorm:table_options", "ENGINE=InnoDB").AutoMigrate(&User{})
NOTE AutoMigrate creates database foreign key constraints automatically, you can disable this feature during initialization, for example:
GORM provides a migrator interface, which contains unified API interfaces for each database that could be used to build your database-independent migrations, for example:
SQLite doesn’t support ALTER COLUMN, DROP COLUMN, GORM will create a new table as the one you are trying to change, copy all data, drop the old table, rename the new table
MySQL doesn’t support rename column, index for some versions, GORM will perform different SQL based on the MySQL version you are using
type Migrator interface { // AutoMigrate AutoMigrate(dst ...interface{}) error
// Columns AddColumn(dst interface{}, field string) error DropColumn(dst interface{}, field string) error AlterColumn(dst interface{}, field string) error MigrateColumn(dst interface{}, field *schema.Field, columnType ColumnType) error HasColumn(dst interface{}, field string) bool RenameColumn(dst interface{}, oldName, field string) error ColumnTypes(dst interface{}) ([]ColumnType, error) // Views CreateView(name string, option ViewOption) error DropView(name string) error
// Constraints CreateConstraint(dst interface{}, name string) error DropConstraint(dst interface{}, name string) error HasConstraint(dst interface{}, name string) bool
// Indexes CreateIndex(dst interface{}, name string) error DropIndex(dst interface{}, name string) error HasIndex(dst interface{}, name string) bool RenameIndex(dst interface{}, oldName, newName string) error }
CurrentDatabase
Returns current using database name
db.Migrator().CurrentDatabase()
Tables
// Create table for `User` db.Migrator().CreateTable(&User{})
// Append "ENGINE=InnoDB" to the creating table SQL for `User` db.Set("gorm:table_options", "ENGINE=InnoDB").Migrator().CreateTable(&User{})
// Check table for `User` exists or not db.Migrator().HasTable(&User{}) db.Migrator().HasTable("users")
// Drop table if exists (will ignore or delete foreign key constraints when dropping) db.Migrator().DropTable(&User{}) db.Migrator().DropTable("users")
// Rename old table to new table db.Migrator().RenameTable(&User{}, &UserInfo{}) db.Migrator().RenameTable("users", "user_infos")
Columns
type User struct { Name string }
// Add name field db.Migrator().AddColumn(&User{}, "Name") // Drop name field db.Migrator().DropColumn(&User{}, "Name") // Alter name field db.Migrator().AlterColumn(&User{}, "Name") // Check column exists db.Migrator().HasColumn(&User{}, "Name")
type User struct { Name string NewName string }
// Rename column to new name db.Migrator().RenameColumn(&User{}, "Name", "NewName") db.Migrator().RenameColumn(&User{}, "name", "new_name")
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
query := db.Model(&User{}).Where("age > ?", 20)
// Create View db.Migrator().CreateView("users_pets", gorm.ViewOption{Query: query}) // CREATE VIEW `users_view` AS SELECT * FROM `users` WHERE age > 20
// Create or Replace View db.Migrator().CreateView("users_pets", gorm.ViewOption{Query: query, Replace: true}) // CREATE OR REPLACE VIEW `users_pets` AS SELECT * FROM `users` WHERE age > 20
// Create View With Check Option db.Migrator().CreateView("users_pets", gorm.ViewOption{Query: query, CheckOption: "WITH CHECK OPTION"}) // CREATE VIEW `users_pets` AS SELECT * FROM `users` WHERE age > 20 WITH CHECK OPTION
// Drop View db.Migrator().DropView("users_pets") // DROP VIEW IF EXISTS "users_pets"
Constraints
type UserIndex struct { Name string`gorm:"check:name_checker,name <> 'jinzhu'"` }
type User struct { gorm.Model CreditCards []CreditCard }
type CreditCard struct { gorm.Model Number string UserID uint }
// create database foreign key for user & credit_cards db.Migrator().CreateConstraint(&User{}, "CreditCards") db.Migrator().CreateConstraint(&User{}, "fk_users_credit_cards") // ALTER TABLE `credit_cards` ADD CONSTRAINT `fk_users_credit_cards` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`)
// check database foreign key for user & credit_cards exists or not db.Migrator().HasConstraint(&User{}, "CreditCards") db.Migrator().HasConstraint(&User{}, "fk_users_credit_cards")
// drop database foreign key for user & credit_cards db.Migrator().DropConstraint(&User{}, "CreditCards") db.Migrator().DropConstraint(&User{}, "fk_users_credit_cards")
Indexes
type User struct { gorm.Model Name string`gorm:"size:255;index:idx_name,unique"` }
// Create index for Name field db.Migrator().CreateIndex(&User{}, "Name") db.Migrator().CreateIndex(&User{}, "idx_name")
// Drop index for Name field db.Migrator().DropIndex(&User{}, "Name") db.Migrator().DropIndex(&User{}, "idx_name")
// Check Index exists db.Migrator().HasIndex(&User{}, "Name") db.Migrator().HasIndex(&User{}, "idx_name")
type User struct { gorm.Model Name string`gorm:"size:255;index:idx_name,unique"` Name2 string`gorm:"size:255;index:idx_name_2,unique"` } // Rename index name db.Migrator().RenameIndex(&User{}, "Name", "Name2") db.Migrator().RenameIndex(&User{}, "idx_name", "idx_name_2")
Constraints
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:
