GORM

https://gorm.io/docs
Admin
GORM is a fantastic and developer-friendly ORM (Object-Relational Mapping) library for Golang. It...
Tokens:149,512
Snippets:1,095
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick Start with Generics API

Source: https://gorm.io/docs/index.html

Quick Start example using the Generics API (>= v1.30.0). It defines a Product model, opens a SQLite database, and performs create, read, update, and delete operations using gorm.G[Product].

```go
package main  
  
import (  
  "context"  
  "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")  
  }  
  
  ctx := context.Background()  
  
  // Migrate the schema  
  db.AutoMigrate(&Product{})  
  
  // Create  
  err = gorm.G[Product](db).Create(ctx, &Product{Code: "D42", Price: 100})  
  
  // Read  
  product, err := gorm.G[Product](db).Where("id = ?", 1).First(ctx) // find product with integer primary key  
  products, err := gorm.G[Product](db).Where("code = ?", "D42").Find(ctx) // find product with code D42  
  
  // Update - update product's price to 200  
  err = gorm.G[Product](db).Where("id = ?", product.ID).Update(ctx, "Price", 200)  
  // Update - update multiple fields  
  err = gorm.G[Product](db).Where("id = ?", product.ID).Updates(ctx, Product{Code: "D42", Price: 100})  
  
  // Delete - delete product  
  err = gorm.G[Product](db).Where("id = ?", product.ID).Delete(ctx)  
}  
```

--------------------------------

### Quick Start with Traditional API

Source: https://gorm.io/docs/index.html

Quick Start example using the Traditional API. It defines a Product model, opens a SQLite database, and performs create, read, update, and delete operations using the standard GORM methods.

```go
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")  
  }  
  
  // Migrate the schema  
  db.AutoMigrate(&Product{})  
  
  // Create  
  db.Create(&Product{Code: "D42", Price: 100})  
  
  // Read  
  var product Product  
  db.First(&product, 1) // find product with integer primary key  
  db.First(&product, "code = ?", "D42") // find product with code D42  
  
  // Update - update product's price to 200  
  db.Model(&product).Update("Price", 200)  
  // Update - update multiple fields  
  db.Model(&product).Updates(Product{Price: 200, Code: "F42"}) // non-zero fields  
  db.Model(&product).Updates(map[string]interface{}{"Price": 200, "Code": "F42"})  
  
  // Delete - delete product  
  db.Delete(&product, 1)  
}  
```

--------------------------------

### GORM v2 Quick Start with SQLite

Source: https://gorm.io/docs/v2_release_note.html

Quick start example showing how to open a SQLite database with GORM v2 and perform basic CRUD operations. Most CRUD API kept compatibility with v1.

```go
import (  
  "gorm.io/gorm"  
  "gorm.io/driver/sqlite"  
)  
  
func init() {  
  db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{})  
  
  // Most CRUD API kept compatibility  
  db.AutoMigrate(&Product{})  
  db.Create(&user)  
  db.First(&user, 1)  
  db.Model(&user).Update("Age", 18)  
  db.Model(&user).Omit("Role").Updates(map[string]interface{}{"Name": "jinzhu", "Role": "admin"})  
  db.Delete(&user)  
}  

```

--------------------------------

### Install GORM and SQLite driver

Source: https://gorm.io/docs/index.html

Install the GORM library and the SQLite driver using the Go module tool.

```bash
go get -u gorm.io/gorm  
go get -u gorm.io/driver/sqlite  
```

--------------------------------

### PrepareStmt example

Source: https://gorm.io/docs/gorm_config.html

Shows how to enable prepared statements caching by setting PrepareStmt to true.

```go
db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{  
  PrepareStmt: false,  
})  
```

--------------------------------

### Start Association Mode

Source: https://gorm.io/docs/associations.html

To start Association Mode, specify the source model and the relationship's field name. The source model must contain a primary key, and the field name should match an existing association. The example shows initializing Association Mode for Languages and checking for errors.

```go
var user User  
db.Model(&user).Association("Languages")  
// Check for errors  
error := db.Model(&user).Association("Languages").Error  
```

--------------------------------

### DryRun Session and Global Mode Examples

Source: https://gorm.io/docs/session.html

Shows how to use DryRun mode in a session to generate SQL without executing, and how to enable DryRun globally via gorm.Config. Includes examples for PostgreSQL and MySQL SQL generation.

```go
// session mode  
stmt := db.Session(&Session{DryRun: true}).First(&user, 1).Statement  
stmt.SQL.String() //=> SELECT * FROM `users` WHERE `id` = $1 ORDER BY `id`  
stmt.Vars         //=> []interface{}{1}  
  
// globally mode with DryRun  
db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{DryRun: true})  
  
// different databases generate different SQL  
stmt := db.Find(&user, 1).Statement  
stmt.SQL.String() //=> SELECT * FROM `users` WHERE `id` = $1 // PostgreSQL  
stmt.SQL.String() //=> SELECT * FROM `users` WHERE `id` = ?  // MySQL  
stmt.Vars         //=> []interface{}{1}  
```

