GORM: The Golang ORM

GORM is a full-featured ORM for Golang designed to be developer-friendly. Key capabilities include:

• Associations: Supports Has One, Has Many, Belongs To, Many To Many, Polymorphism, and Single-table inheritance.
• Hooks: Lifecycle callbacks including Before/After Create, Before/After Save, Before/After Update, Before/After Delete, and Before/After Find.
• Eager Loading: Use Preload and Joins to load associated data.
• Transactions: Supports standard transactions, nested transactions, Save Points, and RollbackTo functionality.
• Advanced Querying: Includes a SQL Builder, Upsert, Locking, Optimizer/Index/Comment Hints, and NamedArg. You can perform Search, Update, and Create operations using SQL Expr.
• Data Management: Supports Batch Insert, FindInBatches, Find To Map, and Auto Migrations.
• Extensibility: A flexible plugin API allows for features like a Database Resolver (for Multiple Databases or Read/Write Splitting) and Prometheus integration.

When you call methods like .Where(), .Table(), or .Select() on a generic interface, you transition into a ChainInterface[T]. This interface allows you to build complex SQL queries using a fluent API while maintaining type safety for the eventual execution step.

Key methods in ChainInterface[T]:

• Filtering: .Where(query, args...), .Not(query, args...), .Or(query, args...).
• Pagination/Ordering: .Limit(offset), .Offset(offset), .Order(value).
• Joins & Preloading: .Joins(...) for SQL joins and .Preload(association, query) for eager loading relationships.
• Selection: .Select(query, args...), .Omit(columns...).
• Execution: Once the chain is built, you use ExecInterface[T] methods like .Find(), .First(), or .Scan() to execute the query and retrieve results.

// Example of chaining for a complex query
var users []User
err := gorm.G[User](db). 
    Where("age > ?", 21). 
    Order("name desc"). 
    Limit(10). 
    Find(ctx, &users)

GORM's callback system is managed by processors that hold a collection of callback objects. When a database operation is executed, GORM compiles these callbacks into a sorted list of functions (fns) and executes them sequentially.

Execution Order Control

You can control where your callback sits in the execution chain using these modifiers:

• Before(name string): Executes your callback before the named callback. Use "*" to indicate it should be at the very beginning of the chain.
• After(name string): Executes your callback after the named callback. Use "*" to indicate it should be at the very end of the chain.
• Match(fc func(*DB) bool): A conditional hook. The callback is only added to the execution chain if the match function returns true for the specific *DB instance being processed.

Callback Lifecycle

1. Registration: A callback is added to the processor's list.
2. Compilation: The processor sorts the callbacks based on Before/After constraints and filters out those marked for removal.
3. Execution: During the database operation, the compiled functions are called one by one, passing the current *DB instance.

// Registering a conditional callback
db.Callback().Query().Match(func(d *gorm.DB) bool {
    // Only run this callback if we are querying the 'users' table
    return d.Statement.Table == "users"
}).Register("conditional_query_log", func(d *gorm.DB) {
    fmt.Println("Querying users table...")
})

GORM uses a callback system to allow developers to hook into the lifecycle of database operations. You can register custom functions that execute before or after specific database actions like Create, Query, Update, Delete, Row, or Raw.

Callback Processors

Each major operation has its own processor. You access them via the following methods on the *gorm.DB instance:

• Create()
• Query()
• Update()
• Delete()
• Row()
• Raw()

Registering a Callback

To register a callback, use the Register method on a processor. You can chain Before or After to control the execution order relative to existing callbacks.

Managing Callbacks

• Replace(name string, fn func(*DB)): Replaces an existing callback with a new one.
• Remove(name string): Removes an existing callback by name.
• Match(fc func(*DB) bool): Allows you to register a callback that only executes if the provided predicate function returns true for the current *DB instance.

// Example: Registering a 'before create' callback
db.Callback().Create().Before("gorm:create").Register("my_custom_callback", func(d *gorm.DB) {
    fmt.Println("About to create record...")
})

When starting a transaction on a PreparedStmtDB using BeginTx, you receive a PreparedStmtTX. This type ensures that prepared statements used within the transaction are correctly scoped to that transaction.

Key Behaviors:

• BeginTx(ctx, opt): Starts a transaction. Returns a PreparedStmtTX which wraps both the transaction and the parent PreparedStmtDB.
• Commit(): Commits the transaction.
• Rollback(): Rolls back the transaction.
• ExecContext, QueryContext, QueryRowContext: These methods within the transaction use tx.StmtContext to ensure the cached statement is executed within the transaction's context.

ctx := context.Background()

// Start a transaction
presStmtTx, err := db.BeginTx(ctx, nil)
if err != nil {
    panic(err)
}

// Use the transaction
err = presStmtTx.QueryRowContext(ctx, "SELECT name FROM users WHERE id = ?", 1).Scan(&name)
if err != nil {
    presStmtTx.Rollback()
}

// Commit the transaction
err = presStmtTx.Commit()