mirror of https://github.com/go-gorm/gorm.git
1162 lines
32 KiB
Markdown
1162 lines
32 KiB
Markdown
# GORM
|
|
|
|
The fantastic ORM library for Golang, aims to be developer friendly.
|
|
|
|
[](https://app.wercker.com/project/bykey/0cb7bb1039e21b74f8274941428e0921)
|
|
|
|
## Overview
|
|
|
|
* Full-Featured ORM (almost)
|
|
* Chainable API
|
|
* Auto Migrations
|
|
* Relations (Has One, Has Many, Belongs To, Many To Many, [Polymorphism](#polymorphism))
|
|
* Callbacks (Before/After Create/Save/Update/Delete/Find)
|
|
* Preloading (eager loading)
|
|
* Transactions
|
|
* Embed Anonymous Struct
|
|
* Soft Deletes
|
|
* Customizable Logger
|
|
* Iteration Support via [Rows](#row--rows)
|
|
* Every feature comes with tests
|
|
* Developer Friendly
|
|
|
|
# Getting Started
|
|
|
|
## Install
|
|
|
|
```
|
|
go get -u github.com/jinzhu/gorm
|
|
```
|
|
|
|
## Define Models (Structs)
|
|
|
|
```go
|
|
type User struct {
|
|
ID int
|
|
Birthday time.Time
|
|
Age int
|
|
Name string `sql:"size:255"` // Default size for string is 255, you could reset it with this tag
|
|
Num int `sql:"AUTO_INCREMENT"`
|
|
CreatedAt time.Time
|
|
UpdatedAt time.Time
|
|
DeletedAt time.Time
|
|
|
|
Emails []Email // One-To-Many relationship (has many)
|
|
BillingAddress Address // One-To-One relationship (has one)
|
|
BillingAddressID sql.NullInt64 // Foreign key of BillingAddress
|
|
ShippingAddress Address // One-To-One relationship (has one)
|
|
ShippingAddressID int // Foreign key of ShippingAddress
|
|
IgnoreMe int `sql:"-"` // Ignore this field
|
|
Languages []Language `gorm:"many2many:user_languages;"` // Many-To-Many relationship, 'user_languages' is join table
|
|
}
|
|
|
|
type Email struct {
|
|
ID int
|
|
UserID int `sql:"index"` // Foreign key (belongs to), tag `index` will create index for this field when using AutoMigrate
|
|
Email string `sql:"type:varchar(100);unique_index"` // Set field's sql type, tag `unique_index` will create unique index
|
|
Subscribed bool
|
|
}
|
|
|
|
type Address struct {
|
|
ID int
|
|
Address1 string `sql:"not null;unique"` // Set field as not nullable and unique
|
|
Address2 string `sql:"type:varchar(100);unique"`
|
|
Post sql.NullString `sql:"not null"`
|
|
}
|
|
|
|
type Language struct {
|
|
ID int
|
|
Name string `sql:"index:idx_name_code"` // Create index with name, and will create combined index if find other fields defined same name
|
|
Code string `sql:"index:idx_name_code"` // `unique_index` also works
|
|
}
|
|
```
|
|
|
|
## Conventions
|
|
|
|
* Table name is the plural of struct name's snake case, you can disable pluralization with `db.SingularTable(true)`, or [Specifying The Table Name For A Struct Permanently With TableName](#specifying-the-table-name-for-a-struct-permanently-with-tablename)
|
|
|
|
```go
|
|
type User struct{} // struct User's database table name is "users" by default, will be "user" if you disabled pluralisation
|
|
```
|
|
|
|
* Column name is the snake case of field's name
|
|
* Use `ID` field as primary key
|
|
* Use `CreatedAt` to store record's created time if field exists
|
|
* Use `UpdatedAt` to store record's updated time if field exists
|
|
* Use `DeletedAt` to store record's deleted time if field exists [Soft Delete](#soft-delete)
|
|
|
|
## Initialize Database
|
|
|
|
```go
|
|
import (
|
|
"github.com/jinzhu/gorm"
|
|
_ "github.com/lib/pq"
|
|
_ "github.com/go-sql-driver/mysql"
|
|
_ "github.com/mattn/go-sqlite3"
|
|
)
|
|
|
|
db, err := gorm.Open("postgres", "user=gorm dbname=gorm sslmode=disable")
|
|
// db, err := gorm.Open("mysql", "user:password@/dbname?charset=utf8&parseTime=True&loc=Local")
|
|
// db, err := gorm.Open("sqlite3", "/tmp/gorm.db")
|
|
|
|
// You can also use an existing database connection handle
|
|
// dbSql, _ := sql.Open("postgres", "user=gorm dbname=gorm sslmode=disable")
|
|
// db := gorm.Open("postgres", dbSql)
|
|
|
|
// Get database connection handle [*sql.DB](http://golang.org/pkg/database/sql/#DB)
|
|
db.DB()
|
|
|
|
// Then you could invoke `*sql.DB`'s functions with it
|
|
db.DB().Ping()
|
|
db.DB().SetMaxIdleConns(10)
|
|
db.DB().SetMaxOpenConns(100)
|
|
|
|
// Disable table name's pluralization
|
|
db.SingularTable(true)
|
|
```
|
|
|
|
## Migration
|
|
|
|
```go
|
|
// Create table
|
|
db.CreateTable(&User{})
|
|
|
|
// Drop table
|
|
db.DropTable(&User{})
|
|
|
|
// Automating Migration
|
|
db.AutoMigrate(&User{})
|
|
db.AutoMigrate(&User{}, &Product{}, &Order{})
|
|
// Feel free to change your struct, AutoMigrate will keep your database up-to-date.
|
|
// AutoMigrate will ONLY add *new columns* and *new indexes*,
|
|
// WON'T update current column's type or delete unused columns, to protect your data.
|
|
// If the table is not existing, AutoMigrate will create the table automatically.
|
|
```
|
|
|
|
# Basic CRUD
|
|
|
|
## Create Record
|
|
|
|
```go
|
|
user := User{Name: "Jinzhu", Age: 18, Birthday: time.Now()}
|
|
|
|
db.NewRecord(user) // => returns `true` if primary key is blank
|
|
|
|
db.Create(&user)
|
|
|
|
db.NewRecord(user) // => return `false` after `user` created
|
|
|
|
// Associations will be inserted automatically when save the record
|
|
user := User{
|
|
Name: "jinzhu",
|
|
BillingAddress: Address{Address1: "Billing Address - Address 1"},
|
|
ShippingAddress: Address{Address1: "Shipping Address - Address 1"},
|
|
Emails: []Email{{Email: "jinzhu@example.com"}, {Email: "jinzhu-2@example@example.com"}},
|
|
Languages: []Language{{Name: "ZH"}, {Name: "EN"}},
|
|
}
|
|
|
|
db.Create(&user)
|
|
//// BEGIN TRANSACTION;
|
|
//// INSERT INTO "addresses" (address1) VALUES ("Billing Address - Address 1");
|
|
//// INSERT INTO "addresses" (address1) VALUES ("Shipping Address - Address 1");
|
|
//// INSERT INTO "users" (name,billing_address_id,shipping_address_id) VALUES ("jinzhu", 1, 2);
|
|
//// INSERT INTO "emails" (user_id,email) VALUES (111, "jinzhu@example.com");
|
|
//// INSERT INTO "emails" (user_id,email) VALUES (111, "jinzhu-2@example.com");
|
|
//// INSERT INTO "languages" ("name") VALUES ('ZH');
|
|
//// INSERT INTO user_languages ("user_id","language_id") VALUES (111, 1);
|
|
//// INSERT INTO "languages" ("name") VALUES ('EN');
|
|
//// INSERT INTO user_languages ("user_id","language_id") VALUES (111, 2);
|
|
//// COMMIT;
|
|
```
|
|
|
|
Refer [Associations](#associations) for more details
|
|
|
|
## Query
|
|
|
|
```go
|
|
// Get the first record
|
|
db.First(&user)
|
|
//// SELECT * FROM users ORDER BY id LIMIT 1;
|
|
|
|
// Get the last record
|
|
db.Last(&user)
|
|
//// SELECT * FROM users ORDER BY id DESC LIMIT 1;
|
|
|
|
// Get all records
|
|
db.Find(&users)
|
|
//// SELECT * FROM users;
|
|
|
|
// Get record with primary key
|
|
db.First(&user, 10)
|
|
//// SELECT * FROM users WHERE id = 10;
|
|
```
|
|
|
|
### Query With Where (Plain SQL)
|
|
|
|
```go
|
|
// Get the first matched record
|
|
db.Where("name = ?", "jinzhu").First(&user)
|
|
//// SELECT * FROM users WHERE name = 'jinzhu' limit 1;
|
|
|
|
// Get all matched records
|
|
db.Where("name = ?", "jinzhu").Find(&users)
|
|
//// SELECT * FROM users WHERE name = 'jinzhu';
|
|
|
|
db.Where("name <> ?", "jinzhu").Find(&users)
|
|
|
|
// IN
|
|
db.Where("name in (?)", []string{"jinzhu", "jinzhu 2"}).Find(&users)
|
|
|
|
// LIKE
|
|
db.Where("name LIKE ?", "%jin%").Find(&users)
|
|
|
|
// AND
|
|
db.Where("name = ? and age >= ?", "jinzhu", "22").Find(&users)
|
|
```
|
|
|
|
### Query With Where (Struct & Map)
|
|
|
|
```go
|
|
// Struct
|
|
db.Where(&User{Name: "jinzhu", Age: 20}).First(&user)
|
|
//// SELECT * FROM users WHERE name = "jinzhu" AND age = 20 LIMIT 1;
|
|
|
|
// Map
|
|
db.Where(map[string]interface{}{"name": "jinzhu", "age": 20}).Find(&users)
|
|
//// SELECT * FROM users WHERE name = "jinzhu" AND age = 20;
|
|
|
|
// Slice of primary keys
|
|
db.Where([]int64{20, 21, 22}).Find(&users)
|
|
//// SELECT * FROM users WHERE id IN (20, 21, 22);
|
|
```
|
|
|
|
### Query With Not
|
|
|
|
```go
|
|
db.Not("name", "jinzhu").First(&user)
|
|
//// SELECT * FROM users WHERE name <> "jinzhu" LIMIT 1;
|
|
|
|
// Not In
|
|
db.Not("name", []string{"jinzhu", "jinzhu 2"}).Find(&users)
|
|
//// SELECT * FROM users WHERE name NOT IN ("jinzhu", "jinzhu 2");
|
|
|
|
// Not In slice of primary keys
|
|
db.Not([]int64{1,2,3}).First(&user)
|
|
//// SELECT * FROM users WHERE id NOT IN (1,2,3);
|
|
|
|
db.Not([]int64{}).First(&user)
|
|
//// SELECT * FROM users;
|
|
|
|
// Plain SQL
|
|
db.Not("name = ?", "jinzhu").First(&user)
|
|
//// SELECT * FROM users WHERE NOT(name = "jinzhu");
|
|
|
|
// Struct
|
|
db.Not(User{Name: "jinzhu"}).First(&user)
|
|
//// SELECT * FROM users WHERE name <> "jinzhu";
|
|
```
|
|
|
|
### Query With Inline Condition
|
|
|
|
```go
|
|
// Get by primary key
|
|
db.First(&user, 23)
|
|
//// SELECT * FROM users WHERE id = 23 LIMIT 1;
|
|
|
|
// Plain SQL
|
|
db.Find(&user, "name = ?", "jinzhu")
|
|
//// SELECT * FROM users WHERE name = "jinzhu";
|
|
|
|
db.Find(&users, "name <> ? AND age > ?", "jinzhu", 20)
|
|
//// SELECT * FROM users WHERE name <> "jinzhu" 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;
|
|
```
|
|
|
|
### Query With Or
|
|
|
|
```go
|
|
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"}).Find(&users)
|
|
//// SELECT * FROM users WHERE name = 'jinzhu' OR name = 'jinzhu 2';
|
|
|
|
// Map
|
|
db.Where("name = 'jinzhu'").Or(map[string]interface{}{"name": "jinzhu 2"}).Find(&users)
|
|
```
|
|
|
|
### Query Chains
|
|
|
|
Gorm has a chainable API, you could use it like this
|
|
|
|
```go
|
|
db.Where("name <> ?","jinzhu").Where("age >= ? and role <> ?",20,"admin").Find(&users)
|
|
//// SELECT * FROM users WHERE name <> 'jinzhu' AND age >= 20 AND role <> 'admin';
|
|
|
|
db.Where("role = ?", "admin").Or("role = ?", "super_admin").Not("name = ?", "jinzhu").Find(&users)
|
|
```
|
|
|
|
### Preloading (Eager loading)
|
|
|
|
```go
|
|
db.Preload("Orders").Find(&users)
|
|
//// SELECT * FROM users;
|
|
//// SELECT * FROM orders WHERE user_id IN (1,2,3,4);
|
|
|
|
db.Preload("Orders", "state NOT IN (?)", "cancelled").Find(&users)
|
|
//// SELECT * FROM users;
|
|
//// SELECT * FROM orders WHERE user_id IN (1,2,3,4) AND state NOT IN ('cancelled');
|
|
|
|
db.Where("state = ?", "active").Preload("Orders", "state NOT IN (?)", "cancelled").Find(&users)
|
|
//// SELECT * FROM users WHERE state = 'active';
|
|
//// SELECT * FROM orders WHERE user_id IN (1,2) AND state NOT IN ('cancelled');
|
|
|
|
db.Preload("Orders").Preload("Profile").Preload("Role").Find(&users)
|
|
//// SELECT * FROM users;
|
|
//// SELECT * FROM orders WHERE user_id IN (1,2,3,4); // has many
|
|
//// SELECT * FROM profiles WHERE user_id IN (1,2,3,4); // has one
|
|
//// SELECT * FROM roles WHERE id IN (4,5,6); // belongs to
|
|
```
|
|
|
|
## Update
|
|
|
|
```go
|
|
// Update an existing struct
|
|
db.First(&user)
|
|
user.Name = "jinzhu 2"
|
|
user.Age = 100
|
|
db.Save(&user)
|
|
//// UPDATE users SET name='jinzhu 2', age=100, updated_at = '2013-11-17 21:34:10' WHERE id=111;
|
|
|
|
db.Where("active = ?", true).Save(&user)
|
|
//// UPDATE users SET name='jinzhu 2', age=100, updated_at = '2013-11-17 21:34:10' WHERE id=111 AND active = true;
|
|
|
|
// Update an attribute if it is changed
|
|
db.Model(&user).Update("name", "hello")
|
|
//// UPDATE users SET name='hello', updated_at = '2013-11-17 21:34:10' WHERE id=111;
|
|
|
|
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;
|
|
|
|
db.First(&user, 111).Update("name", "hello")
|
|
//// SELECT * FROM users LIMIT 1;
|
|
//// UPDATE users SET name='hello', updated_at = '2013-11-17 21:34:10' WHERE id=111;
|
|
|
|
// Update multiple attributes if they are changed
|
|
db.Model(&user).Updates(map[string]interface{}{"name": "hello", "age": 18, "actived": false})
|
|
|
|
// Update multiple attributes if they are changed (update with struct only works with none zero values)
|
|
db.Model(&user).Updates(User{Name: "hello", Age: 18})
|
|
//// UPDATE users SET name='hello', age=18, updated_at = '2013-11-17 21:34:10' WHERE id = 111;
|
|
```
|
|
|
|
### Update Without Callbacks
|
|
|
|
By default, update will call BeforeUpdate, AfterUpdate callbacks, if you want to update w/o callbacks:
|
|
|
|
```go
|
|
db.Model(&user).UpdateColumn("name", "hello")
|
|
//// UPDATE users SET name='hello' WHERE id = 111;
|
|
|
|
// Update with struct only works with none zero values, or use map[string]interface{}
|
|
db.Model(&user).UpdateColumns(User{Name: "hello", Age: 18})
|
|
//// UPDATE users SET name='hello', age=18 WHERE id = 111;
|
|
```
|
|
|
|
### Batch Updates
|
|
|
|
```go
|
|
db.Table("users").Where("id = ?", 10).Updates(map[string]interface{}{"name": "hello", "age": 18})
|
|
//// UPDATE users SET name='hello', age=18 WHERE id = 10;
|
|
|
|
// Update with struct only works with none zero values, or use map[string]interface{}
|
|
db.Model(User{}).Updates(User{Name: "hello", Age: 18})
|
|
//// UPDATE users SET name='hello', age=18;
|
|
|
|
// Callbacks won't run when do batch updates
|
|
|
|
// Use `RowsAffected` to get the count of affected records
|
|
db.Model(User{}).Updates(User{Name: "hello", Age: 18}).RowsAffected
|
|
```
|
|
|
|
### Update with SQL Expression
|
|
|
|
```go
|
|
DB.Model(&product).Update("price", gorm.Expr("price * ? + ?", 2, 100))
|
|
//// UPDATE "products" SET "code" = 'L1212', "price" = price * '2' + '100', "updated_at" = '2013-11-17 21:34:10' WHERE "id" = '2';
|
|
|
|
DB.Model(&product).Updates(map[string]interface{}{"price": gorm.Expr("price * ? + ?", 2, 100)})
|
|
//// UPDATE "products" SET "code" = 'L1212', "price" = price * '2' + '100', "updated_at" = '2013-11-17 21:34:10' WHERE "id" = '2';
|
|
|
|
DB.Model(&product).UpdateColumn("quantity", gorm.Expr("quantity - ?", 1))
|
|
//// UPDATE "products" SET "quantity" = quantity - 1 WHERE "id" = '2';
|
|
|
|
DB.Model(&product).Where("quantity > 1").UpdateColumn("quantity", gorm.Expr("quantity - ?", 1))
|
|
//// UPDATE "products" SET "quantity" = quantity - 1 WHERE "id" = '2' AND quantity > 1;
|
|
```
|
|
|
|
## Delete
|
|
|
|
```go
|
|
// Delete an existing record
|
|
db.Delete(&email)
|
|
//// DELETE from emails where id=10;
|
|
```
|
|
|
|
### Batch Delete
|
|
|
|
```go
|
|
db.Where("email LIKE ?", "%jinzhu%").Delete(Email{})
|
|
//// DELETE from emails where email LIKE "%jinhu%";
|
|
```
|
|
|
|
### Soft Delete
|
|
|
|
If struct has `DeletedAt` field, it will get soft delete ability automatically!
|
|
Then it won't be deleted from database permanently when call `Delete`.
|
|
|
|
```go
|
|
db.Delete(&user)
|
|
//// UPDATE users SET deleted_at="2013-10-29 10:23" WHERE id = 111;
|
|
|
|
// Batch Delete
|
|
db.Where("age = ?", 20).Delete(&User{})
|
|
//// UPDATE users SET deleted_at="2013-10-29 10:23" WHERE age = 20;
|
|
|
|
// Soft deleted records will be ignored when query them
|
|
db.Where("age = 20").Find(&user)
|
|
//// SELECT * FROM users WHERE age = 20 AND (deleted_at IS NULL OR deleted_at <= '0001-01-02');
|
|
|
|
// Find soft deleted records with Unscoped
|
|
db.Unscoped().Where("age = 20").Find(&users)
|
|
//// SELECT * FROM users WHERE age = 20;
|
|
|
|
// Delete record permanently with Unscoped
|
|
db.Unscoped().Delete(&order)
|
|
//// DELETE FROM orders WHERE id=10;
|
|
```
|
|
|
|
## Associations
|
|
|
|
### Has One
|
|
|
|
```go
|
|
// User has one address
|
|
db.Model(&user).Related(&address)
|
|
//// SELECT * FROM addresses WHERE id = 123; // 123 is user's foreign key AddressId
|
|
|
|
// Specify the foreign key
|
|
db.Model(&user).Related(&address1, "BillingAddressId")
|
|
//// SELECT * FROM addresses WHERE id = 123; // 123 is user's foreign key BillingAddressId
|
|
```
|
|
|
|
### Belongs To
|
|
|
|
```go
|
|
// Email belongs to user
|
|
db.Model(&email).Related(&user)
|
|
//// SELECT * FROM users WHERE id = 111; // 111 is email's foreign key UserId
|
|
|
|
// Specify the foreign key
|
|
db.Model(&email).Related(&user, "ProfileId")
|
|
//// SELECT * FROM users WHERE id = 111; // 111 is email's foreign key ProfileId
|
|
```
|
|
|
|
### Has Many
|
|
|
|
```go
|
|
// User has many emails
|
|
db.Model(&user).Related(&emails)
|
|
//// SELECT * FROM emails WHERE user_id = 111;
|
|
// user_id is the foreign key, 111 is user's primary key's value
|
|
|
|
// Specify the foreign key
|
|
db.Model(&user).Related(&emails, "ProfileId")
|
|
//// SELECT * FROM emails WHERE profile_id = 111;
|
|
// profile_id is the foreign key, 111 is user's primary key's value
|
|
```
|
|
|
|
### Many To Many
|
|
|
|
```go
|
|
// User has many languages and belongs to many languages
|
|
db.Model(&user).Related(&languages, "Languages")
|
|
//// SELECT * FROM "languages" INNER JOIN "user_languages" ON "user_languages"."language_id" = "languages"."id" WHERE "user_languages"."user_id" = 111
|
|
// `Languages` is user's column name, this column's tag defined join table like this `gorm:"many2many:user_languages;"`
|
|
```
|
|
|
|
There is also a mode used to handle many to many relations easily
|
|
|
|
```go
|
|
// Query
|
|
db.Model(&user).Association("Languages").Find(&languages)
|
|
// same as `db.Model(&user).Related(&languages, "Languages")`
|
|
|
|
db.Where("name = ?", "ZH").First(&languageZH)
|
|
db.Where("name = ?", "EN").First(&languageEN)
|
|
|
|
// Append
|
|
db.Model(&user).Association("Languages").Append([]Language{languageZH, languageEN})
|
|
db.Model(&user).Association("Languages").Append([]Language{{Name: "DE"}})
|
|
db.Model(&user).Association("Languages").Append(Language{Name: "DE"})
|
|
|
|
// Delete
|
|
db.Model(&user).Association("Languages").Delete([]Language{languageZH, languageEN})
|
|
db.Model(&user).Association("Languages").Delete(languageZH, languageEN)
|
|
|
|
// Replace
|
|
db.Model(&user).Association("Languages").Replace([]Language{languageZH, languageEN})
|
|
db.Model(&user).Association("Languages").Replace(Language{Name: "DE"}, languageEN)
|
|
|
|
// Count
|
|
db.Model(&user).Association("Languages").Count()
|
|
// Return the count of languages the user has
|
|
|
|
// Clear
|
|
db.Model(&user).Association("Languages").Clear()
|
|
// Remove all relations between the user and languages
|
|
```
|
|
|
|
### Polymorphism
|
|
|
|
Supports polymorphic has-many and has-one associations.
|
|
|
|
```go
|
|
type Cat struct {
|
|
Id int
|
|
Name string
|
|
Toy Toy `gorm:"polymorphic:Owner;"`
|
|
}
|
|
|
|
type Dog struct {
|
|
Id int
|
|
Name string
|
|
Toy Toy `gorm:"polymorphic:Owner;"`
|
|
}
|
|
|
|
type Toy struct {
|
|
Id int
|
|
Name string
|
|
OwnerId int
|
|
OwnerType string
|
|
}
|
|
```
|
|
Note: polymorphic belongs-to and many-to-many are explicitly NOT supported, and will throw errors.
|
|
|
|
## Advanced Usage
|
|
|
|
## FirstOrInit
|
|
|
|
Get the first matched record, or initialize a record with search conditions.
|
|
|
|
```go
|
|
// Unfound
|
|
db.FirstOrInit(&user, User{Name: "non_existing"})
|
|
//// user -> User{Name: "non_existing"}
|
|
|
|
// Found
|
|
db.Where(User{Name: "Jinzhu"}).FirstOrInit(&user)
|
|
//// user -> User{Id: 111, Name: "Jinzhu", Age: 20}
|
|
db.FirstOrInit(&user, map[string]interface{}{"name": "jinzhu"})
|
|
//// user -> User{Id: 111, Name: "Jinzhu", Age: 20}
|
|
```
|
|
|
|
### Attrs
|
|
|
|
Ignore some values when searching, but use them to initialize the struct if record is not found.
|
|
|
|
```go
|
|
// Unfound
|
|
db.Where(User{Name: "non_existing"}).Attrs(User{Age: 20}).FirstOrInit(&user)
|
|
//// SELECT * FROM USERS WHERE name = 'non_existing';
|
|
//// user -> User{Name: "non_existing", Age: 20}
|
|
|
|
db.Where(User{Name: "noexisting_user"}).Attrs("age", 20).FirstOrInit(&user)
|
|
//// SELECT * FROM USERS WHERE name = 'non_existing';
|
|
//// user -> User{Name: "non_existing", Age: 20}
|
|
|
|
// Found
|
|
db.Where(User{Name: "Jinzhu"}).Attrs(User{Age: 30}).FirstOrInit(&user)
|
|
//// SELECT * FROM USERS WHERE name = jinzhu';
|
|
//// user -> User{Id: 111, Name: "Jinzhu", Age: 20}
|
|
```
|
|
|
|
### Assign
|
|
|
|
Ignore some values when searching, but assign it to the result regardless it is found or not.
|
|
|
|
```go
|
|
// Unfound
|
|
db.Where(User{Name: "non_existing"}).Assign(User{Age: 20}).FirstOrInit(&user)
|
|
//// user -> User{Name: "non_existing", Age: 20}
|
|
|
|
// Found
|
|
db.Where(User{Name: "Jinzhu"}).Assign(User{Age: 30}).FirstOrInit(&user)
|
|
//// SELECT * FROM USERS WHERE name = jinzhu';
|
|
//// user -> User{Id: 111, Name: "Jinzhu", Age: 30}
|
|
```
|
|
|
|
## FirstOrCreate
|
|
|
|
Get the first matched record, or create with search conditions.
|
|
|
|
```go
|
|
// Unfound
|
|
db.FirstOrCreate(&user, User{Name: "non_existing"})
|
|
//// INSERT INTO "users" (name) VALUES ("non_existing");
|
|
//// user -> User{Id: 112, Name: "non_existing"}
|
|
|
|
// Found
|
|
db.Where(User{Name: "Jinzhu"}).FirstOrCreate(&user)
|
|
//// user -> User{Id: 111, Name: "Jinzhu"}
|
|
```
|
|
|
|
### Attrs
|
|
|
|
Ignore some values when searching, but use them to create the struct if record is not found. like `FirstOrInit`
|
|
|
|
```go
|
|
// Unfound
|
|
db.Where(User{Name: "non_existing"}).Attrs(User{Age: 20}).FirstOrCreate(&user)
|
|
//// SELECT * FROM users WHERE name = 'non_existing';
|
|
//// INSERT INTO "users" (name, age) VALUES ("non_existing", 20);
|
|
//// user -> User{Id: 112, Name: "non_existing", Age: 20}
|
|
|
|
// Found
|
|
db.Where(User{Name: "jinzhu"}).Attrs(User{Age: 30}).FirstOrCreate(&user)
|
|
//// SELECT * FROM users WHERE name = 'jinzhu';
|
|
//// user -> User{Id: 111, Name: "jinzhu", Age: 20}
|
|
```
|
|
|
|
### Assign
|
|
|
|
Ignore some values when searching, but assign it to the record regardless it is found or not, then save back to database. like `FirstOrInit`
|
|
|
|
```go
|
|
// Unfound
|
|
db.Where(User{Name: "non_existing"}).Assign(User{Age: 20}).FirstOrCreate(&user)
|
|
//// SELECT * FROM users WHERE name = 'non_existing';
|
|
//// INSERT INTO "users" (name, age) VALUES ("non_existing", 20);
|
|
//// user -> User{Id: 112, Name: "non_existing", Age: 20}
|
|
|
|
// Found
|
|
db.Where(User{Name: "jinzhu"}).Assign(User{Age: 30}).FirstOrCreate(&user)
|
|
//// SELECT * FROM users WHERE name = 'jinzhu';
|
|
//// UPDATE users SET age=30 WHERE id = 111;
|
|
//// user -> User{Id: 111, Name: "jinzhu", Age: 30}
|
|
```
|
|
|
|
## Select
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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;
|
|
|
|
// ReOrder
|
|
db.Order("age desc").Find(&users1).Order("age", true).Find(&users2)
|
|
//// SELECT * FROM users ORDER BY age desc; (users1)
|
|
//// SELECT * FROM users ORDER BY age; (users2)
|
|
```
|
|
|
|
## Limit
|
|
|
|
```go
|
|
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)
|
|
```
|
|
|
|
## Offset
|
|
|
|
```go
|
|
db.Offset(3).Find(&users)
|
|
//// SELECT * FROM users OFFSET 3;
|
|
|
|
// Cancel offset condition with -1
|
|
db.Offset(10).Find(&users1).Offset(-1).Find(&users2)
|
|
//// SELECT * FROM users OFFSET 10; (users1)
|
|
//// SELECT * FROM users; (users2)
|
|
```
|
|
|
|
## Count
|
|
|
|
```go
|
|
db.Where("name = ?", "jinzhu").Or("name = ?", "jinzhu 2").Find(&users).Count(&count)
|
|
//// SELECT * from USERS WHERE name = 'jinzhu' OR name = 'jinzhu 2'; (users)
|
|
//// SELECT count(*) FROM users WHERE name = 'jinzhu' OR name = 'jinzhu 2'; (count)
|
|
|
|
db.Model(User{}).Where("name = ?", "jinzhu").Count(&count)
|
|
//// SELECT count(*) FROM users WHERE name = 'jinzhu'; (count)
|
|
|
|
db.Table("deleted_users").Count(&count)
|
|
//// SELECT count(*) FROM deleted_users;
|
|
```
|
|
|
|
## Pluck
|
|
|
|
Get selected attributes as map
|
|
|
|
```go
|
|
var ages []int64
|
|
db.Find(&users).Pluck("age", &ages)
|
|
|
|
var names []string
|
|
db.Model(&User{}).Pluck("name", &names)
|
|
|
|
db.Table("deleted_users").Pluck("name", &names)
|
|
|
|
// Requesting more than one column? Do it like this:
|
|
db.Select("name, age").Find(&users)
|
|
```
|
|
|
|
## Raw SQL
|
|
|
|
```go
|
|
db.Exec("DROP TABLE users;")
|
|
db.Exec("UPDATE orders SET shipped_at=? WHERE id IN (?)", time.Now, []int64{11,22,33})
|
|
```
|
|
|
|
## Row & Rows
|
|
|
|
It is even possible to get query result as `*sql.Row` or `*sql.Rows`
|
|
|
|
```go
|
|
row := db.Table("users").Where("name = ?", "jinzhu").Select("name, age").Row() // (*sql.Row)
|
|
row.Scan(&name, &age)
|
|
|
|
rows, err := db.Model(User{}).Where("name = ?", "jinzhu").Select("name, age, email").Rows() // (*sql.Rows, error)
|
|
defer rows.Close()
|
|
for rows.Next() {
|
|
...
|
|
rows.Scan(&name, &age, &email)
|
|
...
|
|
}
|
|
|
|
// Raw SQL
|
|
rows, err := db.Raw("select name, age, email from users where name = ?", "jinzhu").Rows() // (*sql.Rows, error)
|
|
defer rows.Close()
|
|
for rows.Next() {
|
|
...
|
|
rows.Scan(&name, &age, &email)
|
|
...
|
|
}
|
|
```
|
|
|
|
## Scan
|
|
|
|
Scan results into another struct.
|
|
|
|
```go
|
|
type Result struct {
|
|
Name string
|
|
Age int
|
|
}
|
|
|
|
var result Result
|
|
db.Table("users").Select("name, age").Where("name = ?", 3).Scan(&result)
|
|
|
|
// Raw SQL
|
|
db.Raw("SELECT name, age FROM users WHERE name = ?", 3).Scan(&result)
|
|
```
|
|
|
|
## Group & Having
|
|
|
|
```go
|
|
rows, err := db.Table("orders").Select("date(created_at) as date, sum(amount) as total").Group("date(created_at)").Rows()
|
|
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()
|
|
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)
|
|
```
|
|
|
|
## Joins
|
|
|
|
```go
|
|
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)
|
|
```
|
|
|
|
## Transactions
|
|
|
|
All individual save and delete operations are run in a transaction by default.
|
|
|
|
```go
|
|
// begin
|
|
tx := db.Begin()
|
|
|
|
// rollback
|
|
tx.Rollback()
|
|
|
|
// commit
|
|
tx.Commit()
|
|
```
|
|
|
|
## Scopes
|
|
|
|
```go
|
|
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.Scopes(AmountGreaterThan1000).Where("status in (?)", status)
|
|
}
|
|
}
|
|
|
|
db.Scopes(AmountGreaterThan1000, PaidWithCreditCard).Find(&orders)
|
|
// Find all credit card orders and amount greater than 1000
|
|
|
|
db.Scopes(AmountGreaterThan1000, PaidWithCod).Find(&orders)
|
|
// Find all COD orders and amount greater than 1000
|
|
|
|
db.Scopes(OrderStatus([]string{"paid", "shipped"})).Find(&orders)
|
|
// Find all paid, shipped orders
|
|
```
|
|
|
|
## Callbacks
|
|
|
|
Callbacks are methods defined on the pointer of struct.
|
|
If any callback returns an error, gorm will stop future operations and rollback all changes.
|
|
|
|
Here is the list of all available callbacks:
|
|
(listed in the same order in which they will get called during the respective operations)
|
|
|
|
### Creating An Object
|
|
|
|
```go
|
|
BeforeSave
|
|
BeforeCreate
|
|
// save before associations
|
|
// save self
|
|
// save after associations
|
|
AfterCreate
|
|
AfterSave
|
|
```
|
|
### Updating An Object
|
|
|
|
```go
|
|
BeforeSave
|
|
BeforeUpdate
|
|
// save before associations
|
|
// save self
|
|
// save after associations
|
|
AfterUpdate
|
|
AfterSave
|
|
```
|
|
|
|
### Destroying An Object
|
|
|
|
```go
|
|
BeforeDelete
|
|
// delete self
|
|
AfterDelete
|
|
```
|
|
|
|
### After Find
|
|
|
|
```go
|
|
// load data from database
|
|
AfterFind
|
|
```
|
|
|
|
### Example
|
|
|
|
```go
|
|
func (u *User) BeforeUpdate() (err error) {
|
|
if u.readonly() {
|
|
err = errors.New("read only user")
|
|
}
|
|
return
|
|
}
|
|
|
|
// Rollback the insertion if user's id greater than 1000
|
|
func (u *User) AfterCreate() (err error) {
|
|
if (u.Id > 1000) {
|
|
err = errors.New("user id is already greater than 1000")
|
|
}
|
|
return
|
|
}
|
|
```
|
|
|
|
As you know, save/delete operations in gorm are running in a transaction,
|
|
This is means if changes made in the transaction is not visiable unless it is commited,
|
|
So if you want to use those changes in your callbacks, you need to run SQL in same transaction.
|
|
Fortunately, gorm support pass transaction to callbacks as you needed, you could do it like this:
|
|
|
|
```go
|
|
func (u *User) AfterCreate(tx *gorm.DB) (err error) {
|
|
tx.Model(u).Update("role", "admin")
|
|
return
|
|
}
|
|
```
|
|
|
|
## Specifying The Table Name
|
|
|
|
```go
|
|
// Create `deleted_users` table with struct User's definition
|
|
db.Table("deleted_users").CreateTable(&User{})
|
|
|
|
var deleted_users []User
|
|
db.Table("deleted_users").Find(&deleted_users)
|
|
//// SELECT * FROM deleted_users;
|
|
|
|
db.Table("deleted_users").Where("name = ?", "jinzhu").Delete()
|
|
//// DELETE FROM deleted_users WHERE name = 'jinzhu';
|
|
```
|
|
|
|
### Specifying The Table Name For A Struct Permanently with TableName
|
|
|
|
```go
|
|
type Cart struct {
|
|
}
|
|
|
|
func (c Cart) TableName() string {
|
|
return "shopping_cart"
|
|
}
|
|
|
|
func (u User) TableName() string {
|
|
if u.Role == "admin" {
|
|
return "admin_users"
|
|
} else {
|
|
return "users"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
```go
|
|
query := db.Where("name = ?", "jinzhu").First(&user)
|
|
query := db.First(&user).Limit(10).Find(&users)
|
|
// query.Error will return the last happened error
|
|
|
|
// So you could do error handing in your application like this:
|
|
if err := db.Where("name = ?", "jinzhu").First(&user).Error; err != nil {
|
|
// error handling...
|
|
}
|
|
|
|
// RecordNotFound
|
|
// If no record found when you query data, gorm will return RecordNotFound error, you could check it like this:
|
|
db.Where("name = ?", "hello world").First(&User{}).Error == gorm.RecordNotFound
|
|
// Or use the shortcut method
|
|
db.Where("name = ?", "hello world").First(&user).RecordNotFound()
|
|
|
|
if db.Model(&user).Related(&credit_card).RecordNotFound() {
|
|
// no credit card found error handling
|
|
}
|
|
```
|
|
|
|
## Logger
|
|
|
|
Gorm has built-in logger support
|
|
|
|
```go
|
|
// Enable Logger
|
|
db.LogMode(true)
|
|
|
|
// Diable Logger
|
|
db.LogMode(false)
|
|
|
|
// Debug a single operation
|
|
db.Debug().Where("name = ?", "jinzhu").First(&User{})
|
|
```
|
|
|
|
|
|
|
|
### Customize Logger
|
|
|
|
```go
|
|
// Refer gorm's default logger for how to: https://github.com/jinzhu/gorm/blob/master/logger.go#files
|
|
db.SetLogger(gorm.Logger{revel.TRACE})
|
|
db.SetLogger(log.New(os.Stdout, "\r\n", 0))
|
|
```
|
|
|
|
## Existing Schema
|
|
|
|
If you have an existing database schema, and the primary key field is different from `id`, you can add a tag to the field structure to specify that this field is a primary key.
|
|
|
|
```go
|
|
type Animal struct {
|
|
AnimalId int64 `gorm:"primary_key"`
|
|
Birthday time.Time `sql:"DEFAULT:current_timestamp"`
|
|
Name string `sql:"default:'galeone'"`
|
|
Age int64
|
|
}
|
|
```
|
|
|
|
If your column names differ from the struct fields, you can specify them like this:
|
|
|
|
```go
|
|
type Animal struct {
|
|
AnimalId int64 `gorm:"column:beast_id;primary_key"`
|
|
Birthday time.Time `gorm:"column:day_of_the_beast"`
|
|
Age int64 `gorm:"column:age_of_the_beast"`
|
|
}
|
|
```
|
|
|
|
## Composite Primary Key
|
|
|
|
```go
|
|
type Product struct {
|
|
ID string `gorm:"primary_key"`
|
|
LanguageCode string `gorm:"primary_key"`
|
|
}
|
|
```
|
|
|
|
## Database Indexes & Foreign Key
|
|
|
|
```go
|
|
// Add foreign key
|
|
// 1st param : foreignkey field
|
|
// 2nd param : destination table(id)
|
|
// 3rd param : ONDELETE
|
|
// 4th param : ONUPDATE
|
|
db.Model(&User{}).AddForeignKey("user_id", "destination_table(id)", "CASCADE", "RESTRICT")
|
|
|
|
// Add index
|
|
db.Model(&User{}).AddIndex("idx_user_name", "name")
|
|
|
|
// Multiple column index
|
|
db.Model(&User{}).AddIndex("idx_user_name_age", "name", "age")
|
|
|
|
// Add unique index
|
|
db.Model(&User{}).AddUniqueIndex("idx_user_name", "name")
|
|
|
|
// Multiple column unique index
|
|
db.Model(&User{}).AddUniqueIndex("idx_user_name_age", "name", "age")
|
|
|
|
// Remove index
|
|
db.Model(&User{}).RemoveIndex("idx_user_name")
|
|
```
|
|
|
|
## Default values
|
|
|
|
If you have defined a default value in the `sql` tag (see the struct Animal above) the generated create/update SQl will ignore these fields if is set blank data.
|
|
|
|
Eg.
|
|
|
|
```go
|
|
db.Create(&Animal{Age: 99, Name: ""})
|
|
```
|
|
|
|
The generated query will be:
|
|
|
|
```sql
|
|
INSERT INTO animals("age") values('99');
|
|
```
|
|
|
|
The same thing occurs in update statements.
|
|
|
|
## More examples with query chain
|
|
|
|
```go
|
|
db.First(&first_article).Count(&total_count).Limit(10).Find(&first_page_articles).Offset(10).Find(&second_page_articles)
|
|
//// SELECT * FROM articles LIMIT 1; (first_article)
|
|
//// SELECT count(*) FROM articles; (total_count)
|
|
//// SELECT * FROM articles LIMIT 10; (first_page_articles)
|
|
//// SELECT * FROM articles LIMIT 10 OFFSET 10; (second_page_articles)
|
|
|
|
|
|
db.Where("created_at > ?", "2013-10-10").Find(&cancelled_orders, "state = ?", "cancelled").Find(&shipped_orders, "state = ?", "shipped")
|
|
//// SELECT * FROM orders WHERE created_at > '2013/10/10' AND state = 'cancelled'; (cancelled_orders)
|
|
//// SELECT * FROM orders WHERE created_at > '2013/10/10' AND state = 'shipped'; (shipped_orders)
|
|
|
|
|
|
// Use variables to keep query chain
|
|
todays_orders := db.Where("created_at > ?", "2013-10-29")
|
|
cancelled_orders := todays_orders.Where("state = ?", "cancelled")
|
|
shipped_orders := todays_orders.Where("state = ?", "shipped")
|
|
|
|
|
|
// Search with shared conditions for different tables
|
|
db.Where("product_name = ?", "fancy_product").Find(&orders).Find(&shopping_carts)
|
|
//// SELECT * FROM orders WHERE product_name = 'fancy_product'; (orders)
|
|
//// SELECT * FROM carts WHERE product_name = 'fancy_product'; (shopping_carts)
|
|
|
|
|
|
// Search with shared conditions from different tables with specified table
|
|
db.Where("mail_type = ?", "TEXT").Find(&users1).Table("deleted_users").Find(&users2)
|
|
//// SELECT * FROM users WHERE mail_type = 'TEXT'; (users1)
|
|
//// SELECT * FROM deleted_users WHERE mail_type = 'TEXT'; (users2)
|
|
|
|
|
|
// FirstOrCreate example
|
|
db.Where("email = ?", "x@example.org").Attrs(User{RegisteredIp: "111.111.111.111"}).FirstOrCreate(&user)
|
|
//// SELECT * FROM users WHERE email = 'x@example.org';
|
|
//// INSERT INTO "users" (email,registered_ip) VALUES ("x@example.org", "111.111.111.111") // if record not found
|
|
```
|
|
|
|
## TODO
|
|
* db.Select("Languages", "Name").Update(&user)
|
|
db.Omit("Languages").Update(&user)
|
|
* Auto migrate indexes
|
|
* Github Pages
|
|
* AlertColumn, DropColumn
|
|
* R/W Splitting, Validation
|
|
|
|
# Author
|
|
|
|
**jinzhu**
|
|
|
|
* <http://github.com/jinzhu>
|
|
* <wosmvp@gmail.com>
|
|
* <http://twitter.com/zhangjinzhu>
|
|
|
|
## License
|
|
|
|
Released under the [MIT License](https://github.com/jinzhu/gorm/blob/master/License).
|
|
|
|
[](http://godoc.org/github.com/jinzhu/gorm)
|