--------------------------------

### Clause Builder example with Offset and Limit

Source: https://gorm.io/docs/sql_builder.html

Shows how different databases generate different SQL for the same GORM query. The example uses Offset and Limit, and the comments show the generated SQL for SQL Server and MySQL.

```go
db.Offset(10).Limit(5).Find(&users)  
// Generated for SQL Server  
// SELECT * FROM "users" OFFSET 10 ROW FETCH NEXT 5 ROWS ONLY  
// Generated for MySQL  
// SELECT * FROM `users` LIMIT 5 OFFSET 10  

```

--------------------------------

### DryRun example

Source: https://gorm.io/docs/gorm_config.html

Shows how to enable DryRun mode to generate SQL without executing it, useful for testing or preparing SQL.

```go
db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{  
  DryRun: false,  
})  
```

--------------------------------

### Creating an object: BeforeCreate and AfterCreate example

Source: https://gorm.io/docs/hooks.html

Example hooks for creating an object. BeforeCreate sets a UUID and validates the user, returning an error to prevent saving invalid data. AfterCreate updates the role to 'admin' when the user ID is 1.

```go
func (u *User) BeforeCreate(tx *gorm.DB) (err error) {  
  u.UUID = uuid.New()  
  
  if !u.IsValid() {  
    err = errors.New("can't save invalid data")  
  }  
  return  
}  
  
func (u *User) AfterCreate(tx *gorm.DB) (err error) {  
  if u.ID == 1 {  
    tx.Model(u).Update("role", "admin")  
  }  
  return  
}  

```

--------------------------------

### Querying an object: AfterFind example

Source: https://gorm.io/docs/hooks.html

Example AfterFind hook that sets a default membership value when the user's membership is empty.

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

```

--------------------------------

### Start transaction with specific resolver and mode

Source: https://gorm.io/docs/dbresolver.html

Shows how to start a transaction using a specific resolver and mode. During a transaction, DBResolver keeps using the transaction and does not switch to sources/replicas based on configuration.

```go
// Start transaction based on default replicas db  
tx := db.Clauses(dbresolver.Read).Begin()  
  
// Start transaction based on default sources db  
tx := db.Clauses(dbresolver.Write).Begin()  
  
// Start transaction based on `secondary`'s sources  
tx := db.Clauses(dbresolver.Use("secondary"), dbresolver.Write).Begin()  
```

--------------------------------

### NamingStrategy options example

Source: https://gorm.io/docs/gorm_config.html

Shows how to customize naming conventions using schema.NamingStrategy with options like TablePrefix, SingularTable, NoLowerCase, and NameReplacer.

```go
db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{  
  NamingStrategy: schema.NamingStrategy{  
    TablePrefix: "t_",   // table name prefix, table for `User` would be `t_users`  
    SingularTable: true, // use singular table name, table for `User` would be `user` with this option enabled  
    NoLowerCase: true, // skip the snake_casing of names  
    NameReplacer: strings.NewReplacer("CID", "Cid"), // use name replacer to change struct/field name before convert it to db name  
  },  
})  
```

--------------------------------

### Install GORM CLI tool

Source: https://gorm.io/docs/the_generics_way.html

Installs the GORM CLI tool required for the code generator workflow.

```bash
go install gorm.io/cli/gorm@latest  
```

--------------------------------

### Optimizer/Index/Comment Hints

Source: https://gorm.io/docs/v2_release_note.html

Add optimizer, index, and comment hints to queries using the gorm.io/hints package. The examples show hints.New, hints.UseIndex, and hints.Comment.

```go
import "gorm.io/hints"  
  
// Optimizer Hints  
db.Clauses(hints.New("hint")).Find(&User{})  
// SELECT * /*+ hint */ FROM `users`  
  
// Index Hints  
db.Clauses(hints.UseIndex("idx_user_name")).Find(&User{})  
// SELECT * FROM `users` USE INDEX (`idx_user_name`)  
  
// Comment Hints  
db.Clauses(hints.Comment("select", "master")).Find(&User{})  
// SELECT /*master*/ * FROM `users`;  

```

--------------------------------

### Updating an object: BeforeUpdate and AfterUpdate example

Source: https://gorm.io/docs/hooks.html

Example hooks for updating an object. BeforeUpdate returns an error for read-only users. AfterUpdate updates related Address records in the same transaction when the user is confirmed.

```go
func (u *User) BeforeUpdate(tx *gorm.DB) (err error) {  
  if u.readonly() {  
    err = errors.New("read only user")  
  }  
  return  
}  
  
// Updating data in same transaction  
func (u *User) AfterUpdate(tx *gorm.DB) (err error) {  
  if u.Confirmed {  
    tx.Model(&Address{}).Where("user_id = ?", u.ID).Update("verfied", true)  
  }  
  return  
}  

