creating-gorm-entity

GORM Entity Creation Skill

Purpose

Generate GORM entity structs that follow the project's Clean Architecture patterns, with proper field tags, relationships, indexing strategies, and soft delete support.

Essential Patterns

1. BaseModel Pattern

All entities MUST embed BaseModel which provides:

• ID uint64 - Primary key with auto-increment
• CreatedAt time.Time - Automatic timestamp
• UpdatedAt time.Time - Automatic timestamp
• DeletedAt gorm.DeletedAt - Soft delete support with index

type BaseModel struct {
    ID        uint64 `gorm:"primaryKey;autoIncrement"`
    CreatedAt time.Time
    UpdatedAt time.Time
    DeletedAt gorm.DeletedAt `gorm:"index"`
}

2. Field Ordering Rules

Fields MUST follow this exact order:

1. BaseModel embedding (always first)
2. Foreign keys (e.g., ProjectID, SymbolID)
3. Required business fields (UID, Label, ClassName, etc.)
4. Optional fields
5. Relationship fields (pointer types with gorm tags)

Example:

type Symbol struct {
    BaseModel                                    // 1. Base embedding
    ProjectID       uint64      `gorm:"..."     // 2. Foreign key
    UID             string      `gorm:"..."     // 3. Required fields
    Label           string      `gorm:"..."
    ClassName       string      `gorm:"..."
    ComponentTarget string      `gorm:"..."
    Version         uint32      `gorm:"..."
    SymbolData      *SymbolData `gorm:"..."     // 4. Relationship
}

3. GORM Tag Structure

Tags MUST follow this pattern: `gorm:"constraint1;constraint2;..." json:"field_name"`

Common constraints:

• `not null` - Required field
• `size:255` - String length limit
• `uniqueIndex:idx_name,priority:N` - Unique composite index
• `index:idx_name,priority:N` - Non-unique composite index
• `foreignKey:FieldName` - FK relationship
• `references:ID` - FK reference
• `constraint:OnDelete:CASCADE` - FK cascade delete

Critical indexing patterns:

// Composite unique index (project_id + uid)
ProjectID uint64 \`gorm:"not null;uniqueIndex:idx_project_uid,priority:1" json:"project_id"\`
UID       string \`gorm:"not null;size:255;uniqueIndex:idx_project_uid,priority:2" json:"uid"\`

// Multiple indexes on same field
ProjectID uint64 \`gorm:"not null;uniqueIndex:idx_project_uid,priority:1;index:idx_project_id,priority:1;index:idx_symbols_project_deleted_at,priority:1" json:"project_id"\`

4. Relationship Patterns

One-to-One with Cascade Delete:

type Symbol struct {
    BaseModel
    // ... other fields ...
    SymbolData *SymbolData \`gorm:"foreignKey:SymbolID;references:ID;constraint:OnDelete:CASCADE" json:"symbol_data,omitempty"\`
}

type SymbolData struct {
    BaseModel
    SymbolID uint64  \`gorm:"not null;uniqueIndex" json:"symbol_id"\`
    Data     *[]byte \`gorm:"not null;type:longblob" json:"data"\`
}

5. Table Naming

MUST provide explicit table name method:

func (Symbol) TableName() string {
    return "symbols"  // plural, snake_case
}

Validation Checklist

When creating a GORM entity, verify:

• BaseModel is embedded as first field
• All foreign keys come before business fields
• Required fields have `not null` tag
• String fields have `size:N` constraint
• Unique combinations use `uniqueIndex` with priorities
• Frequently queried fields are indexed
• Foreign keys have proper relationship tags
• Cascade deletes are configured where needed
• TableName() method returns plural snake_case
• JSON tags use snake_case naming
• Pointer types used for optional relationships
• `omitempty` added to optional json fields

Anti-Patterns

❌ DON'T:

• Use `gorm.Model` (use `BaseModel` instead)
• Forget to index foreign keys
• Use value types for optional relationships
• Mix camelCase and snake_case in json tags
• Omit `TableName()` method
• Put relationship fields before business fields

✅ DO:

• Always embed `BaseModel`
• Index all foreign keys
• Use pointer types for optional relationships
• Use snake_case for all json tags
• Provide explicit `TableName()` method
• Follow field ordering rules