Using Models

Models provide thread-safe field access through typed methods. All operations use .Set() and .Get() patterns.

Creating Model Instances

Basic Constructor

// Create new model instance
user := user.New()

Typed Constructor

For specific types (like joined models):

// Create a new model instance for a specific type
joinedUser := user.NewType[*user.JoinedUser]()

Setting Field Values

All fields use .Set(value) method:

user.Name.Set("Alice")
user.Email.Set("alice@example.com")
user.Age.Set(30)
user.Status.Set(constants.StatusActive)

Getting Field Values

All fields use .Get() method:

name := user.Name.Get()      // "Alice"
email := user.Email.Get()    // "alice@example.com"
age := user.Age.Get()        // 30
status := user.Status.Get()  // constants.StatusActive

Working with Struct Fields

Struct fields (JSONB columns) have additional methods:

Setting Struct Values

type Bookmarks struct {
    FavoriteID types.UUID `json:"favorite_id"`
    RecentIDs  []types.UUID `json:"recent_ids"`
}

user.Bookmarks.Set(&Bookmarks{
    FavoriteID: uuid1,
    RecentIDs:  []types.UUID{uuid2, uuid3},
})

Getting Struct Values

// .Get() returns value and error
bookmarks, err := user.Bookmarks.Get()
if err != nil {
    return err
}

// .GetI() ignores errors (use when error checking not needed)
bookmarks := user.Bookmarks.GetI()

Field Types Reference

Field Type	Go Type	Database Type	Use Case
StringField	string	text	Text/string columns
UUIDField	types.UUID	uuid	UUID columns
IntField	int	integer/smallint	Integer/boolean (0/1) columns
DecimalField	decimal.Decimal	numeric	Decimal/numeric columns
IntConstantField[T]	T (int-based)	smallint	Enum/constant fields
StructField[T]	T	jsonb	JSONB/struct columns

Thread Safety

All field operations are thread-safe by default. Models use internal mutexes to protect concurrent access.

// Safe to use from multiple goroutines
go user.Name.Set("Alice")
go user.Email.Set("alice@example.com")

Common Patterns

Updating Multiple Fields

user := user.New()
user.Name.Set("Alice")
user.Email.Set("alice@example.com")
user.Age.Set(30)
user.Status.Set(constants.StatusActive)

err := user.Save(ctx)
if err != nil {
    return err
}

Reading and Modifying

user, err := user.GetByID(ctx, userID)
if err != nil {
    return err
}

// Modify fields
currentAge := user.Age.Get()
user.Age.Set(currentAge + 1)

err = user.Save(ctx)
if err != nil {
    return err
}

Working with Optional Fields

Fields with null:"true" can be set to nil:

// Set to nil
user.MiddleName.SetNull()

// Check if nil
user.MiddleName.IsNull()

File Organization Standards

• queries.go - All specific queries
• functions.go - All model functions (not methods)
• Methods - Use pointer receivers with this as the receiver variable

Related Skills

• model-queries - Building database queries
• model-conventions - Standards and field type reference

Additional resources

• For usage examples, see examples.md