```

--------------------------------

### BeforeCreate hook example

Source: https://gorm.io/docs/create.html

Define a BeforeCreate hook to run custom logic before a record is created. The example sets a UUID and returns an error for the admin role, which will abort the creation.

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

```

--------------------------------

### NowFunc example

Source: https://gorm.io/docs/gorm_config.html

Shows how to customize the function used to generate timestamps by setting NowFunc in the GORM config.

```go
db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{  
  NowFunc: func() time.Time {  
    return time.Now().Local()  
  },  
})  
```

--------------------------------

### DisableAutomaticPing example

Source: https://gorm.io/docs/gorm_config.html

Shows how to disable automatic pinging after database initialization by setting DisableAutomaticPing to true.

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

--------------------------------

### StatementModifier example with hints

Source: https://gorm.io/docs/sql_builder.html

Shows using the StatementModifier interface with the hints package to add a hint to the generated SQL. The comment shows the resulting SQL.

```go
import "gorm.io/hints"  
  
db.Clauses(hints.New("hint")).Find(&User{})  
// SELECT * /*+ hint */ FROM `users`  

```

--------------------------------

### Count associations with and without conditions

Source: https://gorm.io/docs/associations.html

Gets the count of current associations. The second example shows counting with a condition applied to the source model before the association.

```go
// Count all languages  
db.Model(&user).Association("Languages").Count()  
  
// Count with conditions  
codes := []string{"zh-CN", "en-US", "ja-JP"}  
db.Model(&user).Where("code IN ?", codes).Association("Languages").Count()  
```

--------------------------------

### Order callbacks with Before and After

Source: https://gorm.io/docs/write_plugins.html

Shows how to register callbacks with specific ordering relative to existing callbacks, using Before and After methods. Includes examples for Create, Query, Delete, and Update operations, and wildcard ordering.

```go
// Register to execute before the 'gorm:create' callback  
db.Callback().Create().Before("gorm:create").Register("update_created_at", updateCreated)  
  
// Register to execute after the 'gorm:create' callback  
db.Callback().Create().After("gorm:create").Register("update_created_at", updateCreated)  
  
// Register to execute after the 'gorm:query' callback  
db.Callback().Query().After("gorm:query").Register("my_plugin:after_query", afterQuery)  
  
// Register to execute after the 'gorm:delete' callback  
db.Callback().Delete().After("gorm:delete").Register("my_plugin:after_delete", afterDelete)  
  
// Register to execute before the 'gorm:update' callback  
db.Callback().Update().Before("gorm:update").Register("my_plugin:before_update", beforeUpdate)  
  
// Register to execute before 'gorm:create' and after 'gorm:before_create'  
db.Callback().Create().Before("gorm:create").After("gorm:before_create").Register("my_plugin:before_create", beforeCreate)  
  
// Register to execute before any other callbacks  
db.Callback().Create().Before("*").Register("update_created_at", updateCreated)  
  
// Register to execute after any other callbacks  
db.Callback().Create().After("*").Register("update_created_at", updateCreated)  
```

--------------------------------

### Automatic connection switching examples

Source: https://gorm.io/docs/dbresolver.html

Shows how DBResolver automatically switches connections based on the working table or struct. For RAW SQL, it extracts the table name and uses sources unless the SQL starts with SELECT (except SELECT... FOR UPDATE).

```go
// `User` Resolver Examples  
db.Table("users").Rows() // replicas `db5`  
db.Model(&User{}).Find(&AdvancedUser{}) // replicas `db5`  
db.Exec("update users set name = ?", "jinzhu") // sources `db1`  
db.Raw("select name from users").Row().Scan(&name) // replicas `db5`  
db.Create(&user) // sources `db1`  
db.Delete(&User{}, "name = ?", "jinzhu") // sources `db1`  
db.Table("users").Update("name", "jinzhu") // sources `db1`  
  
// Global Resolver Examples  
db.Find(&Pet{}) // replicas `db3`/`db4`  
db.Save(&Pet{}) // sources `db2`  
  
// Orders Resolver Examples  
db.Find(&Order{}) // replicas `db8`  
db.Table("orders").Find(&Report{}) // replicas `db8`  
```

--------------------------------

### Set / Get

Source: https://gorm.io/docs/settings.html

Use `Set` / `Get` to pass settings to hooks methods. `Set` stores a value in the current `*gorm.DB` instance, and `Get` retrieves it from the same instance.

```APIDOC
## Set / Get

### Description
Use `Set` / `Get` to pass settings to hooks methods. `Set` stores a value in the current `*gorm.DB` instance, and `Get` retrieves it from the same instance.

### Method
Not applicable (GORM method)

### Endpoint
Not applicable (GORM method)

### Parameters
#### Set
- **key** (string) - Required - The key under which the value is stored.
- **value** (interface{}) - Required - The value to store.

#### Get
- **key** (string) - Required - The key to retrieve the value.

### Request Example
```go
db.Set("my_value", 123).Create(&User{})
```

### Response
#### Success Response
- **value** (interface{}) - The value stored under the key, if it exists.
- **ok** (bool) - Indicates whether the key was found.

#### Response Example
```go
myValue, ok := tx.Get("my_value")
// ok => true
// myValue => 123
```
```

