Built a linter to catch GORM's unsafe *gorm.DB reuse

[mpyw]

Have you ever been bitten by GORM's reuse trap?

Hey GORM community! 👋

I think many of us have experienced this frustrating bug at least once - especially if you're maintaining codebases using GORM's Traditional API (and let's be honest, that's most of us! 😅):

func GetUsers(db *gorm.DB, filters UserFilters) {
    query := db.Where("active = ?", true)
    
    if filters.Premium {
        query.Where("premium = ?", true).Find(&premiumUsers)
    }
    
    // Surprise! Conditions accumulate unexpectedly 😱
    query.Where("country = ?", filters.Country).Find(&allUsers)
}

The problem: GORM's Traditional API chain methods (Where, Order, etc.) create shallow clones that share internal state. When the same mutable *gorm.DB branches into multiple queries, they interfere with each other. This is documented in GORM's official guide on Method Chaining, but it's easy to miss in real-world code with complex control flows.

Note about Generics API: GORM's Generics API (gorm.G[T], available since v1.30.0) avoids this issue by design - it returns different types (Interface[T], ChainInterface[T]) instead of *gorm.DB. However, many production codebases still use (and will continue to maintain for years) the Traditional API. This linter is specifically for those real-world scenarios.

Introducing gormreuse - A Static Analysis Linter

I've built a linter that detects these unsafe reuse patterns at compile time: github.com/mpyw/gormreuse

Key Features

• SSA-based tracking: Uses Static Single Assignment form to track *gorm.DB values through complex code paths (loops, conditionals, function calls, closures, defer/goroutines)
• Mutable branching detection: Warns when a mutable DB instance branches into multiple queries
• Automatically excludes Generics API: Only analyzes Traditional API (*gorm.DB) - Generics API types are ignored
• Practical directives:
  • //gormreuse:pure - Mark helpers that don't pollute DB arguments
  • //gormreuse:immutable-return - Mark DB connection/transaction wrappers that return fresh instances
  • //gormreuse:ignore - Suppress false positives when needed

Example Detection

func BadExample(db *gorm.DB) {
    q := db.Where("status = ?", "active")
    
    q.Where("role = ?", "admin").Find(&admins)  // First branch - OK
    q.Where("role = ?", "user").Find(&users)    // Second branch - ⚠️ Detected!
}

func GoodExample(db *gorm.DB) {
    // Option 1: Use Session() at the end to create immutable root
    q := db.Where("status = ?", "active").Session(&gorm.Session{})
    
    q.Where("role = ?", "admin").Find(&admins)  // OK - q is immutable
    q.Where("role = ?", "user").Find(&users)    // OK - each creates new Statement
    
    // Option 2: Chain directly without intermediate variable
    db.Where("status = ?", "active").Where("role = ?", "admin").Find(&admins)
    db.Where("status = ?", "active").Where("role = ?", "user").Find(&users)
}

Handling Custom Helpers

The linter treats user-defined functions conservatively by default, but you can annotate them:

// DB connection helper - returns fresh instance
//gormreuse:immutable-return
func GetDB(ctx context.Context) *gorm.DB {
    return db.WithContext(ctx)
}

// Scope helper - doesn't pollute argument (Session creates isolation)
//gormreuse:pure
func WhereActive(db *gorm.DB) *gorm.DB {
    return db.Session(&gorm.Session{}).Where("active = ?", true)
}

func Example(ctx context.Context) {
    q := GetDB(ctx)           // q is immutable (annotated)
    q = WhereActive(q)        // q becomes mutable (returns mutable chain)
    
    q.Where("x").Find(&x)     // First branch - OK
    q.Where("y").Find(&y)     // Second branch - ⚠️ Still detected!
}

Installation

go install github.com/mpyw/gormreuse/cmd/gormreuse@latest
go vet -vettool=$(which gormreuse) ./...

Or integrate with golangci-lint (supports --build-tags).

---

I think this could be genuinely useful for teams working with GORM's Traditional API, especially in large codebases where these bugs can hide. The linter has been tested on complex scenarios including closures, deferred calls, and control flow.

Would love to hear your thoughts! Have you encountered this issue? Would a linter like this be helpful in your workflow? Any feedback or suggestions are welcome! 🙏

Repository: https://github.com/mpyw/gormreuse

P.S. This linter was developed with the help of Claude Code 🤖