Gorm Conventions

Default Convention

GORM uses a field named ID as the default primary key:

type User struct {
  ID   string // Used as primary key by default
  Name string
}

Custom Primary Key

Use the primaryKey tag on any field:

type Animal struct {
  ID     int64
  UUID   string `gorm:"primaryKey"` // UUID is now the primary key
  Name   string
  Age    int64
}

See the composite_primary_key skill for composite keys.

Table Names

Default Convention

Struct names are converted to snake_case and pluralized:

Override with Tabler Interface

Implement TableName() to specify a custom table name:

type Tabler interface {
  TableName() string
}

type User struct {
  gorm.Model
  Name string
}

func (User) TableName() string {
  return "profiles" // Maps to `profiles` table
}

Note: TableName() result is cached. For dynamic names, use Scopes:

func UserTable(user User) func(tx *gorm.DB) *gorm.DB {
  return func(tx *gorm.DB) *gorm.DB {
    if user.Admin {
      return tx.Table("admin_users")
    }
    return tx.Table("users")
  }
}

db.Scopes(UserTable(user)).Create(&user)

Temporary Table Override

Use Table() method for one-off operations:

// Create table with different name
db.Table("deleted_users").AutoMigrate(&User{})

// Query from different table
var deletedUsers []User
db.Table("deleted_users").Find(&deletedUsers)
// SELECT * FROM deleted_users;

// Delete from different table
db.Table("deleted_users").Where("name = ?", "jinzhu").Delete(&User{})
// DELETE FROM deleted_users WHERE name = 'jinzhu';

Column Names

Default Convention

Field names are converted to snake_case:

type User struct {
  ID        uint      // column: id
  Name      string    // column: name
  Birthday  time.Time // column: birthday
  CreatedAt time.Time // column: created_at
  UserName  string    // column: user_name
}

Custom Column Name

Use the column tag:

type Animal struct {
  AnimalID int64     `gorm:"column:beast_id"`         // beast_id
  Birthday time.Time `gorm:"column:day_of_the_beast"` // day_of_the_beast
  Age      int64     `gorm:"column:age_of_the_beast"` // age_of_the_beast
}

Timestamp Tracking

CreatedAt

Automatically set to current time when creating a record (if value is zero):

db.Create(&user) // Sets CreatedAt to current time

// Provide explicit value to skip auto-setting
user2 := User{Name: "jinzhu", CreatedAt: time.Now()}
db.Create(&user2) // CreatedAt is NOT changed

// Update CreatedAt explicitly
db.Model(&user).Update("CreatedAt", time.Now())

UpdatedAt

Automatically set on create and update:

db.Save(&user) // Sets UpdatedAt to current time

db.Model(&user).Update("name", "jinzhu") // Updates UpdatedAt

// UpdateColumn does NOT update UpdatedAt
db.Model(&user).UpdateColumn("name", "jinzhu") // UpdatedAt unchanged

Disable Auto-tracking

type User struct {
  CreatedAt time.Time `gorm:"autoCreateTime:false"`
  UpdatedAt time.Time `gorm:"autoUpdateTime:false"`
}

Unix Timestamps

Track as Unix seconds, milliseconds, or nanoseconds:

type User struct {
  Created int64 `gorm:"autoCreateTime"`      // Unix seconds
  Updated int64 `gorm:"autoUpdateTime:milli"` // Unix milliseconds
  Modified int64 `gorm:"autoUpdateTime:nano"` // Unix nanoseconds
}

NamingStrategy

For complete control, configure a custom NamingStrategy:

import "gorm.io/gorm/schema"

db, err := gorm.Open(sqlite.Open("test.db"), &gorm.Config{
  NamingStrategy: schema.NamingStrategy{
    TablePrefix:   "prod_",  // Add prefix: User -> prod_users
    SingularTable: true,     // Singular names: User -> prod_user
    NoLowerCase:   true,     // Skip snake_case conversion
    NameReplacer:  strings.NewReplacer("CID", "Cid"), // Custom replacements
  },
})

NamingStrategy Options:

Comprehensive Example

type User struct {
  gorm.Model               // ID, CreatedAt, UpdatedAt, DeletedAt
  Username  string         // column: username
  Email     string         // column: email
  CreatedAt time.Time      // auto-tracked (from gorm.Model)
  UpdatedAt time.Time      // auto-tracked (from gorm.Model)
}

type AdminUser struct {
  ID        uint      `gorm:"primaryKey"`
  AdminName string    `gorm:"column:name"` // custom column name
  Created   int64     `gorm:"autoCreateTime:milli"` // Unix milliseconds
}

func (AdminUser) TableName() string {
  return "admin_portal_users" // custom table name
}

Common Mistakes

When NOT to Use

• When working with a legacy database with inconsistent naming - Instead of fighting conventions, use explicit tags (gorm:"column:...", TableName()) for everything.
• If your team's coding standards conflict with GORM's - Use a custom NamingStrategy to enforce your team's conventions project-wide.
• When table or column names must be dynamic - Conventions are static; use db.Table() or Scopes for dynamic names based on runtime data.
• If you prefer explicit configuration over implicit magic - For maximum clarity, you can choose to define all names and relationships explicitly, ignoring conventions.

References

• Official GORM Documentation: Conventions
• GORM Config: NamingStrategy
• Models: Time Tracking
• Composite Primary Key