--------------------------------

### Manual connection switching with dbresolver.Write and Use

Source: https://gorm.io/docs/dbresolver.html

Demonstrates manual connection switching using dbresolver.Write and dbresolver.Use to specify the resolver and mode for a query.

```go
// Use Write Mode: read user from sources `db1`  
db.Clauses(dbresolver.Write).First(&user)  
  
// Specify Resolver: read user from `secondary`'s replicas: db8  
db.Clauses(dbresolver.Use("secondary")).First(&user)  
  
// Specify Resolver and Write Mode: read user from `secondary`'s sources: db6 or db7  
db.Clauses(dbresolver.Use("secondary"), dbresolver.Write).First(&user)  
```

--------------------------------

### Install GORM v2

Source: https://gorm.io/docs/v2_release_note.html

Install the GORM v2 package. Note that GORM v2.0.0 is released with git tag v1.20.0.

```go
go get gorm.io/gorm  
// **NOTE** GORM `v2.0.0` released with git tag `v1.20.0`  

```

--------------------------------

### Deleting an object: AfterDelete example

Source: https://gorm.io/docs/hooks.html

Example AfterDelete hook that updates related Address records in the same transaction when the user is confirmed.

```go
// Updating data in same transaction  
func (u *User) AfterDelete(tx *gorm.DB) (err error) {  
  if u.Confirmed {  
    tx.Model(&Address{}).Where("user_id = ?", u.ID).Update("invalid", false)  
  }  
  return  
}  

```

--------------------------------

### Traditional API: Get result as *sql.Row

Source: https://gorm.io/docs/sql_builder.html

Use db.Table or db.Raw to build SQL and get a *sql.Row. The row can be scanned into variables.

```go
// Use GORM API build SQL  
row := db.Table("users").Where("name = ?", "jinzhu").Select("name", "age").Row()  
row.Scan(&name, &age)  
  
// Use Raw SQL  
row := db.Raw("select name, age, email from users where name = ?", "jinzhu").Row()  
row.Scan(&name, &age, &email)  

```

--------------------------------

### Index Hints with UseIndex and ForceIndex

Source: https://gorm.io/docs/advanced_query.html

Use these snippets to guide the database's index selection. The first uses hints.UseIndex to suggest a specific index, while the second uses hints.ForceIndex with ForJoin to force the use of certain indexes for a JOIN operation. Both are applied via db.Clauses and the resulting SQL is shown in comments.

```go
import "gorm.io/hints"  

// Suggesting the use of a specific index  
db.Clauses(hints.UseIndex("idx_user_name")).Find(&User{})  
// SQL: SELECT * FROM `users` USE INDEX (`idx_user_name`)  

// Forcing the use of certain indexes for a JOIN operation  
db.Clauses(hints.ForceIndex("idx_user_name", "idx_user_id").ForJoin()).Find(&User{})  
// SQL: SELECT * FROM `users` FORCE INDEX FOR JOIN (`idx_user_name`,`idx_user_id`)  
```

--------------------------------

### Initialize GORM with existing PostgreSQL connection

Source: https://gorm.io/docs/connecting_to_the_database.html

Initializes a *gorm.DB using an existing database/sql connection. Opens a sql.DB with the "pgx" driver and passes it to postgres.Config's Conn field.

```go
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{})  

```

--------------------------------

### Traditional API: Get result as *sql.Rows

Source: https://gorm.io/docs/sql_builder.html

Use db.Model or db.Raw to build SQL and get *sql.Rows. Iterate with rows.Next() and scan each row.

```go
// Use GORM API build SQL  
rows, err := db.Model(&User{}).Where("name = ?", "jinzhu").Select("name, age, email").Rows()  
defer rows.Close()  
for rows.Next() {  
  rows.Scan(&name, &age, &email)  
  
  // do something  
}  
  
// Raw SQL  
rows, err := db.Raw("select name, age, email from users where name = ?", "jinzhu").Rows()  
defer rows.Close()  
for rows.Next() {  
  rows.Scan(&name, &age, &email)  
  
  // do something  
}  

```

--------------------------------

### Generics API: Get result as *sql.Rows

Source: https://gorm.io/docs/sql_builder.html

Use gorm.G[User](db) or gorm.G[any](db) to build SQL and get *sql.Rows. Iterate with rows.Next() and scan each row.

