GORM

GORM 2.0 introduces several significant improvements and new capabilities:

• Core Capabilities: Context support, Batch Insert, Prepared Statement Mode, DryRun Mode, Join Preload, Find To Map, Create From Map, and FindInBatches.
• Transactions: Support for Nested Transactions, SavePoints, and RollbackTo SavePoint.
• Advanced SQL: SQL Builder, Named Arguments, Group Conditions, Upsert, Locking, Optimizer/Index/Comment Hints, SubQuery improvements, and CRUD with SQL Expr and Context Valuer.
• Relationships: Full self-reference relationships, Join Table improvements, and Association Mode for batch data.
• Field Management: Support for multiple fields to track create/update time (including UNIX milli/nano seconds) and Field Permissions (read-only, write-only, create-only, update-only, ignored).
• Extensibility: A new plugin system (with official plugins for multiple databases, read/write splitting, and Prometheus), a new Hooks API, and a new Logger with context support.
• Schema & Migration: A new Migrator supporting foreign keys, smarter AutoMigrate, constraints/checker support, and enhanced index support.
• Naming & Types: Unified Naming strategy (tables, fields, join tables, foreign keys, etc.) and better customized data type support (e.g., JSON).

You can define default values for struct fields using the gorm:"default:value" tag. These values are used by the database when the field is a Go zero-value (e.g., 0, '', false).

Handling Zero-Values

Because GORM treats zero-values as 'empty', it won't send them to the database, which triggers the default tag. If you actually want to save a zero-value (like 0 or false) instead of the default, use a pointer type (e.g., *int) or a sql.Null* type.

Database Functions and Generated Columns

• To use a database function as a default (e.g., uuid_generate_v3()), use the default tag with the function call.
• If you want to skip defining a default value during GORM migrations for a field that has a database-level default or virtual/generated value, use default:(-).
• For virtual/generated columns, you may need to disable create/update permissions using Field-Level Permission.

SQLite Limitation

SQLite does not support default values during batch inserts. If you attempt a batch insert where some records rely on a default tag, it will fail. A workaround is to manually assign the default value within a BeforeCreate hook.

type User struct {
  ID        string `gorm:"default:uuid_generate_v3()"` // database function
  FirstName string
  LastName  string
  Age       uint8
  // Generated column: skip migration definition with default:(-)
  FullName  string `gorm:"->;type:GENERATED ALWAYS AS (concat(firstname,' ',lastname));default:(-);"` 
}

// Workaround for SQLite batch insert default values
func (p *Pet) BeforeCreate(tx *gorm.DB) (err error) {
    if p.Name == "" {
        p.Name = "cat"
    }
    return nil
}

To optimize performance and reduce GC allocations, GORM V2 shares the Statement object during method chaining. Reusing a *gorm.DB instance that has been modified by a method chain (like .Where()) in multiple goroutines is not safe. To safely reuse a *gorm.DB instance in goroutines, you must first call a 'New Session Method' such as WithContext or Session to create a fresh statement instance.

db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})

// SAFE: db is a fresh instance
for i := 0; i < 100; i++ {
  go db.Where(...).First(&user)
}

// NOT SAFE: tx shares the same Statement as other goroutines
tx := db.Where("name = ?", "jinzhu")
for i := 0; i < 100; i++ {
  go tx.Where(...).First(&user)
}

// SAFE: ctxDB is a new session created via WithContext
ctxDB := db.WithContext(ctx)
for i := 0; i < 100; i++ {
  go ctxDB.Where(...).First(&user)
}

// SAFE: Session creates a new instance
tx := db.Where("name = ?", "jinzhu").Session(&gorm.Session{})
for i := 0; i < 100; i++ {
  go tx.Where(...).First(&user)
}

To optimize performance and reduce GC allocations, GORM V2 shares the Statement object during method chains. This means reusing a *gorm.DB instance that has already had conditions applied is not thread-safe.

Safe patterns:

• Using a freshly initialized *gorm.DB.
• Using a *gorm.DB returned by a "New Session Method" such as .WithContext(ctx) or .Session(&gorm.Session{}).

Unsafe pattern:

• Reusing a variable that holds a chain of conditions (e.g., tx := db.Where("name = ?", "jinzhu")) across multiple goroutines.

// SAFE: New initialized DB
for i := 0; i < 100; i++ {
  go db.Where(...).First(&user)
}

// UNSAFE: Reusing a Statement from a chain
tx := db.Where("name = ?", "jinzhu")
for i := 0; i < 100; i++ {
  go tx.Where(...).First(&user) // Race condition!
}

// SAFE: After a New Session Method
ctxDB := db.WithContext(ctx)
for i := 0; i < 100; i++ {
  go ctxDB.Where(...).First(&user)
}

// SAFE: Using Session
tx := db.Where("name = ?", "jinzhu").Session(&gorm.Session{})
for i := 0; i < 100; i++ {
  go tx.Where(...).First(&user)
}