GORM — API Surface#

API types#

Library — GORM has no binary, no server, no HTTP endpoints, no gRPC services, no CLI. Its entire surface is a Go library API consumed by user code importing gorm.io/gorm.

Library API#

Public packages exported for use as a library#

API style#

Fluent method chaining on *DB. All chainable and finisher methods return *DB. Errors are accumulated on db.Error rather than returned from each call. Finisher methods trigger execution; chainable methods are lazy.

// typical usage pattern
var users []User
result := db.Where("age > ?", 18).Order("name").Limit(10).Find(&users)
if result.Error != nil { ... }
// result.RowsAffected is also available

Entry point#

func Open(dialector Dialector, opts ...Option) (*DB, error)

gorm.Open is the single constructor. Dialector is supplied by an external driver package (e.g., gorm.io/driver/postgres). opts accepts *Config or anything implementing the Option interface (Apply(*Config) error + AfterInitialize(*DB) error).

Chainable API (chainable_api.go)#

Methods that add constraints/clauses to the current statement; each returns a new *DB (copy-on-write semantics via clone field):

Finisher API (finisher_api.go)#

Methods that execute a database operation:

Create

Query

Update

Delete

Raw / Exec

Transactions

Session / utility methods (gorm.go)#

Association API (association.go)#

Accessed via db.Association("FieldName"):

Migration API (Migrator interface, migrator.go:68)#

Accessed via db.Migrator(). The dialect implements this interface; db.AutoMigrate(dst...) is the common shortcut.

Key method groups:

• Tables: CreateTable, DropTable, HasTable, RenameTable, GetTables, TableType
• Columns: AddColumn, DropColumn, AlterColumn, MigrateColumn, HasColumn, RenameColumn, ColumnTypes
• Indexes: CreateIndex, DropIndex, HasIndex, RenameIndex, GetIndexes
• Constraints: CreateConstraint, DropConstraint, HasConstraint
• Views: CreateView, DropView
• Misc: CurrentDatabase, FullDataTypeOf, GetTypeAliases

Callback / hook registration API (callbacks.go)#

db.Callback() returns a *callbacks exposing six per-operation *processor objects:

db.Callback().Create()   → *processor
db.Callback().Query()    → *processor
db.Callback().Update()   → *processor
db.Callback().Delete()   → *processor
db.Callback().Row()      → *processor
db.Callback().Raw()      → *processor

Each *processor exposes a fluent hook-registration API:

db.Callback().Create().
    Before("gorm:create").
    Register("myapp:hook", func(db *gorm.DB) { ... })

Model lifecycle hooks (BeforeCreate, AfterCreate, BeforeUpdate, etc.) are ordinary methods on the model struct — they are detected via schema/ reflection and registered as callbacks during RegisterDefaultCallbacks.

Plugin API (interfaces.go)#

type Plugin interface {
    Name() string
    Initialize(*DB) error
}

Registered via db.Use(plugin). Stored in Config.Plugins map keyed by Name(). Initialize(*DB) is called once; plugins typically register callbacks or store state via db.InstanceSet.

Generics API (generics.go) — Go 1.18+#

G[T any](db *DB, opts ...clause.Expression) Interface[T] — a type-safe fluent wrapper around *DB:

userDB := gorm.G[User](db)
users, err := userDB.Where("age > ?", 18).Find(ctx)      // returns ([]User, error)
user,  err := userDB.Where("id = ?", 1).First(ctx)       // returns (User, error)
err        = userDB.Create(ctx, &User{Name: "Alice"})

Key interfaces returned:

The generics layer is entirely additive — it wraps the *DB API and returns typed results and errors instead of *DB. It does not change the underlying execution path.

API style summary#

Notable API design observations#

1. Error sink pattern. All finishers return *DB rather than (*DB, error). Callers check result.Error after the call. This enables chaining through errors (db.Where(...).Find(...) can be written in one expression) but departs from idiomatic Go error handling. The generics G[T] API fixes this: all finishers return (T, error).

2. Dual entry points for the same operation. db.Where("id = ?", 1) (string), db.Where(&User{ID: 1}) (struct), and db.Where(map[string]interface{}{"id": 1}) (map) all work. This polymorphism is handled by clause/ AST construction internally, but makes the API surface unusually permissive.

3. ToSQL for testability. db.ToSQL(func(tx *DB) *DB { return tx.Find(&users) }) returns the generated SQL string without executing — a clean API for testing query construction.

4. Callbacks as the public extension mechanism. The hook system (db.Callback().Create().Before(...).Register(...)) is the documented, stable way for plugins and user code to extend behavior. This makes the plugin API composable and avoids inheritance.

5. clause.Expression as an escape hatch. Users can inject raw clause.Expression objects via db.Clauses(...), giving full access to the SQL AST without abandoning the ORM. This is commonly used for database-specific features (ON CONFLICT, RETURNING, FOR UPDATE).