```go
// Use GORM API build SQL  
rows, err := gorm.G[User](db).Where("name = ?", "jinzhu").Select("name, age, email").Rows(context.Background())  
defer rows.Close()  
for rows.Next() {  
  rows.Scan(&name, &age, &email)  
  
  // do something  
}  
  
// Raw SQL  
rows, err := gorm.G[any](db).Raw("select name, age, email from users where name = ?", "jinzhu").Rows(context.Background())  
defer rows.Close()  
for rows.Next() {  
  rows.Scan(&name, &age, &email)  
  
  // do something  
}  

```

--------------------------------

### FirstOrInit with struct and map conditions

Source: https://gorm.io/docs/advanced_query.html

Shows basic usage of GORM's FirstOrInit with struct and map conditions. If no matching record is found, a new User is initialized with the given conditions; if found, the existing record is loaded into the struct.

```go
// If no User with the name "non_existing" is found, initialize a new User  
var user User  
db.FirstOrInit(&user, User{Name: "non_existing"})  
// user -> User{Name: "non_existing"} if not found  
  
// Retrieving a user named "jinzhu"  
db.Where(User{Name: "jinzhu"}).FirstOrInit(&user)  
// user -> User{ID: 111, Name: "Jinzhu", Age: 18} if found  
  
// Using a map to specify the search condition  
db.FirstOrInit(&user, map[string]interface{}{"name": "jinzhu"})  
// user -> User{ID: 111, Name: "Jinzhu", Age: 18} if found  

```

--------------------------------

### Generics API: Get result as *sql.Row

Source: https://gorm.io/docs/sql_builder.html

Use gorm.G[any](db) to build SQL with GORM API or Raw SQL and get a *sql.Row. The row can be scanned into variables.

```go
// Use GORM API build SQL  
row := gorm.G[any](db).Table("users").Where("name = ?", "jinzhu").Select("name", "age").Row(context.Background())  
row.Scan(&name, &age)  
  
// Use Raw SQL  
row := gorm.G[any](db).Raw("select name, age, email from users where name = ?", "jinzhu").Row(context.Background())  
row.Scan(&name, &age, &email)  

```

--------------------------------

### Traditional API: First, Take, Last

Source: https://gorm.io/docs/query.html

Retrieve a single object using the traditional API. First gets the first record ordered by primary key, Take gets one record without specified order, and Last gets the last record ordered by primary key descending. Returns ErrRecordNotFound if no record is found.

```APIDOC
## Traditional API: First, Take, Last

### Description
Retrieve a single object using the traditional API. First gets the first record ordered by primary key, Take gets one record without specified order, and Last gets the last record ordered by primary key descending. Returns ErrRecordNotFound if no record is found.

### Methods
- `db.First(&user)` - Get the first record ordered by primary key
- `db.Take(&user)` - Get one record, no specified order
- `db.Last(&user)` - Get last record, ordered by primary key desc

### Parameters
- `&user` (pointer to struct) - Required - The destination struct to populate with the retrieved record.

### Return Values
- `result.RowsAffected` - Returns count of records found
- `result.Error` - Returns error or nil

### Error Handling
- Returns `gorm.ErrRecordNotFound` if no record is found.

### Example
```go
// Get the first record ordered by primary key
db.First(&user)
// SELECT * FROM users ORDER BY id LIMIT 1;

// Get one record, no specified order
db.Take(&user)
// SELECT * FROM users LIMIT 1;

// Get last record, ordered by primary key desc
db.Last(&user)
// SELECT * FROM users ORDER BY id DESC LIMIT 1;

result := db.First(&user)
result.RowsAffected // returns count of records found
result.Error        // returns error or nil

// check error ErrRecordNotFound
errors.Is(result.Error, gorm.ErrRecordNotFound)
```
```

--------------------------------

### Initialize GORM with existing GaussDB connection

Source: https://gorm.io/docs/connecting_to_the_database.html

Initializes a *gorm.DB using an existing database/sql connection. Opens a sql.DB with the "gaussdbgo" driver and passes it to gaussdb.Config's Conn field.

```go
import (  
  "database/sql"  
  "gorm.io/driver/gaussdb"  
  "gorm.io/gorm"  
)  
  
sqlDB, err := sql.Open("gaussdbgo", "mydb_dsn")  
gormDB, err := gorm.Open(gaussdb.New(gaussdb.Config{  
  Conn: sqlDB,  
}), &gorm.Config{})  

```

--------------------------------

### Enable GORM Prometheus plugin

Source: https://gorm.io/docs/prometheus.html

Initializes GORM with the Prometheus plugin, configuring DBName as a metrics label, a 15-second refresh interval, optional push address, and an HTTP server on port 8080 to expose metrics. Includes a user-defined MySQL metrics collector for the Threads_running variable.

