Declaração de Modelos

O GORM simplifica as interações com o banco de dados mapeando constructo GO para tabelas de banco de dados. Entender como declarar modelos no GORM é fundamental para aproveitar todas as suas capacidades.

Declaração de Modelos

Os modelos são definidos usando constructo normal. Essas structs podem conter campos com tipos básicos do Go, ponteiros ou aliases desses tipos, ou até tipos personalizados, desde que implementem as interfaces Scanner e Valuer do pacote database/sql.

Consider the following example of a User model:

type User struct {
  ID           uint           // Standard field for the primary key
  Name         string         // A regular string field
  Email        *string        // A pointer to a string, allowing for null values
  Age          uint8          // An unsigned 8-bit integer
  Birthday     *time.Time     // A pointer to time.Time, can be null
  MemberNumber sql.NullString // Uses sql.NullString to handle nullable strings
  ActivatedAt  sql.NullTime   // Uses sql.NullTime for nullable time fields
  CreatedAt    time.Time      // Automatically managed by GORM for creation time
  UpdatedAt    time.Time      // Automatically managed by GORM for update time
  ignored      string         // fields that aren't exported are ignored
}

In this model:

• Basic data types like uint, string, and uint8 are used directly.
• Ponteiros para tipos como *‘strings’ e *time. Time indicam campos que podem ser nulos.
• Sal. Ligustrina e sal. Ultime do pacote database/sal são usados para campos que podem ser nulos, oferecendo mais controle.
• CreatedAt e UpdatedAt são campos especiais que o GORM preenche automaticamente com o horário atual quando um registro é criado ou atualizado.
• Non-exported fields (starting with a small letter) are not mapped

In addition to the fundamental features of model declaration in GORM, it's important to highlight the support for serialization through the serializer tag. This feature enhances the flexibility of how data is stored and retrieved from the database, especially for fields that require custom serialization logic, See Serializer for a detailed explanation

Conventions

1. Primary Key: GORM uses a field named ID as the default primary key for each model.

2. Table Names: By default, GORM converts struct names to snake_case and pluralizes them for table names. For instance, a User struct becomes users in the database, and a GormUserName becomes gorm_user_names.

3. Column Names: GORM automatically converts struct field names to snake_case for column names in the database.

4. Campos de Estamparia: O GORM usa campos chamados CreatedAt e UpdatedAt para rastrear automaticamente os horários de criação e atualização dos registros.

Following these conventions can greatly reduce the amount of configuration or code you need to write. However, GORM is also flexible, allowing you to customize these settings if the default conventions don't fit your requirements.

gorm.Model

O GORM fornece uma struct predefinida chamada gorm.Model, que inclui campos comumente usados:

// definição de gorm.Model
<code>type Model struct {
  ID        uint           `gorm:"primaryKey"`
  CreatedAt time.Time
  UpdatedAt time.Time
  DeletedAt gorm.DeletedAt `gorm:"index"`
}</code>

• Embedding in Your Struct: You can embed gorm.Model directly in your structs to include these fields automatically. This is useful for maintaining consistency across different models and leveraging GORM's built-in conventions, refer Embedded Struct

• Fields Included:

  • ID: A unique identifier for each record (primary key).
  • CreatedAt: Automatically set to the current time when a record is created.
  • UpdatedAt: Automatically updated to the current time whenever a record is updated.
  • DeletedAt: Used for soft deletes (marking records as deleted without actually removing them from the database).

Advanced

<span id="field_permission">Field-Level Permission</span>

Exported fields have all permissions when doing CRUD with GORM, and GORM allows you to change the field-level permission with tag, so you can make a field to be read-only, write-only, create-only, update-only or ignored

{% note warn %} NOTE ignored fields won't be created when using GORM Migrator to create table {% endnote %}

type User struct {
  Name string `gorm:"<-:create"` // allow read and create
  Name string `gorm:"<-:update"` // allow read and update
  Name string `gorm:"<-"`        // allow read and write (create and update)
  Name string `gorm:"<-:false"`  // allow read, disable write permission
  Name string `gorm:"->"`        // readonly (disable write permission unless it configured)
  Name string `gorm:"->;<-:create"` // allow read and create
  Name string `gorm:"->:false;<-:create"` // createonly (disabled read from db)
  Name string `gorm:"-"`            // ignore this field when write and read with struct
  Name string `gorm:"-:all"`        // ignore this field when write, read and migrate with struct
  Name string `gorm:"-:migration"`  // ignore this field when migrate with struct
}

<name id="time_tracking">Creating/Updating Time/Unix (Milli/Nano) Seconds Tracking</span>

GORM use CreatedAt, UpdatedAt to track creating/updating time by convention, and GORM will set the current time when creating/updating if the fields are defined

To use fields with a different name, you can configure those fields with tag autoCreateTime, autoUpdateTime

If you prefer to save UNIX (milli/nano) seconds instead of time, you can simply change the field's data type from time.Time to int

type User struct {
  CreatedAt time.Time // Set to current time if it is zero on creating
  UpdatedAt int       // Set to current unix seconds on updating or if it is zero on creating
  Updated   int64 `gorm:"autoUpdateTime:nano"` // Use unix nano seconds as updating time
  Updated   int64 `gorm:"autoUpdateTime:milli"`// Use unix milli seconds as updating time
  Created   int64 `gorm:"autoCreateTime"`      // Use unix seconds as creating time
}

<span id="embedded_struct">Embedded Struct</span>

For anonymous fields, GORM will include its fields into its parent struct, for example:

type Author struct {
  Name  string
  Email string
}

type Blog struct {
  Author
  ID      int
  Upvotes int32
}
// equals
type Blog struct {
  ID      int64
  Name    string
  Email   string
  Upvotes int32
}

For a normal struct field, you can embed it with the tag embedded, for example:

type Author struct {
    Name  string
    Email string
}

type Blog struct {
  ID      int
  Author  Author `gorm:"embedded"`
  Upvotes int32
}
// equals
type Blog struct {
  ID    int64
    Name  string
    Email string
  Upvotes  int32
}

And you can use tag embeddedPrefix to add prefix to embedded fields' db name, for example:

type Blog struct {
  ID      int
  Author  Author `gorm:"embedded;embeddedPrefix:author_"`
  Upvotes int32
}
// equivalente
type Blog struct {
  ID          int64
  AuthorName  string
  AuthorEmail string
  Upvotes     int32
}

<span id="tags">Tags de Campos</span>

Tags are optional to use when declaring models, GORM supports the following tags: Tags are case insensitive, however camelCase is preferred. If multiple tags are used they should be separated by a semicolon (;). Characters that have special meaning to the parser can be escaped with a backslash (\) allowing them to be used as parameter values.

Associations Tags

GORM allows configure foreign keys, constraints, many2many table through tags for Associations, check out the Associations section for details