```go
import (  
  "gorm.io/gorm"  
  "gorm.io/driver/sqlite"  
  "gorm.io/plugin/prometheus"  
)  
  
db, err := gorm.Open(sqlite.Open("gorm.db"), &gorm.Config{})  
  
db.Use(prometheus.New(prometheus.Config{  
  DBName:          "db1", // use `DBName` as metrics label  
  RefreshInterval: 15,    // Refresh metrics interval (default 15 seconds)  
  PushAddr:        "prometheus pusher address", // push metrics if `PushAddr` configured  
  StartServer:     true,  // start http server to expose metrics  
  HTTPServerPort:  8080,  // configure http server port, default port 8080 (if you have configured multiple instances, only the first `HTTPServerPort` will be used to start server)  
  MetricsCollector: []prometheus.MetricsCollector {  
    &prometheus.MySQL{  
      VariableNames: []string{"Threads_running"},  
    },  
  },  // user defined metrics  
}))  
  
```

--------------------------------

### Generics API: First, Take, Last

Source: https://gorm.io/docs/query.html

Retrieve a single object using the generics API. First gets the first record ordered by primary key, Take gets one record without specified order, and Last gets the last record ordered by primary key descending. Returns ErrRecordNotFound if no record is found.

```APIDOC
## Generics API: First, Take, Last

### Description
Retrieve a single object using the generics API. First gets the first record ordered by primary key, Take gets one record without specified order, and Last gets the last record ordered by primary key descending. Returns ErrRecordNotFound if no record is found.

### Methods
- `gorm.G[User](db).First(ctx)` - Get the first record ordered by primary key
- `gorm.G[User](db).Take(ctx)` - Get one record, no specified order
- `gorm.G[User](db).Last(ctx)` - Get last record, ordered by primary key desc

### Parameters
- `ctx` (context.Context) - Required - The context for the operation.

### Error Handling
- Returns `gorm.ErrRecordNotFound` if no record is found.

### Example
```go
ctx := context.Background()

// Get the first record ordered by primary key
user, err := gorm.G[User](db).First(ctx)
// SELECT * FROM users ORDER BY id LIMIT 1;

// Get one record, no specified order
user, err := gorm.G[User](db).Take(ctx)
// SELECT * FROM users LIMIT 1;

// Get last record, ordered by primary key desc
user, err := gorm.G[User](db).Last(ctx)
// SELECT * FROM users ORDER BY id DESC LIMIT 1;

// check error ErrRecordNotFound
errors.Is(err, gorm.ErrRecordNotFound)
```
```

--------------------------------

### Create, Replace, and Drop Views with ViewOption

Source: https://gorm.io/docs/migration.html

Shows how to create views using gorm.ViewOption. The Query field is required. Setting Replace to true uses CREATE OR REPLACE, and CheckOption appends a check clause. SQLite does not support Replace. Also demonstrates dropping a view.

```go
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"  

```

--------------------------------

### Use existing database connection

Source: https://gorm.io/docs/connecting_to_the_database.html

Initializes *gorm.DB with an existing database connection. Open a database/sql connection and pass it via the Conn field in mysql.Config.

```go
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{})  
```

--------------------------------

### FirstOrInit

Source: https://gorm.io/docs/advanced_query.html

Documentation for GORM's FirstOrInit method and its associated Attrs and Assign modifiers.

```APIDOC
## FirstOrInit

### Description
GORM's `FirstOrInit` method fetches the first record that matches given conditions, or initializes a new instance if no matching record is found. It supports both struct and map conditions and can be combined with `Attrs` and `Assign` for additional flexibility.

### Method
FirstOrInit

### Parameters
- **dest** (pointer to struct) - Required - The destination struct where the result will be stored.
- **cond** (struct or map) - Optional - Conditions to match the record. If not provided, the method uses the destination struct's non-zero fields.

### Request Example
```go
var user User
db.FirstOrInit(&user, User{Name: "non_existing"})
```

### Response
- **user** (User) - The initialized or found User struct.

### Response Example
```go
// user -> User{Name: "non_existing"} if not found
// user -> User{ID: 111, Name: "Jinzhu", Age: 18} if found
```

## Using `Attrs` for Initialization

### Description
When no record is found, `Attrs` initializes the struct with additional attributes. These attributes are included in the new struct but are not used in the SQL query.

### Method
Attrs

### Parameters
- **attrs** (struct or map) - Required - Additional attributes to set on the struct when no record is found.

### Request Example
```go
db.Where(User{Name: "non_existing"}).Attrs(User{Age: 20}).FirstOrInit(&user)
```

### Response
- **user** (User) - The initialized or found User struct.

### Response Example
```go
// user -> User{Name: "non_existing", Age: 20} if not found
// user -> User{ID: 111, Name: "Jinzhu", Age: 18} if found
```

## Using `Assign` for Attributes

### Description
The `Assign` method sets attributes on the struct regardless of whether the record is found or not. These attributes are set on the struct but are not used to build the SQL query, and the final data is not saved to the database.

### Method
Assign

### Parameters
- **attrs** (struct or map) - Required - Attributes to set on the struct regardless of record existence.

### Request Example
```go
db.Where(User{Name: "non_existing"}).Assign(User{Age: 20}).FirstOrInit(&user)
```

### Response
- **user** (User) - The initialized or found User struct with assigned attributes.

### Response Example
```go
// user -> User{Name: "non_existing", Age: 20} if not found
// user -> User{ID: 111, Name: "Jinzhu", Age: 20} if found
```
```

--------------------------------

### Build SQL with Statement.Build

Source: https://gorm.io/docs/sql_builder.html

Shows how GORM builds the final SQL in the Query callbacks using Statement.Build with the clause names.

```go
Statement.Build("SELECT", "FROM", "WHERE", "GROUP BY", "ORDER BY", "LIMIT", "FOR")  

```

--------------------------------

### Joins: Load users with company, left join with filter, and subquery join

Source: https://gorm.io/docs/the_generics_way.html

Shows three join examples: loading users who have a company using clause.Has, using LeftJoin with a custom filter on the joined table, and joining using a subquery with AssociationFrom. Demonstrates the new generic Joins API with different join types and conditions.

```go
// Load only users who have a company  
users, err := gorm.G[User](db).Joins(clause.Has("Company"), nil).Find(ctx)  
  
// Use Left Join with custom filter on joined table  
user, err = gorm.G[User](db).Joins(clause.LeftJoin.Association("Company"), func(db gorm.JoinBuilder, joinTable clause.Table, curTable clause.Table) error {  
    db.Where(map[string]any{"name": company.Name})  
    return nil  
}).Where(map[string]any{"name": user.Name}).First(ctx)  
  
// Join using a subquery  
users, err = gorm.G[User](db).Joins(clause.LeftJoin.AssociationFrom("Company", gorm.G[Company](DB).Select("Name")).As("t"),  
    func(db gorm.JoinBuilder, joinTable clause.Table, curTable clause.Table) error {  
        db.Where("?.name = ?", joinTable, u.Company.Name)  
        return nil  
    },  
).Find(ctx)  
```

--------------------------------

### Updated Records Count

Source: https://gorm.io/docs/update.html

Gets the number of rows affected by an update operation.

```APIDOC
## [METHOD] Updated Records Count

### Description
Gets the number of rows affected by an update operation.

### Method
Updates

### Endpoint
`db.Model(User{}).Where("role = ?", "admin").Updates(User{Name: "hello", Age: 18})`

### Parameters
#### Query Parameters
- **role** (string) - Required - The condition to filter records.

#### Request Body
- **Name** (string) - Required - The new value for the name field.
- **Age** (int) - Required - The new value for the age field.

### Request Example
```go
result := db.Model(User{}).Where("role = ?", "admin").Updates(User{Name: "hello", Age: 18})
```

### Response
#### Success Response
- **RowsAffected** (int) - The number of records updated.
- **Error** (error) - Any error that occurred.
```

--------------------------------

### Session NowFunc

Source: https://gorm.io/docs/session.html

Changes the function used to get the current time in GORM operations.

```APIDOC
## [SESSION] NowFunc

### Description
Allows changing the function that returns the current time used by GORM for time-related operations.

### Usage
Use the `NowFunc` option when creating a new session via `db.Session(&Session{NowFunc: func() time.Time { ... }})`.

### Parameters
- **nowFunc** (func() time.Time) - Required - The function that returns the current time.

### Example
```go
db.Session(&Session{
  NowFunc: func() time.Time {
    return time.Now().Local()
  },
})
```
```

--------------------------------

### Preload: Basic, nested, and with sort and per-record limit

Source: https://gorm.io/docs/the_generics_way.html

Shows three preload examples: a basic preload with a condition, preloading nested associations, and preloading with sorting and per-record limit using LimitPerRecord. Demonstrates the new generic Preload API with builder functions.

```go
// A basic Preload example  
users, err := gorm.G[User](db).Preload("Friends", func(db gorm.PreloadBuilder) error {  
    db.Where("age > ?", 14)  
    return nil  
}).Where("age > ?", 18).Find(ctx)  
  
// Preload nested associations  
users, err := gorm.G[User](db).Preload("Friends.Pets", nil).Where("age > ?", 18).Find(ctx)  
  
// Preload with sort and per-record limit  
users, err = gorm.G[User](db).Preload("Friends", func(db gorm.PreloadBuilder) error {  
    db.Select("id", "name").Order("age desc")  
    return nil  
}).Preload("Friends.Pets", func(db gorm.PreloadBuilder) error {  
    db.LimitPerRecord(2)  
    return nil  
}).Find(ctx)  
```

--------------------------------

### Batch count associations with Association().Count

Source: https://gorm.io/docs/associations.html

Gets the count of associations for a batch of records.

```go
db.Model(&users).Association("Team").Count()  
```

--------------------------------

### Row & Rows - Traditional API

Source: https://gorm.io/docs/sql_builder.html

Get result as *sql.Row or *sql.Rows using the Traditional API.

```APIDOC
## Row & Rows - Traditional API

### Description
Get result as *sql.Row or *sql.Rows using the Traditional API.

### Method
Row / Rows

### Usage
```go
// Use GORM API build SQL
row := db.Table("users").Where("name = ?", "jinzhu").Select("name", "age").Row()
row.Scan(&name, &age)

// Use Raw SQL
row := db.Raw("select name, age, email from users where name = ?", "jinzhu").Row()
row.Scan(&name, &age, &email)

// Use GORM API build SQL
rows, err := db.Model(&User{}).Where("name = ?", "jinzhu").Select("name, age, email").Rows()
defer rows.Close()
for rows.Next() {
  rows.Scan(&name, &age, &email)
  // do something
}

// Raw SQL
rows, err := db.Raw("select name, age, email from users where name = ?", "jinzhu").Rows()
defer rows.Close()
for rows.Next() {
  rows.Scan(&name, &age, &email)
  // do something
}
```
```

--------------------------------

### Define a full-featured join table with SetupJoinTable

Source: https://gorm.io/docs/v2_release_note.html

Define a full-featured join table model with Soft Delete, Hooks, and extra fields. PersonAddress must define all required foreign keys or SetupJoinTable will raise an error.

```go
type Person struct {  
  ID        int  
  Name      string  
  Addresses []Address `gorm:"many2many:person_addresses;"`  
}  
  
type Address struct {  
  ID   uint  
  Name string  
}  
  
type PersonAddress struct {  
  PersonID  int  
  AddressID int  
  CreatedAt time.Time  
  DeletedAt gorm.DeletedAt  
}  
  
func (PersonAddress) BeforeCreate(db *gorm.DB) error {  
  // ...  
}  
  
// PersonAddress must defined all required foreign keys, or it will raise error  
err := db.SetupJoinTable(&Person{}, "Addresses", &PersonAddress{})  
```

--------------------------------

### Generate Final SQL with Explain

Source: https://gorm.io/docs/session.html

Shows how to generate the final SQL string using the Dialector's Explain method. Note that the SQL is not always safe to execute and is only used for logs, as it might cause SQL injection.

```go
// NOTE: the SQL is not always safe to execute, GORM only uses it for logs, it might cause SQL injection  
db.Dialector.Explain(stmt.SQL.String(), stmt.Vars...)  
// SELECT * FROM `users` WHERE `id` = 1  
```

--------------------------------

### Row & Rows - Generics API

Source: https://gorm.io/docs/sql_builder.html

Get result as *sql.Row or *sql.Rows using the Generics API.

```APIDOC
## Row & Rows - Generics API

### Description
Get result as *sql.Row or *sql.Rows using the Generics API.

### Method
Row / Rows

### Usage
```go
// Use GORM API build SQL
row := gorm.G[any](db).Table("users").Where("name = ?", "jinzhu").Select("name", "age").Row(context.Background())
row.Scan(&name, &age)

// Use Raw SQL
row := gorm.G[any](db).Raw("select name, age, email from users where name = ?", "jinzhu").Row(context.Background())
row.Scan(&name, &age, &email)

// Use GORM API build SQL
rows, err := gorm.G[User](db).Where("name = ?", "jinzhu").Select("name, age, email").Rows(context.Background())
defer rows.Close()
for rows.Next() {
  rows.Scan(&name, &age, &email)
  // do something
}

// Raw SQL
rows, err := gorm.G[any](db).Raw("select name, age, email from users where name = ?", "jinzhu").Rows(context.Background())
defer rows.Close()
for rows.Next() {
  rows.Scan(&name, &age, &email)
  // do something
}
```
```

--------------------------------

### Get Current Database Name with GORM Migrator

Source: https://gorm.io/docs/migration.html

Returns the name of the currently used database.

```go
db.Migrator().CurrentDatabase()  

```

--------------------------------

### Customize JoinTable with SetupJoinTable

Source: https://gorm.io/docs/many_to_many.html

Defines Person, Address, and a full-featured PersonAddress join table with primary keys, timestamps, soft delete, and a BeforeCreate hook. Calls SetupJoinTable to change Person's Addresses join table to PersonAddress; the join table must define all required foreign keys or an error is raised.

```go
type Person struct {
  ID        int
  Name      string
  Addresses []Address `gorm:"many2many:person_addresses;"`
}

type Address struct {
  ID   uint
  Name string
}

type PersonAddress struct {
  PersonID  int `gorm:"primaryKey"`
  AddressID int `gorm:"primaryKey"`
  CreatedAt time.Time
  DeletedAt gorm.DeletedAt
}

func (PersonAddress) BeforeCreate(db *gorm.DB) error {
  // ...
}

// Change model Person's field Addresses' join table to PersonAddress
// PersonAddress must defined all required foreign keys or it will raise error
err := db.SetupJoinTable(&Person{}, "Addresses", &PersonAddress{})
```
Tokens:
Raw